Template: NPM Package

This is a template repository which you can use to quickly bootstrap your own NPM package.

Features

• Static Typing: Uses TypeScript for improved type safety and a better developer experience
• Testing: Pre-configured Jest setup for writing and running unit tests efficiently
• Linting: Leverages ESLint to catch potential bugs and enforce coding standards
• Auto-Formatting: Ensures consistent code style with automated formatting using Prettier
• Continuous Integration (CI): Pre-configured GitHub Actions for linting, testing, building, and formatting in CI environments
• Git Hooks: Husky-managed Git hooks to run scripts before commits, pushes, and other Git actions, ensuring code quality
• Automated Publishing: Uses Semantic Release to automate package versioning and publishing.

Table of Content

• Quick Start
  • Clone the template
  • Set Up NPM Authentication
  • Install dependencies
  • Set package metadata
  • Publish your package
• Available NPM Scripts

Quick Start

1. Clone the template

The fastest way is to use GitHub CLI:

# Create a new repository using a template and clone it
gh repo create new-repo-name --template serohman/npm-typescript-module
gh repo clone new-repo-name

Or refer to the official guide for creating repositories from a template.

2. Set up NPM authentication

You need to generate an NPM access token and save it as a GitHub Action Secret, under the key name NPM_TOKEN

Use GitHub CLI

# A prompt for entering the npm token will appear
gh secret set NPM_TOKEN

Or set the secret via the web UI by navigating to your repository's GitHub page, and then: Settings > Secrets and variables > Actions > New repository secret.

3. Install dependencies

npm install

4. Set package metadata

Open package.json and fill out all the relevant fields:

• name
• author
• description
• tags
• license
• publishConfig.access (Set to private to make your package private)

5. Publish your package

To publish your package, switch to the release branch, then create and push a semantic commit with the changes you've made to package.json. Once the changes are pushed, GitHub Actions will automatically publish your package.

git checkout -b "release"
git stage .
git commit -m "feat: Setup package"
git push --set-upstream origin release

And voilà!🎉 The moment new changes hit the release branch, GitHub Actions will pick them up and publish a new release on NPM.

Available NPM Scripts

General

These commands are used during the development process to build, test, lint, and format the code.

• start: Runs the build script.
• build: Compiles the TypeScript code and watches for changes.
• test: Runs Jest in watch mode.
• lint: Runs ESLint on the ./src directory.
• format: Formats the code in the ./src directory using Prettier.

Precommit Hooks

These commands are executed before a commit is made to ensure code quality and consistency. They check for issues in the staged files, attempt to fix them automatically (using the --fix flag), and display an error if the issues cannot be fixed. If any problems remain unresolved, the commit is prevented.

• precommit: Runs lint-staged to check staged files.
• precommit:format: Formats staged files using Prettier.
• precommit:lint: Fixes linting issues in staged files using ESLint.
• precommit:test: Runs Jest on related tests for staged files.
• precommit:typecheck: Type checks the code without emitting output.

Continuous Integration

These commands are executed by GitHub Actions on the release branch. Each time a change is pushed to the release branch, these actions are triggered. If any action fails, the release process is halted until the issues are resolved.

• ci:lint: Runs ESLint with a CI-specific configuration.
• ci:test: Runs Jest with a CI-specific configuration.
• ci:build: Builds the TypeScript project.
• ci:format: Checks code formatting using Prettier.