What is the recommended file structure for versioned controllers in a NestJS project?

Q: What is the recommended file structure for versioned controllers in a NestJS project?

src/ users/ v1/ users-v1.controller.ts // @Controller({ path: 'users', version: '1' }) users-v1.service.ts // v1 business logic v2/ users-v2.controller.ts // @Controller({ path: 'users', version: '2' }) users-v2.service.ts // v2 business logic dto/ create-user.dto.ts // shared across versions update-user.dto.ts pagination-query.dto.ts users.module.ts // users.module.ts — registers both controller versions @Module({ controllers: [UsersV1Controller, UsersV2Controller], providers: [UsersV1Service, UsersV2Service, UsersRepository], }) export class UsersModule {} v1/ and v2/ subdirectories keep version-specific code isolated and independently testable. Shared DTOs go in a common dto/ folder — versioning only applies to the request/response layer. For large teams, separate service classes per version prevent one version's changes from breaking another. For small APIs, a single service with version-branching logic is acceptable to avoid code duplication. The module registers all controller versions — clients route to the right one via the versioning strategy.

Difficulty: 5/10

file organization, API versioning, module structure

Organize versioned controllers into subdirectories (v1/, v2/) within each feature module folder. The feature module imports both controller classes. Shared DTOs live in a dto/ subdirectory outside the version folders. For small APIs, version-specific logic can live in service methods instead of separate service classes.

Versioned controller folder layout

Versioned project structure guidelines:

1
v1/ and v2/ subdirectories keep version-specific code isolated and independently testable.
2
Shared DTOs go in a common dto/ folder — versioning only applies to the request/response layer.
3

What is the recommended file structure for versioned controllers in a NestJS project?

Difficulty: 5/10

file organization, API versioning, module structure

Organize versioned controllers into subdirectories (v1/, v2/) within each feature module folder. The feature module imports both controller classes. Shared DTOs live in a dto/ subdirectory outside the version folders. For small APIs, version-specific logic can live in service methods instead of separate service classes.

Versioned controller folder layout

Versioned project structure guidelines:

1
v1/ and v2/ subdirectories keep version-specific code isolated and independently testable.
2
Shared DTOs go in a common dto/ folder — versioning only applies to the request/response layer.
3

What is the recommended file structure for versioned controllers in a NestJS project?

What is the recommended file structure for versioned controllers in a NestJS project?

Scenario Questions

Follow-up Questions