node-typescript-boilerplate

A modern Node.js TypeScript starter template for building backend services, CLIs, workers, APIs, and libraries with a clean, production-ready toolchain.

This boilerplate is intentionally small, strict, and boring: no framework lock-in, no unnecessary runtime dependencies, and no hidden magic. Clone it, click Use template, or fork it when you want a reliable TypeScript foundation for a new Node.js project.

What's included

• TypeScript 6 with strict, modern configuration
• Native ESM support
• Node.js 24 runtime target
• Vitest for fast unit tests and coverage
• ESLint and typescript-eslint for static analysis
• Prettier and EditorConfig for consistent formatting
• GitHub Actions CI workflow
• Mise for reproducible local toolchains
• Minimal example source code and unit test
• AGENTS.md with project guidance for AI coding agents such as GitHub Copilot, Claude Code, Codex-style agents, and other agentic development tools

AI coding agent ready

This repository includes AGENTS.md, giving coding agents clear instructions about TypeScript style, testing expectations, Node.js conventions, dependency policy, and verification steps.

Why this template?

Most starters are either too empty or too opinionated. This one gives you the boring essentials: TypeScript, linting, formatting, testing, CI, reproducible tooling, and agent instructions — without forcing Express, NestJS, Fastify, serverless tooling, databases, ORMs, or deployment platforms on you.

⭐ If this template saves you setup time, please star the repo to help others discover it.

Good fit for

• Starting a new Node.js + TypeScript backend
• Creating a framework-free TypeScript service
• Building a CLI, worker, API, job processor, or library
• Using Vitest instead of Jest
• Using native ESM instead of CommonJS
• Giving AI coding agents clear project instructions from day one

What this is not

This template does not include Express, NestJS, Fastify, serverless deployment, databases, ORMs, authentication, Docker, or cloud-specific configuration. It is a clean foundation you can build on.

Getting started

This project is intended to be used with the latest Active LTS release of Node.js.

(Recommended) Use as a repository template

To start, just click the Use template link (or the green button). Start adding your code in the src and unit tests in the __tests__ directories.

Clone repository

To start a new project from this template without the upstream history or remote:

git clone --depth 1 https://github.com/jsynowiec/node-typescript-boilerplate my-project
cd my-project
rm -rf .git && git init && git add -A && git commit -m "Initial commit"
npm install

Download

Download and unzip the current main branch or one of the tags:

wget https://github.com/jsynowiec/node-typescript-boilerplate/archive/main.zip -O node-typescript-boilerplate.zip
unzip node-typescript-boilerplate.zip && rm node-typescript-boilerplate.zip

Available scripts

• start - run the built application,
• clean - remove coverage, build, and tmp directories,
• prebuild - lint and type-check before building,
• check-types - type-check without emitting output,
• build - transpile TypeScript to ES2024,
• build:watch - interactive watch mode to automatically transpile source files,
• build:release - clean and transpile for release (no source maps, comments removed),
• lint - lint source files and tests,
• test - run tests,
• test:coverage - run tests with coverage reporting,
• test:watch - interactive watch mode to automatically re-run tests,
• prettier - reformat source files,
• prettier:check - check source file formatting without modifying

Additional information

Why include Mise

I recommend installing Mise and using it to manage your project's toolchain and environment.

Mise keeps track of your environment, ensuring the tools you use respect the settings of the project you're working on. This means you don't have to worry about changing your installed software when switching between projects.

Why Vitest instead of Jest

I recommend using Vitest for unit and integration testing of your TypeScript code.

Vitest is generally faster than Jest, especially for large test suites. Additionally, Vitest has native support for ES modules, is easier to configure, and offers a better developer experience when used with TypeScript. For example, it simplifies working with mocks, spies, and types.

Nevertheless, the choice of specific tooling always depends on the project's specific requirements and characteristics.

Why AGENTS.md over individual configs

The AGENTS.md format has emerged as a community-driven standard, stewarded by the Agentic AI Foundation under the Linux Foundation. It is the closest thing to a universal config file, promoting consistency across AI coding tools.

The included guidelines are just an example. You should write your own, project-specific context and instructions.

ES Modules

This template uses native ESM. Make sure to read this, and this first. If your project requires CommonJS, you will have to convert to ESM.

Please do not open issues for questions regarding CommonJS or ESM on this repo.

Why include tslib

TypeScript inlines helper functions (e.g. for async/await, spread, destructuring) into every output file that needs them, and importHelpers: true plus tslib makes all files share a single imported copy instead, deduplicating repeated runtime code across the build.

Sponsor

Support this project by becoming a sponsor.

License

Licensed under the APLv2. See the LICENSE file for details.