NestJS Starter Boilerplate 🚀

<div align="center">

</div> <p align="center"> A production-ready NestJS boilerplate with comprehensive features and best practices for building scalable, enterprise-grade APIs. </p> <p align="center"> <strong>⚡️ Quick Start</strong> • <strong>🐳 Docker Ready</strong> • <strong>🤖 AI/MCP Integrated</strong> • <strong>✅ Production Ready</strong> </p>

---

🎯 What's Included

<table> <tr> <td width="50%">

Core Features

• ✅ JWT Authentication (Access/Refresh)
• ✅ Role-Based Access Control (RBAC)
• ✅ PostgreSQL + Prisma ORM
• ✅ Redis Cache & Bull Queues
• ✅ AWS S3 File Uploads
• ✅ AWS SES Email Service
• ✅ Swagger API Documentation
• ✅ Health Checks & Monitoring

</td> <td width="50%">

Developer Experience

• ✅ Docker & Docker Compose
• ✅ GitHub Actions CI/CD
• ✅ Jest Testing (90%+ Coverage)
• ✅ ESLint + Prettier + Husky
• ✅ Structured Logging (Pino)
• ✅ Model Context Protocol (MCP)
• ✅ i18n Multi-language Support

</td> </tr> </table>

---

📑 Table of Contents

• Features
• Tech Stack
• Quick Start
  • Prerequisites
  • Installation
  • Environment Setup
  • Database Setup
  • Start Development Server
• Environment Configuration
• Docker Setup
• API Documentation
• Model Context Protocol (MCP)
• Testing
• Project Structure
• Development Workflow
• Deployment
• Security Best Practices
• Troubleshooting
• Contributing
• Scripts Reference
• License

---

✅ Implementation Status

This boilerplate is fully production-ready with comprehensive features and best practices:

| Feature | Status | Details | |---------|--------|---------| | JWT Authentication & RBAC | ✅ Complete | Access/Refresh tokens, role-based access control | | PostgreSQL + Prisma ORM | ✅ Complete | Full schema with 3 models (User, Post, PostImage) | | Redis Cache & Bull Queues | ✅ Complete | Email queue processor, task scheduling | | AWS S3 & SES | ✅ Complete | File uploads, email templating | | Docker & Docker Compose | ✅ Complete | Multi-service setup with health checks | | GitHub Actions CI/CD | ✅ Complete | Automated testing, linting, badge generation | | Jest Testing | ✅ Complete | 18 test suites, 90%+ coverage | | MCP Integration | ✅ Complete | 8 tools, 10 resources, 5 prompts | | Swagger Documentation | ✅ Complete | Auto-generated API docs | | i18n Support | ✅ Complete | Multi-language message service |

---

✨ Features

• 🔐 Authentication & Authorization - JWT-based auth with access/refresh tokens
• 📚 API Documentation - Auto-generated Swagger/OpenAPI documentation
• 🗄️ Database Integration - PostgreSQL with Prisma ORM
• 📧 Email Service - AWS SES integration with templating
• 📁 File Upload - AWS S3 integration with pre-signed URLs
• 🔄 Background Jobs - Bull queue with Redis for async processing
• 🤖 MCP Integration - Model Context Protocol support for AI tools, resources, and prompts
• 📊 Logging - Structured logging with Pino
• 🧪 Testing - Comprehensive unit tests with Jest (90%+ coverage)
• 🐳 Containerization - Docker and Docker Compose ready
• 🚀 CI/CD - GitHub Actions workflows
• 🔍 Code Quality - ESLint, Prettier, Husky pre-commit hooks
• 📈 Monitoring - Sentry integration for error tracking
• 🚦 Rate Limiting - Built-in request throttling
• 🌐 CORS - Configurable cross-origin resource sharing
• 🔒 Security - Helmet, input validation, and sanitization
• 📝 Internationalization - Multi-language support
• 🎯 Health Checks - Application and database health endpoints

🛠️ Tech Stack

