# node-typescript-boilerplate: Minimal Node.js TypeScript Starter > node-typescript-boilerplate is a small, strict starter template for Node.js TypeScript projects that includes Vitest, ESLint, Prettier, GitHub Actions, Mise, and an AGENTS.md file for AI coding agents. It targets Node.js 24 and TypeScript 6 with native ESM and deliberately excludes frameworks, databases, and deployment tooling. **jsynowiec/node-typescript-boilerplate** — Production-ready Node.js TypeScript boilerplate: ESM, Vitest, ESLint, Prettier, GitHub Actions, Mise, and AGENTS.md included. - Repository: https://github.com/jsynowiec/node-typescript-boilerplate - Stars: 2,956 · Forks: 565 - Language: TypeScript - License: Apache-2.0 - Published: 2026-09-24 · Updated: 2026-09-24 · Language: en - Canonical page: https://hysenlabs.com/projects/jsynowiec-node-typescript-boilerplate ## What node-typescript-boilerplate Provides and Who It Is For Setting up a new Node.js TypeScript project from scratch requires configuring TypeScript, a linter, a formatter, a test runner, and a CI pipeline. Each tool needs to be installed, configured to work with the others, and pinned to compatible versions. The boilerplate does this work once and lets teams clone it as a starting point. The README describes the template as intentionally small, strict, and boring. No framework lock-in, no unnecessary runtime dependencies, and no hidden magic. This positions it for projects where the author wants to own every dependency decision: a CLI, a job processor, a library, an API without a specific framework, or a worker. The template is not for full-stack web development. It includes no web framework, no database driver, no authentication library, no Docker configuration, and no cloud deployment setup. The README lists these explicitly as things the template does not include and notes that a clean foundation is what is provided. ## What Is Included: Tools and Their Justification The template bundles a specific set of tools with documented reasoning for each choice. TypeScript is configured with strict mode and targets ES2024 output. The template uses TypeScript 6, as listed in package.json. Vitest replaces Jest as the test runner. The README explains the choice: Vitest is generally faster than Jest, especially for large test suites; it has native ESM support; and it is easier to configure with TypeScript, simplifying mock and spy types. The test command in package.json is: ``` "test": "vitest run unit --config __tests__/vitest.config.ts" ``` ESLint is configured with typescript-eslint for static analysis. Prettier and EditorConfig handle formatting. GitHub Actions provides CI. The .github/ directory in the repository contains the workflow file. Mise replaces Volta for toolchain management. The README notes that Volta is no longer maintained, citing github.com/volta-cli/volta/issues/2080, and that the Volta maintainers recommend Mise as the replacement. Mise tracks the Node.js version in mise.toml and ensures the project uses the configured version when switching between projects. tslib is listed as a runtime dependency. The README explains: TypeScript inlines helper functions for async/await, spread, and destructuring into every output file. Setting `importHelpers: true` in tsconfig along with tslib causes all output files to share a single imported copy of those helpers, reducing duplication across the build. AGENTS.md is included with project guidance for AI coding agents such as GitHub Copilot, Claude Code, and Codex-style agents. The README notes that the AGENTS.md format has become a community-driven standard stewarded by the Agentic AI Foundation under the Linux Foundation. ## Getting Started: Clone, Template, or Download The recommended approach for new projects is clicking Use template on GitHub, which creates a copy without the upstream history. For teams that prefer a fresh git repository from a local clone: ```sh 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 ``` For download without git: ```sh 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 ``` After setup, the available scripts include: `build` to compile TypeScript, `test` to run Vitest in unit mode, `test:coverage` for coverage with v8, `lint` for ESLint, `prettier` to reformat sources, and `build:release` to clean and compile without source maps. The `prebuild` hook runs lint and type checking automatically before every build. New source code goes in src/ and tests go in __tests/. The template ships a minimal example source file and a matching unit test to confirm the toolchain works before the developer writes any production code. ## Native ESM and Why CommonJS Is Not Supported The template uses native ESM throughout. The package.json includes `"type": "module"` and the engines field pins to Node.js >=24.11 <25. TypeScript is configured to emit ES2024 modules. The README links to the Node.js ESM documentation and the TypeScript ESM guide as prerequisites for anyone unfamiliar with ESM in Node.js. It also links to a guide by Sindre Sorhus for converting a CommonJS project to ESM. Both links are listed in the README under the ES Modules section. The template explicitly does not support CommonJS and asks that questions about CommonJS compatibility not be opened as issues. This is a firm design choice: the template targets the current Node.js module system rather than maintaining backward compatibility with the older CommonJS format. Importing ES modules requires file extensions in import paths when using Node.js native ESM. The tsconfig is set up to handle this correctly. Projects that need to export a dual ESM/CommonJS package will need additional configuration beyond what the template provides. The devDependencies include @types/node ~24 and typescript-eslint ~8.59.0 to keep linting aligned with the TypeScript version. ## AGENTS.md and AI Coding Agent Integration The AGENTS.md file in the repository root provides structured guidance for AI coding agents. It covers TypeScript style, testing expectations, Node.js conventions, dependency policy, and verification steps. The README notes that this is example content and that project teams should write their own project-specific instructions tailored to their codebase. The CLAUDE.md file in the repository root serves a similar purpose for Claude Code specifically. Both files exist at the root level where AI coding tools check for project configuration on startup. The practical implication is that an AI coding agent starting work on a project based on this template has a baseline set of instructions about how the project expects code to be written and tested. Without those files, the agent has to infer conventions from the existing code, which can lead to inconsistent style or missed verification steps. The template encodes those expectations in files that any agent supporting either format can read. ## node-typescript-boilerplate Against Express Boilerplates Several popular boilerplates pair Node.js and TypeScript with Express or NestJS. W3Tecch's express-typescript-boilerplate is one such template, bundling Express, TypeORM, JWT authentication, and dependency injection. It solves a different problem: getting a REST API with authentication and database access running quickly. node-typescript-boilerplate makes no assumptions about the application layer. It provides the base TypeScript, linting, testing, and CI configuration and nothing above that. A developer who starts from this template and later decides to add Express adds only what their specific project needs, without removing defaults they did not want. The trade-off is setup time for specific use cases. A developer building a standard REST API with a database will spend more time configuring dependencies starting from this template than from a framework-specific boilerplate. The template is optimized for the case where the application layer requirements are not yet known or are non-standard. ## Maintenance and License The last push to the repository was on 2026-06-30. The repository is not archived. The Apache 2.0 license permits use, modification, and distribution, including in proprietary projects, provided the license notice is preserved. There are no GitHub releases. Version tracking for the template itself is through the git history rather than numbered releases, since the template is a starting point rather than a versioned library. The README credits Jakub Synowiec as the author, with sponsorship links for teams that find the template useful. The package.json engines constraint is `>= 24.11 < 25`. This pins the template to Node.js 24 specifically. Users who need to target an earlier or later Node.js major version will need to update the engines field, the .node-version file, the mise.toml toolchain configuration, and the TypeScript target in tsconfig.json. The Vitest version is ~4.1.4 and ESLint is ~10.2, both pinned in the devDependencies to maintain reproducibility across installs. ## Conclusion node-typescript-boilerplate is the right starting point for backend services, CLIs, and libraries that should be Node.js 24 and TypeScript 6 from day one, without committing to a specific framework, ORM, or deployment platform. It is not the right choice for projects that need Express, Fastify, NestJS, authentication, Docker, or cloud-specific configuration: those are explicitly absent and need to be added. Before using it, check whether your target Node.js version matches the engine constraint in package.json, which pins to >=24.11 <25, since a different Node.js major version may require updating tsconfig and vitest targets. ## FAQ ### Is this node-typescript-boilerplate suitable for production use? The template provides the toolchain configuration (TypeScript, Vitest, ESLint, Prettier, GitHub Actions, Mise) and no application framework, database driver, or deployment setup. It is a starting point that is as close to production-ready as a bare toolchain can be, but the application layer, error handling, logging, and deployment configuration are all left to the developer. ### Why does node-typescript-boilerplate use Vitest instead of Jest? The README explains three reasons: Vitest is generally faster than Jest for large test suites, it has native ES module support, and it simplifies mock, spy, and type handling with TypeScript compared to Jest's configuration requirements. ### What is the purpose of the AGENTS.md file in node-typescript-boilerplate? AGENTS.md provides AI coding agents (GitHub Copilot, Claude Code, and similar tools) with instructions about the project's TypeScript style, testing expectations, and verification steps. The README describes the format as a community-driven standard stewarded by the Agentic AI Foundation under the Linux Foundation. ## Sources - [Issues](https://github.com/jsynowiec/node-typescript-boilerplate/issues) - [jsynowiec/node-typescript-boilerplate on GitHub](https://github.com/jsynowiec/node-typescript-boilerplate) - [License: Apache-2.0](https://github.com/jsynowiec/node-typescript-boilerplate/blob/main/LICENSE) - [README](https://github.com/jsynowiec/node-typescript-boilerplate/blob/main/README.md) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/jsynowiec-node-typescript-boilerplate