template-node

A sane, opinionated template for ESM Node.js projects written in TypeScript without a transpilation step — TypeScript is executed directly by Node.js.

Tip

Using mise locally is the path of least friction: it manages the project-specific runtimes, tools, and tasks without requiring a container.

This template also includes an optional Arch Linux Dev Container based on mise-devcontainers. It is suggested if you do not normally use mise or want a consistent, preconfigured development environment.

Uses, among other tools/packages:

• pnpm as package manager
• Biome for linting and formatting
• Lefthook for Git hooks
• Commitlint with config-conventional for commit message linting
• Vitest for testing

requirements and dependencies

Using mise locally is recommended and provides the least-friction setup. If you do not normally use mise, the included Dev Container is an optional way to get a consistent development environment with everything preconfigured.

To use the Dev Container you need:

• Docker or a compatible container runtime
• a Dev Container-compatible editor or the Dev Container CLI
• an SSH agent exposed through SSH_AUTH_SOCK with at least one key loaded

The SSH agent is forwarded into the container for Git authentication and commit signing. Private keys remain on the host.

If you use the Dev Container, once inside it, install the project dependencies:

pnpm install

The project-specific runtimes and development tools are managed by mise.

If you do not use the Dev Container, install mise locally and run mise install before installing the project dependencies.

Note

Git hooks keep the tooling managed by mise and the project dependencies synchronized after checkouts and merges.

subpath imports

Subpath imports (#/) are used instead of relative paths. They are mapped through the imports field in package.json, allowing native Node.js resolution at runtime without additional build tooling, and mirrored in tsconfig.json for editor support.

Example:

import { add } from "#/lib/math"; // ./src/lib/math.ts

running

mise run dev

Runs the project in watch mode.

mise run test

Runs the tests.

mise run lint-fix

Runs Biome in fix mode to lint and format the project.

mise run typecheck

Runs TypeScript type checking.

ci

CI is provided by GitHub Actions through .github/workflows/checks.yml.

It runs:

• Biome linting and formatting checks
• TypeScript type checking
• Vitest tests

license

MIT