Agent-Skills.md

Agent Skills: NestJS API Standards & Common Patterns

Create standardized API response envelopes, paginated endpoints, and error interceptors in NestJS. Use when implementing response wrappers, pagination DTOs, or global error formats. (triggers: **/*.controller.ts, **/*.dto.ts, ApiResponse, Pagination, TransformInterceptor)

UncategorizedID: hoangnguyen0403/agent-skills-standard/nestjs-api-standards

Repository

hoangnguyen0403/agent-skills-standard
HoangNguyen0403License: Apache-2.0
362103

Install this agent skill to your local

pnpm dlx add-skill https://github.com/HoangNguyen0403/agent-skills-standard/tree/HEAD/skills/nestjs/nestjs-api-standards

Skill Files

Browse the full folder contents for nestjs-api-standards.

Download Skill

Loading file tree…

skills/nestjs/nestjs-api-standards/SKILL.md

Skill Metadata

Name
nestjs-api-standards
Description
"Create standardized API response envelopes, paginated endpoints, and error interceptors in NestJS. Use when implementing response wrappers, pagination DTOs, or global error formats. (triggers: **/*.controller.ts, **/*.dto.ts, ApiResponse, Pagination, TransformInterceptor)"

NestJS API Standards & Common Patterns

Priority: P1 (OPERATIONAL)

Standardized API response patterns and common NestJS conventions.

Workflow: Standardize an API Endpoint

  1. Create Response DTO — Define a dedicated DTO for every endpoint return type.
  2. Map entity to DTO — Use plainToInstance(UserResponseDto, user) in the service or controller.
  3. Apply TransformInterceptor — Bind globally to wrap all responses in { statusCode, data, meta }.
  4. Add nested validation — Decorate nested DTO properties with @ValidateNested() + @Type().
  5. Document with Swagger — Apply @ApiResponse({ status, type }) with exact types per endpoint.

Response Wrapper Example

See implementation examples

Entity-to-DTO Mapping Example

See implementation examples

Deep Validation (Critical)

  • [Rule] Nested Validation: When a DTO property is an object or array of objects, you MUST use @ValidateNested() along with @Type(() => TargetDto) from class-transformer to ensure deep validation.

Pagination Standards

  • DTOs: Use strict PageOptionsDto (page/take/order) and PageDto<T> (data/meta).
  • Swagger Logic: Generics require ApiExtraModels and schema path resolution.
  • Reference: See Pagination Wrapper Implementation for the complete ApiPaginatedResponse decorator code.

Custom Error Response

  • Standard Error Object: Define ApiErrorResponse with statusCode, message, error, timestamp, path. See Error Response Class.
  • Docs: Apply @ApiBadRequestResponse({ type: ApiErrorResponse }) globally or per controller.

Anti-Patterns

  • No raw entity returns: Always map to a Response DTO; raw entities leak internal fields.
  • No unvalidated nested DTOs: Use @ValidateNested() + @Type() for all nested object properties.
  • No generic 200 docs: Apply @ApiResponse({ status, type }) with exact types per endpoint.

References