NestJS API Starter Kit

A production-ready NestJS API starter kit with comprehensive tooling, security features, and development workflow. Built with TypeScript, PostgreSQL, Docker, and modern development practices.

📦 Package Manager Flexible: Works with npm, Bun, pnpm, or Yarn. See Package Manager Guide for details.

Features

🚀 Core Framework

• NestJS 11.1+ - Progressive Node.js framework for building efficient and scalable server-side applications
• TypeScript - Full TypeScript support with strict type checking
• API Versioning - Built-in URI-based API versioning (/api/v1/)
• Validation - Request validation using class-validator and class-transformer
• Global Exception Handling - Centralized error handling with detailed logging

🛡️ Security

• Helmet - Security headers and protection against common vulnerabilities
• CORS - Configurable Cross-Origin Resource Sharing
• Rate Limiting - Multi-tiered throttling (short, medium, long-term limits)
• Input Validation - Strict input validation and sanitization
• Security Best Practices - Non-root Docker user, proper secret management

📊 Database & ORM

• PostgreSQL 16 - Robust relational database with Alpine Linux image
• TypeORM - Feature-rich ORM with migrations and seeding support
• Database Health Checks - Built-in health monitoring
• Migration System - Automated database schema migrations
• Connection Pooling - Optimized database connections

🐳 Containerization

• Multi-stage Docker builds - Optimized for development and production
• Docker Compose - Complete development environment with services
• Health Checks - Container health monitoring
• Volume Management - Persistent data storage
• Service Orchestration - PostgreSQL, Redis, and Adminer integration

🧪 Testing

• Jest - Comprehensive testing framework
• Unit Tests - Component-level testing with mocking
• E2E Tests - End-to-end integration testing
• Coverage Reports - Detailed code coverage with thresholds (80%+)
• Test Database - Isolated testing environment

📝 Logging & Monitoring

• Winston - Structured logging with multiple transports
• Health Checks - Liveness and readiness probes
• Request Logging - Detailed HTTP request/response logging
• Performance Monitoring - Response time tracking
• Error Tracking - Comprehensive error logging and stack traces

🛠️ Development Tools

• ESLint - Code linting with TypeScript rules
• Prettier - Code formatting with consistent style
• Husky - Git hooks for pre-commit validation
• Lint-staged - Run linters on staged files only
• Commitlint - Enforce conventional commit messages
• Standard Version - Automated versioning and changelog generation

🔧 Additional Features

• Hot Reload - Fast development with automatic restarts
• Path Mapping - Clean imports with TypeScript path mapping
• Environment Configuration - Comprehensive environment variable management
• Graceful Shutdown - Proper application shutdown handling
• Compression - Response compression for better performance
• Redis Ready - Pre-configured Redis integration for caching

Quick Start

Prerequisites

• Node.js 20.0.0 or higher (required for NestJS v11.x)
• Package Manager (choose one):
  • npm 10.0.0+ (included with Node.js)
  • Bun 1.0+ (Install) - Fastest installs & runtime
  • pnpm 8.0+ (Install) - Disk space efficient
  • Yarn 4.0+ (Install) - Classic choice
• Docker and Docker Compose (optional, for containerized development)
• PostgreSQL 12+ (if not using Docker)

Installation

1. Clone the repository

   git clone <repository-url>
   cd nestjs-api-starter-kit

2. Install dependencies

   # Choose your preferred package manager:
   npm install      # npm (comes with Node.js)
   # OR
   bun install      # bun (fastest)
   # OR
   pnpm install     # pnpm (efficient)
   # OR
   yarn install     # yarn (classic)

3. Start with Docker (Recommended)

   # Copy environment file
   cp .env.example .env
   # Edit .env with your configuration if needed
   
   # Start all services (API + Database + Redis)
   docker compose up

   The API will be available at http://localhost:3888

Alternative: Local Development

If you prefer running the API locally with containerized services:

1. Start only the database services

   docker compose up -d postgres redis

2. Run migrations

   npm run typeorm:migration:run  # (use your chosen package manager)

3. Start the API locally

   npm run start:dev  # (use your chosen package manager)

Development Tools

For additional development tools like Adminer (database management UI):

# Start with development tools
docker compose -f docker-compose.yml -f docker-compose.dev.yml up

# Or with profiles
docker compose --profile dev-tools up

This adds:

• pgAdmin at http://localhost:8080 - PostgreSQL management interface
  • Login: [email protected] / admin

Docker Management

# Start all services
docker compose up

# Start services in background
docker compose up -d

# Start with development tools (pgAdmin)
docker compose -f docker-compose.yml -f docker-compose.dev.yml up

# Rebuild and start
docker compose up --build

# View logs
docker compose logs -f api

# Stop services
docker compose down

# Stop and remove volumes
docker compose down -v

Available Scripts

Note: Replace npm run with your package manager's command:

• npm: npm run <script>
• bun: bun run <script> or bun <script>
• pnpm: pnpm run <script> or pnpm <script>
• yarn: yarn <script>

Development

npm run start:dev          # Start development server with hot reload
npm run start:debug        # Start development server with debugger
npm run build              # Build production bundle
npm run start:prod         # Start production server

Testing

npm test                   # Run unit tests
npm run test:watch         # Run tests in watch mode
npm run test:cov           # Run tests with coverage report
npm run test:e2e           # Run end-to-end tests
npm run test:all           # Run all tests (unit + e2e)

Code Quality

npm run lint               # Lint and fix code
npm run lint:check         # Check linting without fixing
npm run format             # Format code with Prettier
npm run format:check       # Check formatting without fixing

