giuseppe-trisciuoglio/developer-kit

nestjs-best-practices

Provides comprehensive NestJS best practices including modular architecture, dependency injection scoping, exception filters, DTO validation with class-validator, and Drizzle ORM integration.

查看源码

使用方法

  1. 复制安装命令,在自己的智能体环境安装前先检查源码包。
  2. 从原始文档核对所需工具、凭据和支持的宿主。
  3. 说明输入材料与期望交付物,并对照来源检查输出。
npx skills add https://github.com/giuseppe-trisciuoglio/developer-kit --skill nestjs-best-practices

开始前需了解

  • 安装不包含模型订阅、API 额度或访问文件的权限。
  • 仓库星数和安装量反映活跃情况,不等于独立质量或安全测试。
仓库原始内容

按源仓库内容呈现,保留标题、案例、代码、表格、链接以及原文引用的演示图片。

NestJS Best Practices

Overview

Grounded in the Official NestJS Documentation, this skill enforces modular architecture, dependency injection scoping, exception filters, DTO validation with class-validator, and Drizzle ORM integration patterns.

When to Use

  • Designing/refactoring NestJS modules or dependency injection
  • Creating exception filters, validating DTOs, or integrating Drizzle ORM
  • Reviewing code for anti-patterns or onboarding to a NestJS codebase

Instructions

1. Modular Architecture

Follow strict module encapsulation. Each domain feature should be its own @Module():

  • Export only what other modules need — keep internal providers private
  • Use forwardRef() only as a last resort for circular dependencies; prefer restructuring
  • Group related controllers, services, and repositories within the same module
  • Use a SharedModule for cross-cutting concerns (logging, configuration, caching)

See references/arch-module-boundaries.md for enforcement rules.

2. Dependency Injection

Choose the correct provider scope based on use case:

ScopeLifecycleUse Case
DEFAULTSingleton (shared)Stateless services, repositories
REQUESTPer-request instanceRequest-scoped data (tenant, user context)
TRANSIENTNew instance per injectionStateful utilities, per-consumer caches
  • Default to DEFAULT scope — only use REQUEST or TRANSIENT when justified
  • Use constructor injection exclusively — avoid property injection
  • Register custom providers with useClass, useValue, useFactory, or useExisting

See references/di-provider-scoping.md for enforcement rules.

3. Request Lifecycle

Understand and respect the NestJS request processing pipeline:

Middleware → Guards → Interceptors (before) → Pipes → Route Handler → Interceptors (after) → Exception Filters
  • Middleware: Cross-cutting concerns (logging, CORS, body parsing)
  • Guards: Authorization and authentication checks (return true/false)
  • Interceptors: Transform response data, add caching, measure timing
  • Pipes: Validate and transform input parameters
  • Exception Filters: Catch and format error responses

4. Error Handling

Standardize error responses across the application:

  • Extend HttpException for HTTP-specific errors
  • Create domain-specific exception classes (e.g., OrderNotFoundException)
  • Implement a global ExceptionFilter for consistent error formatting
  • Use the Result pattern for expected business logic failures
  • Never silently swallow exceptions

See references/error-exception-filters.md for enforcement rules.

5. Validation

Enforce input validation at the API boundary:

  • Enable ValidationPipe globally with transform: true and whitelist: true
  • Decorate all DTO properties with class-validator decorators
  • Use class-transformer for type coercion (@Type(), @Transform())
  • Create separate DTOs for Create, Update, and Response operations
  • Never trust raw user input — validate everything

See references/api-validation-dto.md for enforcement rules.

6. Database Patterns (Drizzle ORM)

Integrate Drizzle ORM following NestJS provider conventions:

  • Wrap the Drizzle client in an injectable provider
  • Use the Repository pattern for data access encapsulation
  • Define schemas in dedicated schema files per domain module
  • Use transactions for multi-step operations
  • Keep database logic out of controllers

See references/db-drizzle-patterns.md for enforcement rules.

Best Practices

