node-typescript-boilerplate

👩🏻‍💻 Developer Ready: A comprehensive template. Works out of the box for most Node.js projects.

🏃🏽 Instant Value: All basic tools included and configured:

• TypeScript 6.0
• ESM
• ESLint with some initial rules recommendation
• Vitest for fast unit testing and code coverage
• Type definitions for Node.js
• Prettier to enforce consistent code style
• NPM scripts for common operations
• EditorConfig for consistent coding style
• Reproducible environments thanks to Mise
• Example configuration for GitHub Actions
• Simple example of TypeScript code and unit test
• Basic AGENTS.md guidelines for agents

🤲 Free as in speech: available under the APLv2 license.

Getting Started

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

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 clone the repository, use the following commands:

git clone https://github.com/jsynowiec/node-typescript-boilerplate
cd node-typescript-boilerplate
npm install

Download latest release

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

• clean - remove coverage data, cache and transpiled files,
• prebuild - lint source files and tests before building,
• build - transpile TypeScript to ES6,
• build:watch - interactive watch mode to automatically transpile source files,
• lint - lint source files and tests,
• prettier - reformat files,
• test - run tests,
• test:watch - interactive watch mode to automatically re-run tests
• test:coverage - run test and print out test coverage

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.

Backers & Sponsors

Support this project by becoming a sponsor.

License

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