• Framework: NestJS 11.x
• Language: TypeScript 5.9
• Database: PostgreSQL with Prisma ORM 6.x
• Cache/Queue: Redis with Bull 4.x
• Authentication: JWT with Passport
• File Storage: AWS S3
• Email: AWS SES
• Documentation: Swagger/OpenAPI
• Testing: Jest 30.x with SWC
• Logging: Pino (structured JSON logging)
• Validation: class-validator & class-transformer
• MCP Integration: @hmake98/nestjs-mcp for AI capabilities
• Containerization: Docker & Docker Compose

🚀 Quick Start

Prerequisites

• Node.js >= 20.0.0
• Yarn >= 1.22.0
• Docker & Docker Compose (for containerized setup)
• PostgreSQL (if running locally)
• Redis (if running locally)

1. Clone and Install

# Clone the repository
git clone https://github.com/hmake98/nestjs-starter.git
cd nestjs-starter

# Install dependencies
yarn install

2. Environment Setup

# Copy environment template
cp .env.example .env

# Edit the environment file with your configuration
nano .env  # or use your preferred editor

3. Database Setup

# Generate Prisma client
yarn generate

# Run database migrations
yarn migrate

# (Optional) Seed email templates
yarn seed:email

4. Start Development Server

# Development mode with hot reload
yarn dev

# Or using Docker Compose (recommended for full stack)
docker-compose up --build

The API will be available at:

• API: http://localhost:3001
• Documentation: http://localhost:3001/docs
• MCP Playground: http://localhost:3001/mcp/playground (for testing AI tools)

📋 Environment Configuration

Create a .env file based on .env.example template. All environment variables are documented with comments in the template file.

Application Settings

| Variable | Description | Default | Required | | ------------------- | ---------------------------------------- | ------------- | -------- | | APP_ENV | Environment mode | local | Yes | | APP_NAME | Application name | nestjs-starter | No | | APP_DEBUG | Enable debug mode | true | No | | APP_LOG_LEVEL | Logging level | debug | No | | APP_CORS_ORIGINS | Comma-separated allowed CORS origins | * | No |

HTTP Server Configuration

| Variable | Description | Default | Required | | -------------------------- | ----------------------------- | --------- | -------- | | HTTP_HOST | Server bind address | 0.0.0.0 | No | | HTTP_PORT | Server port | 3001 | No | | HTTP_VERSIONING_ENABLE | Enable API versioning | true | No | | HTTP_VERSION | Default API version | 1 | No |

Authentication & JWT

| Variable | Description | Example | Required | | --------------------------- | ---------------------------- | --------------------------------------- | -------- | | AUTH_ACCESS_TOKEN_SECRET | JWT access token secret | Generate with openssl rand -base64 32 | Yes | | AUTH_REFRESH_TOKEN_SECRET | JWT refresh token secret | Generate with openssl rand -base64 32 | Yes | | AUTH_ACCESS_TOKEN_EXP | Access token expiration | 1d (1 day) | No | | AUTH_REFRESH_TOKEN_EXP | Refresh token expiration | 7d (7 days) | No |

Database Configuration

| Variable | Description | Example | Required | | -------------- | ---------------------------- | ---------------------------------------------------- | -------- | | DATABASE_URL | PostgreSQL connection string | postgresql://user:pass@host:5432/db?schema=public | Yes |

AWS Configuration

| Variable | Description | Example | Required | | ----------------------------- | -------------------------------- | ------------- | ------------------ | | AWS_ACCESS_KEY | AWS IAM access key | - | For AWS features | | AWS_SECRET_KEY | AWS IAM secret key | - | For AWS features | | AWS_S3_REGION | S3 bucket region | us-east-1 | For S3 uploads | | AWS_S3_BUCKET | S3 bucket name | my-bucket | For S3 uploads | | AWS_S3_PRESIGN_LINK_EXPIRES | Pre-signed URL expiration (sec) | 1200 | No | | AWS_SES_REGION | SES service region | us-east-1 | For email service | | AWS_SES_SOURCE_EMAIL | Verified sender email | no-reply@example.com | For email service |

Redis Configuration

| Variable | Description | Default | Required | | ------------------ | --------------------- | ----------- | -------- | | REDIS_HOST | Redis host | redis | Yes | | REDIS_PORT | Redis port | 6379 | No | | REDIS_PASSWORD | Redis password | - | No | | REDIS_ENABLE_TLS | Enable TLS for Redis | false | No |

