node-typescript-boilerplate
Production-ready Node.js TypeScript boilerplate: ESM, Vitest, ESLint, Prettier, GitHub Actions, Mise, and AGENTS.md included.
Top Related Projects
A reference example for TypeScript and Node with a detailed README describing how to use the two together.
TypeScript execution and REPL for node.js
Starter kit with zero-config for building a library in TypeScript, featuring RollupJS, Jest, Prettier, TSLint, Semantic Release, and more!
The most basic TypeScript starter I could think of
A delightful way to building a RESTful API with NodeJs & TypeScript by @w3tecch
Quick Overview
The jsynowiec/node-typescript-boilerplate is a minimalist, ready-to-use template for building Node.js projects with TypeScript. It provides a solid foundation for developing scalable and maintainable applications, including essential tools for testing, linting, and formatting.
Pros
- Pre-configured with TypeScript, Jest, ESLint, and Prettier for immediate development
- Includes GitHub Actions for automated testing and CI/CD
- Supports both CommonJS and ES modules
- Regularly updated to maintain compatibility with the latest Node.js LTS versions
Cons
- May include more tools than needed for very simple projects
- Requires familiarity with TypeScript and Node.js ecosystem
- Limited customization options out of the box
- May need additional configuration for complex project structures
Getting Started
-
Clone the repository:
git clone https://github.com/jsynowiec/node-typescript-boilerplate.git my-project cd my-project -
Install dependencies:
npm install -
Start development:
npm run start:dev -
Build and run the project:
npm run build npm run start -
Run tests:
npm test
These instructions will set up the boilerplate and allow you to start developing your Node.js TypeScript project immediately.
Competitor Comparisons
A reference example for TypeScript and Node with a detailed README describing how to use the two together.
Pros of TypeScript-Node-Starter
- More comprehensive setup with Express.js, MongoDB, and authentication
- Includes detailed documentation and explanations for each feature
- Offers a production-ready structure with MVC pattern implementation
Cons of TypeScript-Node-Starter
- Potentially overwhelming for beginners due to its complexity
- Might include unnecessary features for simpler projects
- Less frequently updated compared to node-typescript-boilerplate
Code Comparison
TypeScript-Node-Starter:
import express from "express";
import compression from "compression";
import session from "express-session";
import bodyParser from "body-parser";
import lusca from "lusca";
node-typescript-boilerplate:
import { add } from './main';
describe('add', () => {
it('adds two numbers', () => {
expect(add(1, 2)).toBe(3);
});
});
The TypeScript-Node-Starter example shows the setup for an Express.js application with various middleware, while the node-typescript-boilerplate example demonstrates a simple test setup using Jest.
TypeScript-Node-Starter is better suited for full-stack applications with a more complex structure, while node-typescript-boilerplate provides a minimal setup ideal for smaller projects or as a starting point for custom configurations.
TypeScript execution and REPL for node.js
Pros of ts-node
- Directly executes TypeScript files without separate compilation step
- Supports REPL for interactive TypeScript execution
- Integrates seamlessly with Node.js ecosystem and tools
Cons of ts-node
- May have slower startup time for large projects
- Limited customization options for TypeScript compilation process
- Potential performance overhead in production environments
Code Comparison
ts-node:
// Execute TypeScript directly
import { sum } from './math';
console.log(sum(5, 3));
node-typescript-boilerplate:
// Compile TypeScript to JavaScript first
"scripts": {
"build": "tsc",
"start": "node build/index.js"
}
Summary
ts-node offers a more streamlined development experience with direct TypeScript execution and REPL support, making it ideal for quick prototyping and smaller projects. node-typescript-boilerplate provides a more structured setup with separate build and run steps, which can be beneficial for larger projects and production deployments. The choice between the two depends on project requirements, team preferences, and performance considerations.
Starter kit with zero-config for building a library in TypeScript, featuring RollupJS, Jest, Prettier, TSLint, Semantic Release, and more!
Pros of typescript-library-starter
- More comprehensive tooling setup, including automatic documentation generation with TypeDoc
- Includes semantic-release for automated versioning and publishing
- Provides a more opinionated structure for library development
Cons of typescript-library-starter
- May be overly complex for simpler projects or beginners
- Less frequently updated compared to node-typescript-boilerplate
- Some included tools might not be necessary for every project
Code Comparison
node-typescript-boilerplate:
{
"scripts": {
"start": "node build/src/main.js",
"clean": "rimraf coverage build tmp",
"build": "tsc -p tsconfig.json",
"build:watch": "tsc -w -p tsconfig.json",
"lint": "eslint . --ext .ts,.tsx"
}
}
typescript-library-starter:
{
"scripts": {
"lint": "tslint --project tsconfig.json -t codeFrame 'src/**/*.ts' 'test/**/*.ts'",
"prebuild": "rimraf dist",
"build": "tsc --module commonjs && rollup -c rollup.config.ts && typedoc --out docs --target es6 --theme minimal --mode file src",
"start": "rollup -c rollup.config.ts -w",
"test": "jest --coverage",
"test:watch": "jest --coverage --watch"
}
}
The code comparison shows that typescript-library-starter includes more advanced build and test configurations, while node-typescript-boilerplate keeps it simpler with basic TypeScript compilation and linting.
The most basic TypeScript starter I could think of
Pros of simple-typescript-starter
- Simpler setup with fewer dependencies, making it easier for beginners to understand and use
- Includes a basic Express server setup, which is useful for web application development
- Uses ts-node-dev for faster development and automatic restarting
Cons of simple-typescript-starter
- Less comprehensive testing setup compared to node-typescript-boilerplate
- Fewer pre-configured tools and scripts for code quality and formatting
- Less frequent updates and maintenance compared to node-typescript-boilerplate
Code Comparison
simple-typescript-starter (package.json):
"scripts": {
"start": "npm run build && node build/index.js",
"start:dev": "ts-node-dev --respawn --transpile-only src/index.ts",
"build": "tsc"
}
node-typescript-boilerplate (package.json):
"scripts": {
"start": "node build/src/main.js",
"clean": "rimraf coverage build tmp",
"build": "tsc -p tsconfig.json",
"build:watch": "tsc -w -p tsconfig.json"
}
The simple-typescript-starter uses ts-node-dev for development, while node-typescript-boilerplate relies on TypeScript's watch mode. The node-typescript-boilerplate also includes a clean script for removing build artifacts.
Both projects provide a solid foundation for TypeScript development, with node-typescript-boilerplate offering a more comprehensive setup and simple-typescript-starter focusing on simplicity and ease of use for beginners.
A delightful way to building a RESTful API with NodeJs & TypeScript by @w3tecch
Pros of express-typescript-boilerplate
- Includes Express.js framework, providing a robust foundation for web applications
- Offers more comprehensive features like database integration, authentication, and API documentation
- Provides a scalable project structure suitable for larger applications
Cons of express-typescript-boilerplate
- More complex setup and steeper learning curve due to additional features
- Potentially overkill for simple projects or microservices
- Less frequently updated compared to node-typescript-boilerplate
Code Comparison
node-typescript-boilerplate:
import { hello } from './main';
console.log(hello());
express-typescript-boilerplate:
import { Container } from 'typedi';
import { UserService } from './services/UserService';
const userService = Container.get(UserService);
const users = await userService.find();
The code snippets highlight the difference in complexity and features between the two boilerplates. node-typescript-boilerplate focuses on a simple TypeScript setup, while express-typescript-boilerplate demonstrates dependency injection and service-based architecture.
Both boilerplates offer valuable starting points for TypeScript projects, with node-typescript-boilerplate being more suitable for lightweight applications and express-typescript-boilerplate providing a comprehensive foundation for full-fledged web applications.
Convert
designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual CopilotREADME
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.
[!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.
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.
Top Related Projects
A reference example for TypeScript and Node with a detailed README describing how to use the two together.
TypeScript execution and REPL for node.js
Starter kit with zero-config for building a library in TypeScript, featuring RollupJS, Jest, Prettier, TSLint, Semantic Release, and more!
The most basic TypeScript starter I could think of
A delightful way to building a RESTful API with NodeJs & TypeScript by @w3tecch
Convert
designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual Copilot