nestjs-best-practices

What this skill does

# NestJS Best Practices

Comprehensive guide for building production-ready NestJS applications. Contains 26 rules across 13 categories, covering security, architecture, performance, validation, database operations, authentication, and advanced patterns.

## When to Apply

Reference these guidelines when:
- Writing new NestJS modules, controllers, or services
- Implementing authentication and authorization
- Setting up Prisma database operations
- Creating DTOs and validation pipes
- Adding middleware or guards
- Implementing error handling and logging
- Reviewing NestJS code for best practices
- Refactoring existing NestJS applications

## Rule Categories by Priority

| Priority | Category | Impact | Prefix |
|----------|----------|--------|--------|
| 1 | Security | CRITICAL | `security-` |
| 2 | Performance | HIGH | `performance-` |
| 3 | Architecture | HIGH | `architecture-` |
| 4 | Error Handling | HIGH | `error-handling-` |
| 5 | Validation | CRITICAL | `validation-` |
| 6 | Database | CRITICAL | `database-` |
| 7 | Authentication | CRITICAL | `auth-` |
| 8 | API | MEDIUM | `api-` |
| 9 | Configuration | CRITICAL | `config-` |
| 10 | Testing | MEDIUM | `testing-` |
| 11 | Deployment | MEDIUM | `deployment-` |
| 12 | Middleware | MEDIUM | `middleware-` |
| 13 | Advanced | HIGH | `advanced-` |

## Quick Reference

### 1. Security (CRITICAL)

- `security-cors-whitelist` - Enable CORS with whitelist origins only
- `security-dependency-audit` - Regular dependency security audits with bun
- `security-helmet-headers` - Use Helmet middleware for security headers

### 2. Performance (HIGH)

- `performance-redis-caching` - Cache frequently used data with Redis

### 3. Architecture (HIGH)

- `architecture-short-functions` - Keep functions short and single purpose
- `architecture-feature-modules` - Organize code by feature modules
- `architecture-no-dead-code` - Remove unused code and dependencies
- `architecture-thin-controllers` - Single responsibility - separate controller and service
- `architecture-naming-conventions` - Use consistent naming conventions
- `architecture-event-driven` - Use event-driven architecture for loose coupling

### 4. Error Handling (HIGH)

- `error-handling-exception-filter` - Enable global exception filter
- `error-handling-structured-logging` - Implement proper logging strategy

### 5. Validation (CRITICAL)

- `validation-custom-pipes` - Create custom pipes for query parameter transformation
- `validation-dto-validation` - Validate all inputs with DTOs and ValidationPipe

### 6. Database (CRITICAL)

- `database-parameterized-queries` - Use parameterized queries to prevent SQL injection (Prisma v7)

### 7. Authentication (CRITICAL)

- `auth-password-hashing` - Use Bun's built-in Crypto for secure password hashing (argon2/bcrypt)
- `auth-route-guards` - Use guards for route protection

### 8. API (MEDIUM)

- `api-cursor-pagination` - Use cursor-based pagination for large datasets
- `api-swagger-docs` - Generate Swagger/OpenAPI documentation

### 9. Configuration (CRITICAL)

- `config-no-secrets` - Never hardcode secrets - use environment variables

### 10. Testing (MEDIUM)

- `testing-unit-tests` - Write comprehensive unit tests

### 11. Deployment (MEDIUM)

- `deployment-health-checks` - Implement health check endpoints

### 12. Middleware (MEDIUM)

- `middleware-compression` - Enable compression middleware for responses
- `middleware-rate-limiting` - Implement rate limiting for all routes

### 13. Advanced (HIGH)

- `advanced-lazy-loading` - Lazy load non-critical modules
- `advanced-scheduled-tasks` - Use @nestjs/schedule for cron jobs and scheduled tasks

## How to Use

Read individual rule files for detailed explanations and code examples:

```
rules/security-cors-whitelist.md
rules/auth-route-guards.md
rules/validation-dto-validation.md
rules/_sections.md
```

Each rule file contains:
- "For AI Agents" section with step-by-step implementation instructions
- Quick Reference Checklist for code review
- ❌ WRONG vs ✅ CORRECT patterns with file locations
- Installation commands using `bun add`
- Comprehensive code examples for NestJS + Prisma
- Security and performance considerations

## Key Patterns

### Agent-Friendly Format

All rules are optimized for AI agents with:
- Explicit file locations (e.g., `src/users/users.service.ts`)
- Step-by-step "For AI Agents" sections
- ✅ CORRECT vs ❌ WRONG pattern comparisons
- Quick Reference Checklists
- Clear installation instructions

### Technology Stack

- **Framework**: NestJS with Express/Fastify adapter
- **Runtime**: Bun (native crypto, scheduling)
- **Database**: Prisma v7 (sql template tag, interactive transactions)
- **Validation**: class-validator + class-transformer
- **Security**: Helmet, CORS whitelisting, rate limiting
- **Scheduling**: @nestjs/schedule with cron/interval decorators
- **Events**: EventEmitter2 for loose coupling

## Full Compiled Document

For the complete guide with all rules expanded: `AGENTS.md`

## Build Commands

```bash
cd packages/nestjs-best-practices-build
bun install
bun run build      # Generate AGENTS.md
bun run validate   # Validate rule files
bun run dev        # Build and validate
```

## Statistics

- **13 sections** covering all aspects of NestJS development
- **26 rules** prioritized by impact (CRITICAL, HIGH, MEDIUM)
- **Prisma v7** compatible database patterns
- **Bun runtime** native features (Crypto.hashPassword, @nestjs/schedule)
- **Agent-optimized** for automated code generation and review