NestJS Starter

A production-ready NestJS boilerplate for building scalable, enterprise-grade REST APIs.

Features

Tech Stack

• Runtime: Node.js 24, TypeScript 6
• Framework: NestJS 11
• ORM: Prisma 7 + PostgreSQL 16
• Cache / Queues: Redis 7, ioredis, BullMQ
• Auth: Passport.js, JWT (@nestjs/jwt), argon2
• Logger: nestjs-pino, pino-pretty
• Testing: Jest 30, SWC, Supertest

Quick Start

Prerequisites

• Node.js >= 24
• npm >= 11
• PostgreSQL and Redis (local or Docker)

1. Clone and install

git clone https://github.com/hmake98/nestjs-starter.git
cd nestjs-starter
npm install

2. Environment setup

cp .env.example .env
# Edit .env — set DATABASE_URL, REDIS_URL, and JWT secrets

Generate JWT secrets:

openssl rand -base64 32   # run twice — one for access, one for refresh

3. Database setup

npm run db:generate     # generate Prisma client
npm run db:migrate      # run migrations
npm run seed:admin      # (optional) create default admin user

4. Start in development mode

npm run dev

API is available at http://localhost:3000. Swagger UI at http://localhost:3000/docs.

Scripts

Project Structure

src/
├── app/                        # Root module, config, health controller
│   ├── config/                 # Typed config factories (app, auth, redis, doc, seed)
│   ├── controllers/            # HealthController
│   └── enums/                  # APP_ENVIRONMENT
├── common/                     # Shared infrastructure
│   ├── bullmq/                 # BullMQ module (Redis-backed queues)
│   ├── cache/                  # Redis cache module + CacheService
│   ├── database/               # Prisma module, DatabaseService, repositories
│   ├── doc/                    # Swagger decorator helpers (@ApiEndpoint)
│   ├── logger/                 # Pino logger configuration
│   ├── message/                # i18n message resolution
│   ├── request/                # Guards, decorators, throttler
│   └── response/               # Interceptor, exception filter, serializer
├── modules/
│   ├── auth/                   # JWT auth — login, signup, refresh
│   └── user/                   # User CRUD — profile, update, delete
├── workers/                    # Cron schedulers
└── migration/                  # CLI seed commands
docs/
└── features/                   # Feature specs (source of truth for AI scaffolding)
    └── _template.md            # Copy this to create a new spec

Module dependency rules

• Feature modules (AuthModule, UserModule) import DatabaseModule directly — they never import each other.
• CommonModule aggregates infrastructure for AppModule only.
• Global providers (guards, interceptors, filters) are registered via APP_GUARD / APP_INTERCEPTOR / APP_FILTER.

Feature Spec Workflow

This project uses a spec-driven development model. Before writing or generating any feature code, you write a feature spec — a structured markdown file that serves as the single source of truth for every AI tool.

How it works

1. Copy the template

   cp docs/features/_template.md docs/features/<name>.md
   

2. Fill in the spec — every section maps directly to generated code:

   Section	Used for
   Prisma Model	Schema block added verbatim to prisma/schema.prisma
   Endpoints	Which methods go in public vs admin controller
   Business Rules	Service method logic and guards
   DTO Fields	class-validator decorators and @ApiProperty examples
   i18n Keys	src/languages/en/<name>.json content
   Test Scenarios	it('should...') blocks in the Jest spec
   Open Questions	AI stops and asks before generating if any are unchecked

3. Run the scaffold command (Claude Code or Copilot Chat):

   /scaffold-feature post
   

   The AI reads your spec and generates all files — schema, repository, DTOs, service, controllers, module, i18n JSON, and tests — without any back-and-forth.

4. Run the migration

   npm run db:migrate -- --name add_posts_table
   

No spec? The AI infers a minimal CRUD structure from the feature name and reminds you to write a spec afterward for future changes.

AI Developer Workflows

This project ships with full configuration for both Claude Code and GitHub Copilot. Both are set up so generated code matches project conventions on the first attempt — no extra prompting needed.

Claude Code

Install: claude.ai/code

The CLAUDE.md file gives Claude Code complete project context. Claude reads it at the start of every session — no repo scanning required.

Commands

Skills (multi-step workflows)

Hooks

A PostToolUse hook runs automatically after every file edit:

• .ts files — runs eslint --fix on the saved file
• schema.prisma — runs npm run db:generate automatically

Permissions

.claude/settings.json pre-approves safe read/run commands (npm, npx, find, grep, git log/status/diff) so Claude never pauses to ask for permission on routine operations.

GitHub Copilot

The .github/copilot-instructions.md file is automatically attached to every Copilot Chat session. It contains the same depth of context as CLAUDE.md — real code examples, guard order, DTO patterns, error-throwing shape, testing conventions — so Copilot generates correct code without any extra explanation.

Scoped Instructions (auto-applied by file type)

These files in .github/instructions/ are automatically applied when you edit matching files:

Prompt Files (Copilot Chat)

Type / in Copilot Chat to invoke these reusable prompts:

Note: Scoped instruction files and prompt files apply in Copilot Chat. The main copilot-instructions.md applies to both Chat and inline tab completions.

API Endpoints

All routes are versioned (/v1/...) unless marked as version-neutral.

Swagger UI is available at /docs in non-production environments.

Authentication

Protected routes require a Bearer token:

Authorization: Bearer <access_token>

Role-based access is enforced via the @AllowedRoles() decorator (array required):

@AllowedRoles([UserRole.ADMIN])
@Delete(':id')
deleteUser(@Param('id') id: string) { ... }

Public routes bypass JWT entirely:

@PublicRoute()
@Post('login')
login(@Body() dto: UserLoginDto) { ... }

Guard execution order: ThrottlerGuard → JwtAccessGuard → RolesGuard

Docker

The Dockerfile has three stages:

docker-compose.yml uses the dev stage. For a deployable image: docker build --target production.

The entrypoint (docker-entrypoint.sh) runs prisma generate and prisma migrate deploy before the app starts.

Set HTTP_HOST=0.0.0.0 inside Docker containers.

Environment Variables

Testing

npm test                # run all tests with coverage report

Coverage is collected from services, guards, filters, interceptors, and repositories. Thresholds are enforced — the suite fails if coverage drops below the configured minimums.

Mock pattern used throughout:

const mockRepository = { findById: jest.fn(), existsById: jest.fn() };
// Never jest.createMockFromModule — plain objects only
// Never jest.clearAllMocks() — clearMocks: true is global in test/jest.json

Commit Convention

Commits follow Conventional Commits:

<type>(<scope>): <subject>

Types: feat | fix | docs | style | refactor | perf | test | build | ci | chore | revert

Enforced by commitlint + Husky on every commit.

License

MIT