@seroh/template-npm-package NPM

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.

Quick Start
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.