Model Context Protocol (MCP)

| Variable | Description | Default | Required | | --------------------- | --------------------- | -------------------- | -------- | | MCP_SERVER_NAME | MCP server name | nestjs-starter-mcp | No | | MCP_SERVER_VERSION | MCP server version | 1.0.0 | No | | MCP_LOG_LEVEL | MCP logging level | info | No |

Error Tracking

| Variable | Description | Example | Required | | ------------- | -------------------------- | ------- | -------- | | SENTRY_DSN | Sentry error tracking DSN | - | No |

Quick Setup

# Copy environment template
cp .env.example .env

# Generate JWT secrets
echo "AUTH_ACCESS_TOKEN_SECRET=$(openssl rand -base64 32)" >> .env
echo "AUTH_REFRESH_TOKEN_SECRET=$(openssl rand -base64 32)" >> .env

# Edit remaining values
nano .env

🐳 Docker Setup

Development with Docker Compose

# Start all services (app, database, redis)
docker-compose up --build

# Start only database and Redis (run app locally)
docker-compose up postgres redis

# Run in background
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

Production Docker Build

# Build production image (uses ci/Dockerfile for production)
docker build -f ci/Dockerfile -t nestjs-starter:latest .

# Run production container
docker run -p 3001:3001 --env-file .env nestjs-starter:latest

📚 API Documentation

Swagger UI

Visit /docs endpoint when the server is running for interactive API documentation.

Authentication

The API uses JWT Bearer token authentication:

# Login to get tokens
curl -X POST http://localhost:3001/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "password"}'

# Use access token in requests
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  http://localhost:3001/v1/user/profile

Available API Endpoints

Authentication (Public)

• POST /v1/auth/login - User login (email, password)
• POST /v1/auth/signup - User registration
• GET /v1/auth/refresh-token - Refresh access token

User Management (Protected)

• GET /v1/user/profile - Get current user profile
• PUT /v1/user - Update current user profile
• DELETE /v1/admin/user/:id - Delete user (Admin only)

Post Management (Protected)

• POST /v1/post - Create post
• GET /v1/post - List posts with pagination
• PUT /v1/post/:id - Update post (Author only)
• DELETE /v1/post/:id - Delete post (Author only)

Health Check (Public)

• GET /health - Application health status

🤖 Model Context Protocol (MCP) Integration

This boilerplate includes built-in support for the Model Context Protocol (MCP), enabling AI-powered features through tools, resources, and prompts.

What is MCP?

MCP is a standardized protocol for integrating AI capabilities into applications. It allows you to:

• Tools: Execute functions through AI (e.g., calculations, data transformations)
• Resources: Provide data to AI (e.g., documentation, configuration)
• Prompts: Template AI interactions (e.g., code reviews, documentation generation)

MCP Playground

Access the interactive MCP playground at http://localhost:3001/mcp/playground to:

• Test all available tools, resources, and prompts
• View auto-generated schemas
• Execute operations with real-time feedback

Built-in Examples

The boilerplate includes example MCP implementations in src/common/mcp/services/:

Tools (8 implemented)

• Math Operations: add, subtract, multiply, divide
• Text Utilities: toUpperCase, toLowerCase
• System Tools: generateUUID, getCurrentTimestamp

Resources (10 implemented)

• API Documentation: docs://api/overview, docs://api/auth, docs://api/user, docs://api/post
• Server Status: status://server
• Configuration: config://nodeVersion, config://platform, config://environment, config://port

Prompts (5 implemented)

• code-review - Review code for best practices
• generate-api-docs - Generate API documentation
• generate-nestjs-service - Generate NestJS service with CRUD
• optimize-query - Get query optimization suggestions
• generate-unit-tests - Generate Jest test cases

Prompts (AI Templates)

// Code assistance prompts
- code-review        // Review code for best practices
- bug-analysis       // Analyze and suggest bug fixes
- documentation      // Generate documentation
- test-generation    // Generate unit tests

Creating Custom MCP Services

1. Create a Tool Service

// src/modules/your-module/services/mcp.tools.service.ts
import { Injectable } from '@nestjs/common';
import { MCPTool, MCPToolWithParams } from '@hmake98/nestjs-mcp';