Database

npm run typeorm:migration:generate    # Generate migration from entity changes
npm run typeorm:migration:create      # Create empty migration file
npm run typeorm:migration:run         # Run pending migrations
npm run typeorm:migration:revert      # Revert last migration
npm run db:seed                       # Run database seeds

Docker

npm run docker:build       # Build production Docker image
npm run docker:build:dev   # Build development Docker image
npm run docker:up          # Start Docker compose services
npm run docker:down        # Stop Docker compose services
npm run docker:test        # Run tests in Docker environment

API Documentation

Health Endpoints

The API includes comprehensive health check endpoints:

• GET /api/v1/health/live - Liveness probe (basic server health)
• GET /api/v1/health/ready - Readiness probe (includes database connectivity)
• GET /api/v1/health - Detailed health status

API Versioning

All API endpoints are versioned using URI versioning:

/api/v1/endpoint
/api/v2/endpoint

Response Format

All API responses follow a consistent format:

{
  "success": true,
  "data": {...},
  "message": "Success message",
  "timestamp": "2024-01-01T00:00:00Z"
}

Error responses:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {...}
  },
  "timestamp": "2024-01-01T00:00:00Z"
}

Project Structure

nestjs-api-starter-kit/
├── src/                          # Source code
│   ├── app.module.ts            # Root application module
│   ├── main.ts                  # Application entry point
│   ├── common/                  # Shared utilities and components
│   │   ├── decorators/          # Custom decorators
│   │   ├── filters/             # Exception filters
│   │   ├── guards/              # Route guards
│   │   ├── interceptors/        # Request/response interceptors
│   │   ├── pipes/               # Validation pipes
│   │   └── logger/              # Logging configuration
│   ├── config/                  # Configuration management
│   ├── database/                # Database configuration and migrations
│   │   ├── migrations/          # TypeORM migrations
│   │   └── seeds/               # Database seeds
│   └── health/                  # Health check module
├── test/                        # Test files
│   ├── unit/                    # Unit tests
│   └── e2e/                     # End-to-end tests
├── docs/                        # Documentation
├── scripts/                     # Utility scripts
├── docker-compose.yml           # Docker compose configuration
├── Dockerfile                   # Multi-stage Docker build
└── package.json                 # Dependencies and scripts

Environment Variables

The application uses environment-based configuration. See docs/environment-variables.md for complete documentation.

Key variables:

• NODE_ENV - Environment (development/production/test)
• PORT - Server port (default: 3888)
• DB_HOST, DB_PORT, DB_USERNAME, DB_PASSWORD, DB_NAME - Database configuration
• JWT_SECRET - JWT signing secret
• LOG_LEVEL - Logging level (error/warn/info/debug/verbose)

Contributing

We welcome contributions! Please see our Contributing Guide for details on:

• Code of conduct
• Development process
• Pull request procedure
• Coding standards
• Testing requirements

Documentation

Comprehensive documentation is available in the docs/ directory:

• 📚 Getting Started Guide - Detailed setup instructions
• 🔧 Development Workflow - Development best practices
• 🧪 Testing Guide - Testing strategies and tools
• 🐳 Docker Guide - Container usage and deployment
• 🛠️ Tooling Overview - Development tools explanation
• 🌍 Environment Variables - Configuration reference
• 📁 Project Structure - Code organization guide
• 🚀 Deployment Guide - Production deployment
• 🐶 Husky & Git Hooks - Commit guidelines and git hooks
• 🔧 Adding New Endpoints - Guide for creating new API endpoints

🤖 AI Development Support

• Cursor Rules - Comprehensive .cursorrules file for AI-assisted development with project-specific guidelines and patterns

Performance

Response Times

• Health endpoints: < 10ms
• Database queries: < 100ms (with proper indexing)
• API responses: < 200ms (average)

Scalability

• Horizontal scaling ready
• Stateless application design
• Connection pooling optimized
• Caching layer ready (Redis)

Resource Usage

• Memory: ~50MB baseline
• CPU: Low utilization with async processing
• Disk: Minimal with log rotation

Security Considerations

• 🔒 All dependencies are regularly audited (npm audit)
• 🛡️ Security headers applied via Helmet
• 🚫 Input validation and sanitization on all endpoints
• 🔐 Secrets managed via environment variables
• 👤 Non-root Docker container execution
• 🌐 CORS properly configured
• 🚦 Rate limiting to prevent abuse

Monitoring & Observability

Health Checks

• Kubernetes-ready liveness and readiness probes
• Database connectivity monitoring
• Custom health indicators

Logging

• Structured JSON logging
• Request/response logging
• Error tracking with stack traces
• Performance metrics

Metrics (Ready for Integration)

• Request duration
• Request count
• Error rates
• Database query performance

Roadmap

Planned Features

• JWT Authentication module
• User management system
• API documentation with Swagger/OpenAPI
• Prometheus metrics integration
• GraphQL support
• WebSocket support
• File upload handling
• Email service integration
• Caching layer with Redis
• Queue system with Bull

Performance Enhancements

• Database query optimization
• Response caching
• CDN integration
• Compression improvements

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• 📧 Email: [[email protected]]
• 🐛 Issues: GitHub Issues
• 📖 Documentation: GitHub Wiki
• 💬 Discussions: GitHub Discussions

Acknowledgments

• NestJS - The progressive Node.js framework
• TypeORM - Amazing ORM for TypeScript
• PostgreSQL - Powerful open-source database
• Docker - Containerization platform
• Jest - Delightful JavaScript testing framework

---

Built with ❤️ for the Node.js community