node-backend-template

A minimal Node.js + TypeScript backend starter template and CLI tool using Express, Pino logging, validation middleware, 404 + error handling, and fast development cycle.

✅ Features

• Express server with src/app.ts and src/server.ts
• root endpoint: GET / returns "Hello World!"
• configurable via .env (development/staging/production)
• logging with pino + rotating-file-stream
• security middleware: helmet, cors
• centralized error handling + 404 not found
• utility module sum with Vitest unit tests
• linting, formatting, commit hooks, and type-checking workflows

📦 Requirements

• Node.js 25.x (or latest compatible)
• pnpm (project uses pnpm package manager)

Usage with NPX

Quick start with npx (no installation required):

npx node-backend-template
pnpm dlx node-backend-template

Running this starts an interactive project generator. It now supports:

• project name prompt (must be lowercase, URL-friendly)
• language selection: TypeScript or JavaScript
• package manager selection: npm, yarn, or pnpm

Once complete, it:

1. creates the project folder
2. copies the templates/{ts|js} skeleton
3. renames gitignore.template → .gitignore
4. updates package.json name
5. copies .env.example to .env

Example

npx node-backend-template
# Enter project name: my-app
# Choose language: TypeScript
# Choose package manager: pnpm

Then run:

cd my-app
pnpm install
pnpm dev

This command bootstraps a new backend project with all the starter template features.

Additional commands:

npx node-backend-template --help     # Show all available commands
npx node-backend-template --version  # Show version

⚠️ Warning: Do NOT use npm i node-backend-template. Always use npx node-backend-template for the best experience with proper dependency management.

🛠️ Environment

Copy and set environment variables for your environment.

cp .env.example .env.development
cp .env.example .env.staging
cp .env.example .env.production

Environment Variables

• PORT: The port number on which the Express server will listen (e.g., 3000)
• SERVER_URL: The base URL of the server (e.g., http://localhost:3000)
• ENV: The environment mode, one of development, staging, or production
• DATABASE_URL: The database connection string (optional; required if using a database)

▶️ Development

pnpm dev
pnpm dev:staging
pnpm dev:prod

Express server starts and logs via Pino. Root route is at GET /.

🧱 Build

pnpm build

Build compiles with TypeScript using tsconfig.build.json.

🧪 Tests

pnpm test:run
pnpm test:ui
pnpm coverage

Includes sample unit test in src/__tests__/sum.spec.ts for src/utils/sum.ts.

🎯 Lint & formatter

pnpm lint
pnpm lint:fix
pnpm format
pnpm format:check

Git hooks via husky and lint-staged run lint + prettier before commit.

📁 Project structure

• src/app.ts - Express app setup
• src/server.ts - server startup + graceful shutdown
• src/config/config.ts - env config loader
• src/middlewares/middlewares.ts - sample route handler
• src/middlewares/notFound.ts - 404 middleware
• src/middlewares/globalErrorHandler.ts - error handler
• src/utils/logger.ts - pino logger config + file rotation
• src/utils/httpError.ts - http error wrapper
• src/utils/errorObjects.ts - error response builder
• src/constant/* - response messages + environment enums
• src/type/types.ts - TS type definitions
• src/__tests__ - unit tests

Middleware flow

1. pino-http logs request/response
2. express.json parses incoming JSON
3. cors enables CORS
4. helmet adds security headers
5. express.static serves public/
6. globalErrorHandler handles errors in JSON format
7. notFound handles unknown routes

Contributing

Please see CONTRIBUTING.md for contribution guidelines and CODE_OF_CONDUCT.md for community expectations.

If you are contributing through a pull request, the basic flow is:

1. Fork and branch
2. pnpm install
3. Add or update tests
4. Run lint/format
5. Open a pull request

🆘 Troubleshooting

• Port in use: change PORT in .env
• Type errors: pnpm type-check
• Commit blocked: run pnpm lint:fix and pnpm format