nestjs-best-practices

Files (37)

• SKILL.md
• _sections.md · rules/
• _template.md · rules/
• api-use-dto-serialization.md · rules/
• api-use-interceptors.md · rules/
• api-use-pipes.md · rules/
• api-versioning.md · rules/
• arch-app-vs-library-boundaries.md · rules/
• arch-avoid-circular-deps.md · rules/
• arch-dynamic-module-configuration.md · rules/
• arch-external-adapter-layer.md · rules/
• arch-feature-modules.md · rules/
• arch-module-sharing.md · rules/
• arch-shared-bootstrap-consistency.md · rules/
• arch-single-responsibility.md · rules/
• arch-use-repository-pattern.md · rules/
• devops-correlation-id-logging.md · rules/
• devops-graceful-shutdown.md · rules/
• devops-use-config-module.md · rules/
• devops-use-logging.md · rules/
• devops-worker-bootstrap-conventions.md · rules/
• di-avoid-service-locator.md · rules/
• di-interface-segregation.md · rules/
• di-liskov-substitution.md · rules/
• di-prefer-constructor-injection.md · rules/
• di-scope-awareness.md · rules/
• di-use-interfaces-tokens.md · rules/
• error-handle-async-errors.md · rules/
• error-throw-http-exceptions.md · rules/
• error-use-exception-filters.md · rules/
• perf-async-hooks.md · rules/
• perf-lazy-loading.md · rules/
• perf-optimize-contentstack.md · rules/
• security-rate-limiting.md · rules/
• security-validate-all-input.md · rules/
• test-mock-external-services.md · rules/
• test-use-testing-module.md · rules/

SKILL.md (first lines)

# NestJS Best Practices

## Overview

Comprehensive best practices guide for NestJS applications and monorepos. Contains 30+ rules across 8 categories, prioritized by impact to guide code generation, refactoring, review, and architecture decisions.

## When to Apply

Reference these guidelines when:

- Writing new NestJS modules, controllers, or services
- Designing shared NestJS packages in a monorepo
- Defining application bootstrap or worker startup paths
- Integrating third-party APIs, SDKs, queues, or schedulers
- Reviewing code for architecture and security issues
- Refactoring existing NestJS codebases
- Optimizing performance, ContentStack access, or OpenSearch queries

## Rule Categories by Priority

| Priority | Category             | Impact      | Prefix      |
| -------- | -------------------- | ----------- | ----------- |
| 1        | Architecture         | CRITICAL    | `arch-`     |
| 2        | Dependency Injection | CRITICAL    | `di-`       |
| 3        | Error Handling       | HIGH        | `error-`    |
| 4        | Security             | HIGH        | `security-` |
| 5        | Performance          | HIGH        | `perf-`     |
| 6        | Testing              | MEDIUM-HIGH | `test-`     |
| 7        | API Design           | MEDIUM      | `api-`      |
| 9        | DevOps & Deployment  | LOW-MEDIUM  | `devops-`   |

## Quick Reference

### 1. Architecture (CRITICAL)

- `arch-avoid-circular-deps` - Avoid circular module dependencies
- `arch-app-vs-library-boundaries` - Keep application bootstrap out of reusable libraries
- `arch-dynamic-module-configuration` - Expose explicit registration APIs for configurable packages
- `arch-external-adapter-layer` - Isolate third-party SDKs behind Nest services or adapters
- `arch-feature-modules` - Organize by feature, not technical layer
- `arch-module-sharing` - Proper module exports/imports, avoid duplicate providers
- `arch-shared-bootstrap-consistency` - Standardize global Nest setup across services and workers
- `arch-single-responsibility` - Focused services over "god services"
- `arch-use-repository-pattern` - Abstract database logic for testability

### 2. Dependency Injection (CRITICAL)

- `di-avoid-service-locator` - Avoid service locator anti-pattern
- `di-interface-segregation` - Interface Segregation Principle (ISP)
- `di-liskov-substitution` - Liskov Substitution Principle (LSP)
- `di-prefer-constructor-injection` - Constructor over property injection
- `di-scope-awareness` - Understand singleton/request/transient scopes
- `di-use-interfaces-tokens` - Use injection tokens for interfaces

### 3. Error Handling (HIGH)

- `error-use-exception-filters` - Centralized exception handling
- `error-throw-http-exceptions` - Use NestJS HTTP exceptions
- `error-handle-async-errors` - Handle async errors properly

### 4. Security (HIGH)

- `security-validate-all-input` - Validate with class-validator
- `security-rate-limiting` - Implement rate limiting

### 5. Performance (HIGH)

- `perf-async-hooks` - Proper async lifecycle hooks
- `perf-optimize-contentstack` - Reduce CMS round-trips and expensive content traversals
- `perf-lazy-loading` - Lazy load modules for faster startup

### 6. Testing (MEDIUM-HIGH)

- `test-use-testing-module` - Use NestJS testing utilities
- `test-mock-external-services` - Mock external dependencies

### 7. API Design (MEDIUM)

- `api-use-dto-serialization` - DTO and response serialization
- `api-use-interceptors` - Cross-cutting concerns
- `api-versioning` - API versioning strategies
- `api-use-pipes` - Input transformation with pipes

### 8. DevOps & Deployment (LOW-MEDIUM)

- `devops-correlation-id-logging` - Propagate request context through logs and async work
- `devops-worker-bootstrap-conventions` - Keep schedulers, workers, and HTTP services operationally aligned
- `devops-use-config-module` - Environment configuration
- `devops-use-logging` - Structured logging
- `devops-graceful-shutdown` - Zero-downtime deployments

## How to Use

Read individual rule files for detailed explanations and code examples:

```
rules/arch-avoid-circular-deps.md
rules/security-validate-all-input.md
rules/_sections.md
```

Each rule file contains:

- Brief explanation of why it matters
- When to apply the rule and what scope it covers
- Incorrect code example with explanation
- Correct code example with explanation
- Review checklist for code review or planning
- Additional context and references

## Verification

After applying a rule, confirm the code against that rule file's review checklist. Treat the CRITICAL/HIGH categories (Architecture, Dependency Injection, Error Handling, Security, Performance) as blocking — every applicable rule's checklist should pass before the change merges.

From sgpopov/ai-kit, MIT.

More from sgpopov/ai-kit