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.

Quelltext ansehen

Verwendung

  1. Installationsbefehl kopieren und das Quellpaket vor der Installation in der eigenen Agentenumgebung prüfen.
  2. Benötigte Werkzeuge, Zugangsdaten und Hosts im Original prüfen.
  3. Eingabe und gewünschtes Ergebnis beschreiben und die Ausgabe mit den Quellen abgleichen.
npx skills add https://github.com/giuseppe-trisciuoglio/developer-kit --skill nestjs-best-practices

Vor dem Start

  • Die Installation umfasst weder Modellabo noch API-Kontingent oder Dateizugriffsrechte.
  • Sterne und Installationen zeigen Aktivität, keine unabhängige Qualitäts- oder Sicherheitsprüfung.
Originales Skill-Dokument

Aus dem Quell-Repository gerendert; Überschriften, Beispiele, Code, Tabellen, Links und Bilder bleiben erhalten.

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

Verwandte Aufgaben

aus demselben Repository

Weitere Skills

Alle Skills
giuseppe-trisciuoglio
Community

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.

Installationen / 1h
3
GitHub Stars
372
Aktualisiert
10. Sept.
giuseppe-trisciuoglio
Community

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.

Installationen / 1h
1
GitHub Stars
372
Aktualisiert
10. Sept.
giuseppe-trisciuoglio
Community

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.

Installationen / 1h
1
GitHub Stars
371
Aktualisiert
10. Sept.
giuseppe-trisciuoglio
Community

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.

Installationen / 1h
1
GitHub Stars
371
Aktualisiert
10. Sept.