@Injectable()
export class YourMCPToolsService {
    // Simple tool (auto-infers parameters from TypeScript types)
    @MCPTool({
        name: 'customTool',
        description: 'Your custom tool description',
    })
    async customTool(params: { input: string }): Promise<string> {
        // Your business logic here
        return `Processed: ${params.input}`;
    }

    // Tool with explicit parameter definitions
    @MCPToolWithParams({
        name: 'complexTool',
        description: 'A more complex tool with explicit params',
        parameters: [
            {
                name: 'userId',
                type: 'string',
                description: 'The user ID to process',
                required: true,
            },
            {
                name: 'options',
                type: 'object',
                description: 'Additional options',
                required: false,
            },
        ],
    })
    async complexTool(params: { userId: string; options?: any }): Promise<any> {
        // Your complex business logic
        return { success: true, userId: params.userId };
    }
}

2. Create a Resource Service

// src/modules/your-module/services/mcp.resources.service.ts
import { Injectable } from '@nestjs/common';
import { MCPResource } from '@hmake98/nestjs-mcp';

@Injectable()
export class YourMCPResourcesService {
    @MCPResource({
        uri: 'data://your-resource',
        name: 'Your Resource',
        description: 'Provides access to your data',
        mimeType: 'application/json',
    })
    async getResource() {
        return {
            uri: 'data://your-resource',
            mimeType: 'application/json',
            text: JSON.stringify({
                data: 'your data',
                timestamp: new Date().toISOString()
            }),
        };
    }
}

3. Create a Prompt Service

// src/modules/your-module/services/mcp.prompts.service.ts
import { Injectable } from '@nestjs/common';
import { MCPPrompt } from '@hmake98/nestjs-mcp';

@Injectable()
export class YourMCPPromptsService {
    @MCPPrompt({
        name: 'customPrompt',
        description: 'Custom AI prompt template',
        arguments: [
            {
                name: 'context',
                description: 'Context for the prompt',
                required: true,
            },
        ],
    })
    async customPrompt(args: { context: string }) {
        return {
            messages: [
                {
                    role: 'user',
                    content: {
                        type: 'text',
                        text: `Given the context: ${args.context}, please provide analysis.`,
                    },
                },
            ],
        };
    }
}

4. Register in Module

// src/modules/your-module/your-module.module.ts
import { Module } from '@nestjs/common';
import { YourMCPToolsService } from './services/mcp.tools.service';
import { YourMCPResourcesService } from './services/mcp.resources.service';
import { YourMCPPromptsService } from './services/mcp.prompts.service';

@Module({
    providers: [
        YourMCPToolsService,
        YourMCPResourcesService,
        YourMCPPromptsService,
    ],
    exports: [
        YourMCPToolsService,
        YourMCPResourcesService,
        YourMCPPromptsService,
    ],
})
export class YourModule {}

MCP services are auto-discovered - no additional registration needed! Just create the services with decorators and they'll automatically appear in the MCP playground.

Configuration

MCP settings can be configured via environment variables:

MCP_SERVER_NAME="your-mcp-server"
MCP_SERVER_VERSION="1.0.0"
MCP_LOG_LEVEL="info"  # debug, info, warn, error

Learn More

• MCP Package Documentation
• MCP Protocol Specification

🧪 Testing

The project uses Jest with SWC for fast test execution. Tests are located in the test/ directory, mirroring the src/ structure.

# Run all tests
yarn test

# Run tests in watch mode (requires manual setup)
jest --config test/jest.json --watch

# Debug tests
yarn test:debug

Test Coverage (18 test suites with 90%+ coverage threshold):

• test/common/ - 11 test suites for shared services (auth, AWS, cache, database, file, helpers, MCP, message)
• test/modules/ - 2 test suites for feature modules (user, post)
• test/workers/ - 1 test suite for email processor
• test/mcp/ - 3 test suites for MCP services (tools, resources, prompts)
• test/mocks/ - Mock data generators using @faker-js/faker

Example Test:

import { Test, TestingModule } from '@nestjs/testing';
import { UserService } from 'src/modules/user/services/user.service';

