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.
- TypeScript 7 with strict, modern configuration
- Native ESM support
- Node.js v26 runtime
- pnpm package manager
- Vitest for fast unit tests and coverage
- Oxlint for static analysis
- Oxfmt and EditorConfig for consistent formatting
- GitHub Actions CI workflow
- Mise for reproducible local toolchains
- Minimal example source code and unit test
- AGENTS.md with example project guidance for AI coding agents
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.
- 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
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.
This project is intended to be used with the latest Active LTS release of Node.js.
To start, just click the Use template link (or the green button). Start adding your code in the src directory and unit tests in the __tests__ directory.
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"
pnpm installDownload 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.zipstart- 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,format- reformat source files,format:check- check source file formatting without modifying them
Oxlint uses its default rules and severities, with the Vitest plugin enabled for tests. Intentional overrides report unused variables and explicit any as errors, and missing TypeScript return types as warnings. Generated build, temporary, and coverage files are ignored.
pnpm significantly speeds up package installation while saving massive amounts of disk space. Also, its strict dependency isolation prevents "ghost dependencies", while strict defaults ensure better supply-chain safety without extra tooling.
I recommend using Oxlint and Oxfmt for linting and formatting. By running as self-contained native binaries built on Rust, Oxlint and Oxfmt significantly outperform ESLint and Prettier while stripping away dozens of Node.js dependencies. Their zero-config defaults eliminate complex plugin chains, shrinking the attack surface and ensuring conflict-free integration across modern JavaScript and TypeScript environments.
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.
Note
This project previously used Volta for toolchain management. Volta is no longer maintained (see volta-cli/volta#2080), so it was replaced with Mise, which the Volta maintainers recommend.
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.
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. With recent versions of Claude Code natively supporting AGENTS.md, every major AI coding tool now supports this format.
The included guidelines are just an example of behavioural instructions for modern models. You should write your own, project-specific context and instructions.
This template uses native ESM. Please do not open issues for questions regarding CommonJS or ESM on this repo.
TypeScript inlines helper functions (e.g. for async/await, spread, destructuring) into every output file that needs them, and importHelpers: true plus tslib make all files share a single imported copy instead, deduplicating repeated runtime code across the build.
Support this project by becoming a sponsor.
Licensed under the APLv2. See the LICENSE file for details.
