template-nodejs

A minimal production-ready template for Node.js 24 applications written in TypeScript.

The template includes pnpm, tsup, ESLint, Prettier, TypeScript strict checks, Node's built-in test runner, a VS Code Devcontainer, and a non-root multi-stage production image.

Requirements

• Node.js 24.19.0 (LTS) for local development
• Corepack
• Docker for container builds

The exact Node version is declared in .node-version and .nvmrc. The exact pnpm version is declared through packageManager in package.json.

Setup

corepack enable
pnpm install --frozen-lockfile
cp .env.example .env
pnpm dev

The server listens on port 3000 by default. Its readiness endpoint is available at http://localhost:3000/health.

Development Commands

Command	Purpose
pnpm dev	Start the application in watch mode
pnpm build	Create the regular bundle in dist/
pnpm build:production	Create the minified production bundle
pnpm start	Run the generated bundle
pnpm typecheck	Check TypeScript without emitting files
pnpm test	Run tests once
pnpm test:watch	Run tests in watch mode
pnpm lint	Run ESLint without modifying files
pnpm lint:fix	Apply safe ESLint fixes
pnpm format	Format supported files
pnpm format:check	Verify formatting
pnpm check	Run the full local quality gate

VS Code Devcontainer

Open the repository in VS Code and select "Dev Containers: Reopen in Container". The Devcontainer uses Node 24.19.0, activates pnpm 11.22.0 through Corepack, installs the locked dependencies, and includes the Codex CLI.

No host-side project installation is required.

Production Container

Build and run the application from the repository root:

docker build --tag template-nodejs:local .
docker run --rm --publish 3000:3000 --env PORT=3000 template-nodejs:local

The production image:

• uses the current Node 24 LTS patch on Alpine Linux
• installs dependencies from pnpm-lock.yaml
• excludes development dependencies and build tools from the runtime stage
• runs as the unprivileged node user
• exposes a Docker health check backed by GET /health
• handles SIGINT and SIGTERM for graceful shutdown

Project Structure

src/
├── main.ts         # process entry point and lifecycle
├── server.ts       # side-effect-free server factory
└── server.test.ts  # HTTP behavior tests

Add domain modules below src/ and keep main.ts limited to configuration, dependency wiring, startup, and shutdown.

Dependency Updates

Check direct dependencies and update the lockfile with pnpm:

pnpm outdated
pnpm update --latest
pnpm check

TypeScript is intentionally kept on the newest version supported by the current typescript-eslint release. Keep that peer-dependency boundary in mind when moving to a new TypeScript major.