nkcoder/nodejs-blueprint

A scaffold for my next Node.js project.

Node.js TypeScript Blueprint

A modern Node.js TypeScript scaffold with best practices, comprehensive testing, and developer-friendly tooling.

Features

• 🚀 Modern TypeScript - Latest TypeScript with strict type checking
• 📦 ESM Support - Native ECMAScript modules
• 🛠️ Development Tools - Hot reload with tsx, debugging support
• ✅ Testing Suite - Vitest with coverage reporting and UI
• 🎯 Code Quality - Biome for linting and formatting
• 🔧 Build System - TypeScript compiler with declaration files
• 📝 Logging - Structured logging with Pino
• ⚙️ Configuration - Environment validation with Zod
• 🔀 Git Hooks - Automated checks with Lefthook
• 🛡️ Error Handling - Custom error classes with correlation IDs

Quick Start

# Install dependencies
pnpm install

# Start development server
pnpm dev

# Run tests
pnpm test

# Build for production
pnpm build

# Start production server
pnpm start

Scripts

Development

• pnpm dev - Start development server with hot reload
• pnpm dev:debug - Start with Node.js debugger enabled

Testing

• pnpm test - Run tests once and exit
• pnpm test:watch - Run tests in watch mode
• pnpm test:coverage - Run tests with coverage report
• pnpm test:ui - Launch interactive test UI

Code Quality

• pnpm lint - Lint code with Biome
• pnpm lint:fix - Lint and auto-fix issues
• pnpm format - Format code with Biome
• pnpm check - Run all Biome checks
• pnpm check:fix - Run checks with auto-fix
• pnpm typecheck - Type check with TypeScript

Build & Deployment

• pnpm build - Compile TypeScript to JavaScript
• pnpm start - Start production server
• pnpm clean - Remove build artifacts

Project Structure

├── src/
│   ├── config/
│   │   └── env.ts          # Environment configuration with Zod validation
│   ├── types/
│   │   └── common.ts       # Shared TypeScript interfaces
│   ├── utils/
│   │   ├── errors.ts       # Custom error classes
│   │   └── logger.ts       # Structured logging setup
│   └── index.ts            # Application entry point
├── test/                   # Test files
├── dist/                   # Compiled JavaScript output
└── coverage/               # Test coverage reports

Configuration

Environment Variables

The application validates environment variables using Zod schemas:

• NODE_ENV - Environment mode (development, production, test)
• PORT - Server port (1-65535, default: 3000)
• LOG_LEVEL - Logging level (error, warn, info, debug)

Path Aliases

TypeScript path aliases are configured for clean imports:

import { config } from '@/config/env';
import { logger } from '@/utils/logger';
import { AppError } from '@/utils/errors';

Available aliases:

• @/* → src/*
• @/types/* → src/types/*
• @/utils/* → src/utils/*
• @/config/* → src/config/*
• @/components/* → src/components/*
• @/middleware/* → src/middleware/*
• @/lib/* → src/lib/*
• @/constants/* → src/constants/*

Core Components

Error Handling

Custom AppError class with correlation IDs and context:

// Factory methods for common error types
const error = AppError.validationError('Invalid input', { field: 'email' });
const error = AppError.notFoundError('User not found', { userId: 123 });

// Convert from standard Error
const appError = AppError.fromError(originalError, 400);

Logging

Structured logging with Pino:

import { logger } from '@/utils/logger';

logger.info({ userId: 123 }, 'User logged in');
logger.error({ error: err.message, correlationId }, 'Database error');

Configuration

Type-safe environment configuration:

import { config } from '@/config/env';

console.log(config.NODE_ENV); // TypeScript knows this is a valid enum
console.log(config.PORT);     // TypeScript knows this is a number

Testing

The project includes comprehensive tests using Vitest:

• Unit Tests - All core utilities (errors, logger, config)
• Integration Tests - Application entry point and module imports
• Type Tests - TypeScript interface validation
• Coverage - 80% threshold for branches, functions, lines, statements

Running Tests

# Run all tests
pnpm test

# Run with coverage
pnpm test:coverage

# Watch mode for development
pnpm test:watch

# Interactive UI
pnpm test:ui

Git Hooks

Lefthook manages Git hooks for code quality:

Pre-commit

• Code formatting and linting (auto-fix enabled)
• TypeScript type checking

Pre-push

• Full test suite
• Production build verification

Technology Stack

• Runtime - Node.js 20+
• Language - TypeScript 5.9
• Package Manager - pnpm
• Development - tsx (TypeScript execution)
• Testing - Vitest with V8 coverage
• Code Quality - Biome (ESLint + Prettier replacement)
• Logging - Pino with pretty printing
• Validation - Zod schemas
• Git Hooks - Lefthook

Requirements

• Node.js ≥ 20.0.0
• pnpm ≥ 8.0.0

License

MIT

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and ensure they pass
5. Submit a pull request

The project uses automated Git hooks to ensure code quality and test coverage.