AreaDoDon't
ModulesOne module per domain featureDump everything in AppModule
DI ScopingDefault to singleton scopeUse REQUEST scope without justification
Error HandlingCustom exception filters + domain errorsBare try/catch with console.log
ValidationGlobal ValidationPipe + DTO decoratorsManual if checks in controllers
DatabaseRepository pattern with injected clientDirect DB queries in controllers
TestingUnit test services, e2e test controllersSkip tests or test implementation details
Configuration@nestjs/config with typed schemasHardcode values or use process.env

Examples

Example: New Domain Module with Validation

When building a "Product" feature, follow this workflow:

1. Create the module with proper encapsulation:

typescript
// product/product.module.ts
@Module({
  imports: [DatabaseModule],
  controllers: [ProductController],
  providers: [ProductService, ProductRepository],
  exports: [ProductService], // Only export what others need
})
export class ProductModule {}

2. Create validated DTOs:

typescript
// product/dto/create-product.dto.ts
import { IsString, IsNumber, IsPositive, MaxLength } from 'class-validator';

export class CreateProductDto {
  @IsString() @MaxLength(255) readonly name: string;
  @IsNumber() @IsPositive() readonly price: number;
}

3. Service with error handling:

typescript
@Injectable()
export class ProductService {
  constructor(private readonly productRepository: ProductRepository) {}

  async findById(id: string): Promise<Product> {
    const product = await this.productRepository.findById(id);
    if (!product) throw new ProductNotFoundException(id);
    return product;
  }
}

4. Verify module registration:

bash
# Check module is imported in AppModule
grep -r "ProductModule" src/app.module.ts

# Run e2e to confirm exports work
npx jest --testPathPattern="product"

Constraints and Warnings

  1. Do not mix scopes without justification — REQUEST-scoped providers cascade to all dependents
  2. Never access database directly from controllers — always go through service and repository layers
  3. Avoid `forwardRef()` — restructure modules to eliminate circular dependencies
  4. Do not skip `ValidationPipe` — always validate at the API boundary with DTOs
  5. Never hardcode secrets — use @nestjs/config with environment variables
  6. Keep modules focused — one domain feature per module, avoid "god modules"

References

  • references/architecture.md — Deep-dive into NestJS architectural patterns
  • references/ — Individual enforcement rules with correct/incorrect examples
  • assets/templates/ — Starter templates for common NestJS components

按任务相关推荐

来自同一仓库

更多 Skills

全部 Skills
giuseppe-trisciuoglio
社区

drizzle-orm-patterns

Provides comprehensive Drizzle ORM patterns for schema definition, CRUD operations, relations, queries, transactions, and migrations. Proactively use for any Drizzle ORM development including defining database schemas, writing type-safe queries, implementing relations, managing transactions, and setting up migrations with Drizzle Kit. Supports PostgreSQL, MySQL, SQLite, MSSQL, and CockroachDB.

1小时安装量
3
GitHub Stars
372
最近更新
9月10日
giuseppe-trisciuoglio
社区

tailwind-css-patterns

Provides comprehensive Tailwind CSS utility-first styling patterns including responsive design, layout utilities, flexbox, grid, spacing, typography, colors, and modern CSS best practices. Use when styling React/Vue/Svelte components, building responsive layouts, implementing design systems, or optimizing CSS workflow.

1小时安装量
1
GitHub Stars
372
最近更新
9月10日
giuseppe-trisciuoglio
社区

dynamodb-toolbox-patterns

Provides TypeScript patterns for DynamoDB-Toolbox v2 including schema/table/entity modeling, .build() command workflow, query/scan access patterns, batch and transaction operations, and single-table design with computed keys. Use when implementing type-safe DynamoDB access layers with DynamoDB-Toolbox v2 in TypeScript services or serverless applications.

1小时安装量
1
GitHub Stars
371
最近更新
9月10日
giuseppe-trisciuoglio
社区

spring-boot-dependency-injection

Provides dependency injection patterns for Spring Boot projects, including constructor-first design, optional collaborator handling, bean selection, and wiring validation. Use when creating services and configurations, replacing field injection, or troubleshooting ambiguous or fragile Spring wiring.

1小时安装量
1
GitHub Stars
371
最近更新
9月10日