describe('UserService', () => {
    let service: UserService;

    beforeEach(async () => {
        const module: TestingModule = await Test.createTestingModule({
            providers: [UserService, /* mock dependencies */],
        }).compile();

        service = module.get<UserService>(UserService);
    });

    it('should be defined', () => {
        expect(service).toBeDefined();
    });
});

📁 Project Structure

src/
├── app/                          # Application module and health checks
├── common/                       # Shared modules (14 services)
│   ├── auth/                    # JWT authentication with strategies
│   ├── aws/                     # AWS S3 & SES services
│   ├── cache/                   # Redis cache management
│   ├── config/                  # Configuration management
│   ├── database/                # Prisma ORM integration
│   ├── doc/                     # Documentation decorators
│   ├── file/                    # File upload handling
│   ├── helper/                  # Email, encryption, pagination utilities
│   ├── logger/                  # Pino structured logging
│   ├── mcp/                     # Model Context Protocol (AI integration)
│   │   ├── services/
│   │   │   ├── mcp.tools.service.ts        # Math, text, system tools
│   │   │   ├── mcp.resources.service.ts    # API docs, config resources
│   │   │   └── mcp.prompts.service.ts      # AI prompt templates
│   │   └── mcp.module.ts
│   ├── message/                 # i18n message service
│   ├── request/                 # Guards, decorators, middleware
│   └── response/                # Response formatting, error filters
├── languages/                   # i18n translation files
├── migrations/                  # Database migrations & seeders
├── modules/                     # Feature modules (2 implemented)
│   ├── post/                    # Post CRUD operations
│   │   ├── controllers/         # API endpoints
│   │   ├── services/            # Business logic
│   │   └── dto/                 # Data transfer objects
│   └── user/                    # User management & authentication
│       ├── controllers/         # API endpoints (public & admin)
│       ├── services/            # Business logic
│       └── dto/                 # Data transfer objects
└── workers/                     # Background job processors
    ├── processors/              # Bull queue processors (email)
    └── schedulers/              # Cron jobs (midnight scheduler)

🔧 Development Workflow

Code Quality

# Lint code
yarn lint

# Format code
yarn format

# Type checking
yarn build

Database Operations

# Generate Prisma client after schema changes
yarn generate

# Create new migration
yarn migrate

# Deploy migrations to production
yarn migrate:prod

# Open Prisma Studio
yarn studio

Background Jobs

# Seed email templates
yarn seed:email

# Remove email templates
yarn rollback:email

🚀 Deployment

Docker Production (Recommended)

# Build and tag production image
docker build -f ci/Dockerfile -t your-registry/nestjs-starter:v1.0.0 .

# Push to registry
docker push your-registry/nestjs-starter:v1.0.0

# Run with Docker
docker run -d -p 3001:3001 --env-file .env --name nestjs-app your-registry/nestjs-starter:v1.0.0

# Or deploy with Docker Compose (full stack)
docker-compose up -d --build

Cloud Deployment Examples

AWS ECS

# 1. Create ECR repository
aws ecr create-repository --repository-name nestjs-starter --region us-east-1

# 2. Authenticate Docker to ECR
aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin <account-id>.dkr.ecr.us-east-1.amazonaws.com

# 3. Build and push
docker build -f ci/Dockerfile -t nestjs-starter:latest .
docker tag nestjs-starter:latest <account-id>.dkr.ecr.us-east-1.amazonaws.com/nestjs-starter:latest
docker push <account-id>.dkr.ecr.us-east-1.amazonaws.com/nestjs-starter:latest

# 4. Create ECS task definition and service through AWS Console or CLI

Google Cloud Run

# 1. Build and submit to Google Container Registry
gcloud builds submit --tag gcr.io/PROJECT-ID/nestjs-starter

# 2. Deploy to Cloud Run
gcloud run deploy nestjs-starter \
  --image gcr.io/PROJECT-ID/nestjs-starter \
  --platform managed \
  --region us-central1 \
  --allow-unauthenticated \
  --set-env-vars "APP_ENV=production" \
  --port 3001

DigitalOcean App Platform

# 1. Push to Docker Hub or DigitalOcean Container Registry
docker build -f ci/Dockerfile -t your-dockerhub/nestjs-starter:latest .
docker push your-dockerhub/nestjs-starter:latest

