DEV Community

Cover image for Node.js Backend Building a Scalable App: A Practical Guide to Project Structure
Kafeel Ahmad (kaf shekh)
Kafeel Ahmad (kaf shekh)

Posted on

1

Node.js Backend Building a Scalable App: A Practical Guide to Project Structure

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;
 };
 }
}`
Enter fullscreen mode Exit fullscreen mode

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
};
Enter fullscreen mode Exit fullscreen mode

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 });
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

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;
}
Enter fullscreen mode Exit fullscreen mode

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);
  }
}
Enter fullscreen mode Exit fullscreen mode

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

6. Middlewares

// middlewares/auth.ts
export const authMiddleware = async (req: Request, res: Response, next: NextFunction) => {
  try {
    const token = req.headers.authorization?.split(' ')[1];
    if (!token) throw new Error('No token provided');
    // Verify token and set user
    next();
  } catch (error) {
    res.status(401).json({ error: 'Unauthorized' });
  }
};
Enter fullscreen mode Exit fullscreen mode

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.

// Better approach
class UserService {
  constructor(private userRepository: UserRepository) {}
}
Enter fullscreen mode Exit fullscreen mode

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.

Image of Timescale

🚀 pgai Vectorizer: SQLAlchemy and LiteLLM Make Vector Search Simple

We built pgai Vectorizer to simplify embedding management for AI applications—without needing a separate database or complex infrastructure. Since launch, developers have created over 3,000 vectorizers on Timescale Cloud, with many more self-hosted.

Read full post →

Top comments (0)

Sentry image

See why 4M developers consider Sentry, “not bad.”

Fixing code doesn’t have to be the worst part of your day. Learn how Sentry can help.

Learn more