📦 ts-npm-package-boilerplate

TypeScript NPM Module Boilerplate

Report Bug · Request Feature

Tested on

Did you like the project? Please consider a donation to help improve!

TypeScript NPM Module Boilerplate ✨

---

Table of Contents

• Overview
• Features
• Prerequisites
• Quick Start
• Usage
• Scripts
• Project Structure
• CI/CD
• Publishing
• Contributing
• License

Overview

Starter template for building and publishing typed Node.js libraries to npm using TypeScript, Jest, ESLint, and Prettier. It ships with sensible defaults, CI workflows, coverage upload to Codecov, and a minimal example implementation.

Features

• TypeScript build with declaration output to lib/.
• Jest test setup with ts-jest and coverage.
• ESLint + Prettier configured for TS.
• GitHub Actions for tests/coverage and npm publish on release.
• Prepublish hooks to lint and test before publishing.

Prerequisites

• Node.js 18+ (LTS recommended).
• npm 9+.

Quick Start

Option A — Use as template (recommended):

1. Click “Use this template” on GitHub to create your repo.
2. Clone your new repo and install dependencies:

git clone https://github.com/<your-username>/<your-repo>.git
cd <your-repo>
npm install

Option B — Clone this repository directly:

git clone https://github.com/hebertcisco/ts-npm-package-boilerplate
cd ts-npm-package-boilerplate
npm install
# Optional: reset git history
rm -rf .git && git init && git add . && git commit -m "Initial commit"

Then update package.json fields: name, version, description, author, repository, bugs, and homepage.

Edit the icon on Figma if you want:

Usage

This template includes a simple Uuid helper as an example. After building, the entry point is lib/index.js with types in lib/index.d.ts.

Example:

import uuid from 'ts-npm-package-boilerplate';
// or: import { Uuid } from 'ts-npm-package-boilerplate';

const id = uuid.v4();
console.log(id); // 3f52c6f8-7a8e-4c04-b4a0-bf5f7d3e9f0a

During development (from this repo):

import uuid from './src';

Scripts

• npm run build: Compile TypeScript to lib/.
• npm test: Run tests with Jest.
• npm run lint: Lint code with ESLint.
• npm run lint:fix: Fix lint issues.
• npm run format: Format with Prettier.

Important lifecycle hooks:

• prepare: Runs npm run build so the package is built before pack/publish.
• prepublishOnly: Runs tests and linting before npm publish.
• version: Formats and stages changes when bumping version with npm version.

Project Structure

• src/: Source code (TypeScript).
• src/helpers/uuid.ts: Example implementation.
• src/__tests__/: Jest tests.
• lib/: Compiled JS + type definitions (generated).

CI/CD

GitHub Actions are included:

• .github/workflows/coverage.yml: Runs tests on Node 18/20/22 and uploads coverage to Codecov. Set CODECOV_TOKEN secret for private repos.
• .github/workflows/npm-publish.yml: On GitHub release creation, builds and publishes to npm. Set NPM_TOKEN secret with publish rights.

Publishing

1. Ensure you are logged in: npm login.
2. Update package.json metadata and ensure files includes what you want to publish.
3. Bump version: npm version patch|minor|major.
4. Publish: npm publish.

Alternatively, create a GitHub Release and let the publish workflow handle it (requires NPM_TOKEN).

🤝 Contributing

Contributions, issues, and feature requests are welcome. Check the issues page: https://github.com/hebertcisco/ts-npm-package-boilerplate/issues

Show your support

Give a ⭐️ if this project helps you!

Or buy me a coffee 🙌🏾

📝 License

Copyright © 2025 @hebertcisco.

This project is MIT licensed.