NestJS Best Practices
Use the project's source, package manifest, lockfile, module format, HTTP adapter, and test runner as the primary context. Read only the references relevant to the task.
This skill targets NestJS 12. The npm latest tag for @nestjs/core was verified as 12.0.1 on 2026-08-29. Treat that patch number as a dated observation: re-check the registry and official documentation before recommending or performing an upgrade.
Version Gate
- Inspect
package.json and the lockfile for @nestjs/core, @nestjs/common, platform adapters, CLI, and companion packages.
- Preserve the installed major for ordinary feature and bug-fix work. Do not introduce v12-only APIs into a v10/v11 project.
- For a new project or an explicit upgrade, verify the current stable npm tag and official migration guide. Keep all
@nestjs/* packages on compatible majors.
- For v11 to v12 work, read NestJS 12 migration before editing dependencies or configuration.
- Preserve the project's CommonJS or ESM choice unless the user requests a module-format migration. Nest 12 packages are ESM, but supported CommonJS applications can consume them on compatible Node.js versions.
Working Method
- Inspect existing module boundaries and nearby patterns before generating code.
- Prefer framework primitives and the adapter already in use. Avoid Express-specific response handling in code that should remain adapter-independent.
- Keep controllers thin: translate transport input/output and delegate business rules to providers.
- Use explicit injection tokens for non-class dependencies. Export only providers that other modules actually consume.
- Choose singleton scope by default; request scope has a performance and dependency-graph cost.
- Validate untrusted input at the transport boundary. Use class-based or Standard Schema-based validation consistently with the project; do not layer both without a concrete reason.
- Keep secrets and environment-specific values outside source. Validate configuration during startup.
- Preserve stable error contracts. In Nest 12, prefer
errorCode for machine decisions and messages for humans.
- Test observable behavior through
@nestjs/testing; preserve the repository's Jest or Vitest choice.
- After edits, run the narrow relevant tests, type checking, linting, and build commands already defined by the repository.
NestJS 12 Decisions
- Runtime and CLI: a Nest 12 application needs Node.js 20.19+ or 22.12+ on the 22.x line. Current schematics/CLI generation has a higher runtime floor; see the migration reference rather than inferring from
@nestjs/core.engines alone.
- Validation: keep
ValidationPipe for decorator/class DTOs. Use the built-in StandardSchemaValidationPipe with @Body({ schema }), @Query({ schema }), or @Param(..., { schema }) when the project already uses Zod, Valibot, ArkType, or another Standard Schema library.
- Serialization: keep
ClassSerializerInterceptor for class-transformer models. Use StandardSchemaSerializerInterceptor with @SerializeOptions({ schema }) for schema-driven response shaping.
- Configuration:
@nestjs/config accepts Standard Schema through validationSchema; Zod is the current documentation's default example. Joi requires v18+ and nests library-specific settings under validationOptions.libraryOptions.
- CLI/build: use
nest upgrade --dry-run before an explicit migration. Rspack is the v12 monorepo default; webpack CLI flags are deprecated. Do not migrate an existing build stack merely to match new-project defaults.
- Routes: consider
routeConflictPolicy and routeResolutionStrategy: 'specificity' when route shadowing is a real risk; both are opt-in.
- GraphQL: GraphiQL is the default IDE. Use
graphql-ws; subscriptions-transport-ws is no longer supported by the latest GraphQL package.
- NATS: v12 uses NATS v3 and
@nats-io/transport-node; review custom serializers/deserializers.
- Observability:
@nestjs/observe is an optional official hosted integration, not a universal dependency. Read observability only when the task calls for it.
Reference Routing
Migration, CLI, and Architecture
Request Lifecycle and Framework Primitives
HTTP, Data, and Operations
Security and API Contracts
GraphQL, WebSockets, and Microservices
Advanced Recipes