# 2. Create app via DigitalOcean Console
#    - Select Docker Hub as source
#    - Configure environment variables
#    - Add PostgreSQL and Redis managed databases

Heroku

# 1. Login to Heroku
heroku login
heroku container:login

# 2. Create app
heroku create your-app-name

# 3. Add PostgreSQL and Redis addons
heroku addons:create heroku-postgresql:mini
heroku addons:create heroku-redis:mini

# 4. Build and push
docker build -f ci/Dockerfile -t registry.heroku.com/your-app-name/web .
docker push registry.heroku.com/your-app-name/web

# 5. Release
heroku container:release web -a your-app-name

🔐 Security Best Practices

1. Environment Variables: Never commit sensitive data - use .env.example as template only
2. JWT Secrets: Use strong, randomly generated secrets (minimum 32 characters)

   openssl rand -base64 32
   

3. Global Guards: All routes are protected by default (JWT, Roles, Throttler)
4. Password Hashing: Uses Argon2 for secure password storage
5. Rate Limiting: Throttler guard prevents brute force attacks
6. CORS: Configure APP_CORS_ORIGINS to restrict allowed domains
7. Helmet: Security headers configured automatically
8. Input Validation: class-validator validates all DTOs automatically
9. Database: Use connection pooling, read replicas, and prepared statements (Prisma handles this)
10. HTTPS: Always use TLS in production
11. Monitoring: Sentry integration for error tracking and monitoring
12. Soft Deletes: Models support soft deletion to prevent data loss

🔧 Troubleshooting

Common Issues and Solutions

Database Connection Issues

Problem: Error: Can't reach database server

# Check if PostgreSQL is running
docker-compose ps postgres
# or
kubectl get pods -n nestjs-starter | grep postgres

# Check DATABASE_URL format
# Correct: postgresql://username:password@host:5432/database?schema=public

# For Docker: use service name as host
DATABASE_URL="postgresql://postgres:password@postgres:5432/db"

# For local: use localhost
DATABASE_URL="postgresql://postgres:password@localhost:5432/db"

# For Kubernetes: use service name
DATABASE_URL="postgresql://postgres:password@postgres.nestjs-starter.svc.cluster.local:5432/db"

Redis Connection Issues

Problem: Error: Redis connection refused

# Check if Redis is running
docker-compose ps redis
# or
kubectl get pods -n nestjs-starter | grep redis

# Verify REDIS_HOST matches your setup
# Docker: REDIS_HOST=redis
# Local: REDIS_HOST=localhost
# K8s: REDIS_HOST=redis.nestjs-starter.svc.cluster.local

Prisma Migration Errors

Problem: Migration failed or Schema is out of sync

# Reset database (⚠️ DESTRUCTIVE - development only)
docker-compose down -v
docker-compose up -d postgres redis
yarn generate
yarn migrate

# For production, run migrations explicitly
yarn migrate:prod

# If stuck, check migration status
npx prisma migrate status

Port Already in Use

Problem: Error: listen EADDRINUSE: address already in use :::3001

# Find process using the port (macOS/Linux)
lsof -i :3001

# Kill the process
kill -9 <PID>

# Or use a different port
HTTP_PORT=3002 yarn dev

Docker Build Fails

Problem: ERROR [builder X/Y] RUN yarn install --frozen-lockfile

# Clear Docker build cache
docker builder prune -af

# Rebuild without cache
docker-compose build --no-cache

# Check Docker resources (ensure enough memory/disk)
docker system df
docker system prune

JWT Token Issues

Problem: Unauthorized or Invalid token

# Ensure secrets are properly set
echo $AUTH_ACCESS_TOKEN_SECRET
echo $AUTH_REFRESH_TOKEN_SECRET

# Secrets must be the same across restarts
# Use strong random values (min 32 characters)
openssl rand -base64 32

# Check token expiration settings
AUTH_ACCESS_TOKEN_EXP=1d   # 1 day
AUTH_REFRESH_TOKEN_EXP=7d  # 7 days

AWS S3/SES Integration Issues

Problem: AccessDenied or InvalidAccessKeyId

# Verify AWS credentials
aws configure list
aws sts get-caller-identity

