Organize Your NestJS Project for Scalability

A scalable folder structure is crucial for maintaining and expanding a NestJS application efficiently. This guide provides a recommended structure and explains the purpose of each directory.

Here is an example of a well-organized folder structure for a NestJS project:

src
├── constants      # Define reusable constants used throughout the application
├── decorators     # Custom decorators for parameter and route handling
├── errors         # Custom error classes or error handling logic
├── filters        # Exception filters for handling errors globally or locally
├── guards         # Guards for implementing role-based or route-specific access control
├── interceptors   # Interceptors for modifying incoming requests or outgoing responses
├── interfaces     # TypeScript interfaces for type safety
├── middlewares    # Custom middleware logic
├── models         # Data models representing database entities or DTOs
├── modules        # Feature-based modules containing controllers, services, and providers
├── pipes          # Pipes for data transformation and validation
├── processors     # Background job processing or worker threads
├── transformers   # Data transformation logic (e.g., mapping database records to DTOs)
├── utils          # Utility functions or helpers
├── app.config.ts  # Configuration setup for the application
└── app.controller.spec.ts # Unit tests for the app controller

Directory Breakdown

• constants: Store constants like magic strings or configuration keys used across the app.
• decorators: Build custom decorators to enhance functionality in a DRY manner.
• errors: Centralize error handling by creating custom error classes to maintain consistency.
• filters: Use filters to define custom logic for exception handling.
• guards: Implement guards to manage access control, such as AuthGuard or RolesGuard.
• interceptors: Process requests or responses globally or locally, such as logging or response shaping.
• interfaces: Define reusable interfaces for strong typing and improved code readability.
• middlewares: Use middleware to handle request-level concerns like logging or parsing.
• models: Represent database entities or structure data transfer objects (DTOs).
• modules: Each module encapsulates related controllers, services, and other providers.
• pipes: Create custom pipes for validating or transforming incoming request data.
• processors: Handle background tasks like queues (e.g., with Bull or RabbitMQ).
• transformers: Ensure data is mapped correctly between layers.
• utils: Group helper functions, like date formatters or encryption utilities.

Why This Structure?

• Scalability: As the app grows, each module or layer remains isolated, making maintenance easier.
• Readability: Clear separation of concerns ensures every team member can navigate the codebase.
• Testability: Each layer or module is easier to test independently.

Organizing your project this way ensures your NestJS application is clean, scalable, and maintainable.