As a junior developer, one of the most challenging aspects of building a Node.js backend isn’t writing the code itself — it’s organizing it in a way that scales. Today, we’ll explore a production-ready Node.js project structure that you can use as a template for your applications.

The Problem with Unstructured Code
Before we dive in, imagine trying to find a specific book in a library where books are randomly placed on shelves. Frustrating, right? The same applies to code. Without a proper structure, your Node.js application can quickly become a maze of spaghetti code that’s difficult to maintain and scale.

A Better Way: The Modern Node.js Project Structure
Let’s break down a professional-grade Node.js project structure that many successful companies use:

? BACKEND/
├─? src/
│ └── ? @types # TypeScript type definitions
│ └──? config # Configuration files
│ └── ? controllers # Request handlers
│ └── ? entity # Database models/entities
│ └── ? helper # Helper/utility functions
│ └── ? middlewares # Express middlewares
│ └── ? routes # API route definitions
│ └── ? services # Business logic
│ └── ? types # Additional type definitions
│ └── ? utils # Utility functions
└── ? app.ts # Application entry point
└── ? .eslintrc.js # ESLint configuration
└── ? .prettierrc # Prettier configuration
└── ? Dockerfile # Docker configuration
└── ? package.json # Project dependencies
└── ? tsconfig.json # TypeScript configuration
└── ? .dockerignore # Docker ignore rules
└── ? .env # Environment variables
└── ? docker-compose.yml # Docker Compose configuration

Understanding Each Component
1. @types and types Directories

`// @types/express/index.d.ts
declare namespace Express {
 export interface Request {
 user?: {
 id: string;
 role: string;
 };
 }
}`

These folders contain TypeScript type definitions. The @types folder typically contains declarations for external modules, while types holds your application-specific types.

2. Config Directory

// config/database.ts
export const dbConfig = {
 host: process.env.DB_HOST,
 port: process.env.DB_PORT,
 username: process.env.DB_USER,
 // … other configuration
};

This directory houses all configuration files, making it easy to manage different environments (development, staging, production).

3. Controllers

// controllers/userController.ts
export class UserController {
  async getUser(req: Request, res: Response) {
    try {
      const user = await userService.findById(req.params.id);
      res.json(user);
    } catch (error) {
      res.status(500).json({ error: error.message });
    }
  }
}

Controllers handle HTTP requests and responses, acting as a bridge between your routes and services.

4. Entity

typescript// entity/User.ts
@Entity()
export class User {
  @PrimaryGeneratedColumn()
  id: number;

  @Column()
  username: string;

  @Column()
  email: string;
}

The entity directory contains your database models, typically using an ORM like TypeORM or Sequelize.

5. Services

services/userService.ts
export class UserService {
  async createUser(userData: CreateUserDto) {
    const user = new User();
    Object.assign(user, userData);
    return await this.userRepository.save(user);
  }
}

Services contain your business logic, keeping it separate from your controllers.

6. Middlewares

`// @types/express/index.d.ts
declare namespace Express {
 export interface Request {
 user?: {
 id: string;
 role: string;
 };
 }
}`

Middlewares handle cross-cutting concerns like authentication, logging, and error handling.

Best Practices and Tips

1. Single Responsibility: Each directory should have a clear, single purpose. Don’t mix business logic with route definitions.

2. Dependency Injection: Use dependency injection to make your code more testable and maintainable.

// config/database.ts
export const dbConfig = {
 host: process.env.DB_HOST,
 port: process.env.DB_PORT,
 username: process.env.DB_USER,
 // … other configuration
};

3. Environment Configuration: Use .env files for environment-specific variables and never commit them to version control.

4. Docker Integration: The presence of Dockerfile and docker-compose.yml indicates containerization support, making deployment consistent across environments.

Common Pitfalls to Avoid
Circular Dependencies: Be careful not to create circular dependencies between your modules.
Massive Files: If a file grows too large, it’s probably doing too much. Split it into smaller, focused modules.
Inconsistent Error Handling: Establish a consistent error-handling strategy across your application.

Conclusion

A well-structured Node.js application is crucial for long-term maintainability and scalability. This structure provides a solid foundation that you can build upon as your application grows. Remember, the goal isn’t just to make it work — it’s to make it maintainable, scalable, and enjoyable to work with.

The next time you start a new Node.js project, consider using this structure as a template. It will save you countless hours of refactoring and make your codebase more professional from day one.

Pro tip: Create a template repository with this structure so you can quickly bootstrap new projects with the same organization.

The above is the detailed content of Node.js Backend Building a Scalable App: A Practical Guide to Project Structure. For more information, please follow other related articles on the PHP Chinese website!