# Check IAM permissions for S3
# Required: s3:PutObject, s3:GetObject, s3:DeleteObject

# Check IAM permissions for SES
# Required: ses:SendEmail, ses:SendRawEmail

# Verify email is verified in SES (sandbox mode)
aws ses list-verified-email-addresses

# Check S3 bucket exists and region matches
aws s3 ls s3://your-bucket-name --region us-east-1

Tests Failing

Problem: Tests fail unexpectedly

# Clear test cache
yarn test --clearCache

# Run tests with verbose output
yarn test --verbose

# Run specific test file
yarn test --testPathPattern=user.service.spec.ts

# Check for missing mocks
# Ensure all external dependencies are properly mocked

TypeScript Compilation Errors

Problem: error TS2307: Cannot find module

# Clear build cache and reinstall
rm -rf dist node_modules yarn.lock
yarn install
yarn build

# Regenerate Prisma client
yarn generate

# Check tsconfig.json paths configuration

Memory/Performance Issues

Problem: Application crashes or runs slowly

# Check memory usage
docker stats

# Increase Node.js memory limit
NODE_OPTIONS="--max-old-space-size=4096" yarn start

# Enable garbage collection logs
NODE_OPTIONS="--trace-gc" yarn dev

# Check for memory leaks in production
# Use clinic.js or node --inspect

Kubernetes Pod CrashLoopBackOff

Problem: Pod keeps restarting

# Check pod logs
kubectl logs -f <pod-name> -n nestjs-starter
kubectl logs <pod-name> --previous -n nestjs-starter

# Describe pod for events
kubectl describe pod <pod-name> -n nestjs-starter

# Common causes:
# 1. Missing environment variables
# 2. Database not ready (add init containers)
# 3. Health check failing too quickly (adjust liveness/readiness probes)
# 4. Insufficient resources (increase limits)

# Check events
kubectl get events -n nestjs-starter --sort-by='.lastTimestamp'

Email Not Sending (SES)

Problem: Emails not being sent

# Check SES sandbox mode
# In sandbox, you can only send to verified emails

# Verify sender email
aws ses verify-email-identity --email-address your-email@domain.com

# Check SES sending quota
aws ses get-send-quota

# Check email queue (Bull)
# Visit Bull Board or check Redis
redis-cli KEYS "bull:email:*"

# Check worker logs
docker-compose logs worker

Getting Help

If you encounter issues not covered here:

1. Check Logs: Always start with application logs

   # Docker
   docker-compose logs -f app
   
   # Kubernetes
   kubectl logs -f deployment/nestjs-app -n nestjs-starter
   

2. Enable Debug Mode:

   APP_DEBUG=true
   APP_LOG_LEVEL=debug
   

3. Search Issues: Check GitHub Issues

4. Create an Issue: Provide:

   • Error message
   • Steps to reproduce
   • Environment (Node version, OS, Docker/K8s)
   • Relevant logs

---

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit changes: git commit -m 'Add amazing feature'
4. Push to branch: git push origin feature/amazing-feature
5. Open a Pull Request

Development Guidelines

• Follow TypeScript and ESLint rules
• Write tests for new features
• Update documentation when needed
• Use conventional commit messages
• Ensure all tests pass before submitting PR

📄 Scripts Reference

| Script | Description | | --------------- | ---------------------------------------- | | yarn dev | Start development server with hot reload | | yarn build | Build for production | | yarn start | Start production server | | yarn test | Run unit tests | | yarn lint | Lint and fix code | | yarn format | Format code with Prettier | | yarn generate | Generate Prisma client | | yarn migrate | Run database migrations | | yarn studio | Open Prisma Studio |

🔗 Useful Links

• NestJS Documentation
• Prisma Documentation
• Passport JWT Strategy
• Bull Queue
• Pino Logger
• class-validator
• Docker Documentation
• Model Context Protocol (MCP)
• @hmake98/nestjs-mcp Package

📝 License

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

👨‍💻 Author

Harsh Makwana

• 🌐 GitHub
• 💼 LinkedIn
• 📷 Instagram

🙏 Support

If this project helped you, please consider giving it a ⭐️!

---

Happy Coding! 🎉