NPM Template

A modern NPM package template built with TypeScript, featuring a class and a command-line interface (CLI). Pre-configured with Jest, ESLint, Prettier, and a GitHub Action workflow for automated publishing to NPM.

📋 Table of Contents

• Features
• Prerequisites
• Getting Started
• Usage
• Publishing to NPM
• Contributing
• License

✨ Features

• TypeScript: Write type-safe JavaScript with modern ECMAScript features.
• Jest: Unit testing framework for reliable code quality.
• Prettier & ESLint: Enforces consistent code style and catches potential errors.
• Publish Action: Automates publishing to NPM on git push if version changed.

📦 Prerequisites

• Node.js (v16 or higher)
• npm (comes with Node.js)
• An NPM account (for publishing)

🚀 Getting Started

1. Clone the Repository

   git clone https://github.com/ganemedelabs/npm-template.git
   cd npm-template

2. Install Dependencies and Build the Project

   npm install
   npm run build
   
   # link the package to test it locally
   npm link

3. Customize Your Package

   • Update package.json with your package's details (e.g., name, description, author).
   • Modify src/ files to implement your package's functionality.

🔧 Usage

As a CLI

npm-template greet Alice
# Output: Hello, Alice!

npm-template add 2 3
# Output: Result: 5

As a Module

import Template from "npm-template";

const template = new Template("Bob");
console.log(template.greet()); // "Hello, Bob!"
console.log(template.add(2, 3)); // 5

🚢 Publishing to NPM

Publishing is handled automatically by a GitHub Action when you push changes to the main branch with a new version name.

Features

• Triggers on push to the main branch.
• Checks out the repository code with full Git history.
• Sets up Node.js 20 and configures the NPM registry.
• Installs project dependencies.
• Compares the current package.json version with the latest NPM version.
• Builds the project if the version has changed.
• Publishes the package to NPM with public access if the version has changed.

Setup

1. Update package.json

   • Set the name field (e.g., @yourusername/npm-template).
   • Increment the version field for each release you want to publish to NPM.

2. Generate an NPM Access Token

   • Go to your NPM account: Access Tokens > Generate New Token > Granular Access Token
   • In Packages and Scopes section, select Read and write access for all packages.
   • If the package is scoped, select Read and write in the Organizations section for the specific organization.
   • Copy the generated token.

3. Add Your NPM Token to GitHub

   • Go to your GitHub repository: Settings > Secrets and variables > Actions
   • Add a new repository secret named NPM_TOKEN with the token value from NPM.

4. Push to Main

   • Make your changes, update the version, and push to the main branch.
   • The publish.yml GitHub Action will publish your package if the version is new or it hasn't been published yet.

Notes

• Triggers on push to main
• Publishes only if the version has changed
• Uses the NPM_TOKEN for authentication

🤝 Contributing

Feel free to submit issues or pull requests to improve this template!

📜 License

This project is licensed under the MIT License. See the LICENSE file for details.