DEV Community: Yasin Besni

How to Structure a Node.js + Express Project Without Overcomplicating It

Yasin Besni — Mon, 05 Oct 2026 06:11:07 +0000

A Node.js + Express project can become difficult to navigate surprisingly quickly.

At the beginning, keeping everything in a single file may feel convenient. But as routes, controllers, database logic, middleware, and validation are added, that simple structure becomes harder to maintain.

The solution is not to create dozens of folders from day one.

A better approach is to start with a small structure where every file has a clear responsibility, and expand it only when the project actually needs it.

In this article, we'll build a simple and practical Express project structure without adding unnecessary complexity.

1. Start With a Small and Clear Structure

For a small Express API, a structure like this is usually enough:

src/
├── controllers/
├── routes/
├── middleware/
├── models/
├── app.js
└── server.js

Each part has a specific job:

routes/ defines which endpoints exist.
controllers/ contains the logic that runs when those endpoints are called.
middleware/ contains reusable request-processing logic.
models/ contains the application's data models.
app.js configures the Express application.
server.js starts the HTTP server.

The important idea is not the folder names themselves.

The goal is to avoid putting routing, database operations, validation, and application startup logic into one large file.

For example, instead of writing everything inside server.js, keep the server startup small:

import app from "./app.js";

const PORT = process.env.PORT || 3000;

app.listen(PORT, () => {
  console.log(`Server is running on port ${PORT}`);
});

Then configure Express separately in app.js:

import express from "express";

const app = express();

app.use(express.json());

export default app;

At this point, the project is still simple.

But there is already a useful separation:

server.js is responsible for starting the server.
app.js is responsible for configuring the application.

This small distinction becomes much more valuable as the project grows.

2. Separate Routes From Controllers

As an API grows, route files can easily become crowded with application logic.

Consider a simple /movies endpoint.

You could write everything directly inside the route:

router.get("/", (req, res) => {
  const movies = [
    { id: 1, title: "Movie A" },
    { id: 2, title: "Movie B" },
  ];

  res.json(movies);
});

This works, but the route is now responsible for both defining the endpoint and handling its logic.

A cleaner approach is to move that logic into a controller.

Create a controller:

// controllers/movieController.js

export const getMovies = (req, res) => {
  const movies = [
    { id: 1, title: "Movie A" },
    { id: 2, title: "Movie B" },
  ];

  res.json(movies);
};

Then keep the route focused on routing:

// routes/movieRoutes.js

import express from "express";
import { getMovies } from "../controllers/movieController.js";

const router = express.Router();

router.get("/", getMovies);

export default router;

Finally, register the route in app.js:

import express from "express";
import movieRoutes from "./routes/movieRoutes.js";

const app = express();

app.use(express.json());
app.use("/movies", movieRoutes);

export default app;

Now each file has a clearer responsibility:

the route decides which controller should handle the request,
the controller handles the request and prepares the response,
app.js connects the application's main pieces.

This does not make the application more complicated. It simply prevents unrelated responsibilities from accumulating in the same file.

For a very small project, this separation may feel unnecessary at first. But once an endpoint starts working with validation, database queries, or error handling, having routes and controllers separated becomes much easier to maintain.

3. Use Middleware for Reusable Request Logic

Middleware is useful when the same logic needs to run for multiple requests.

A simple example is request logging.

Instead of adding a console.log() inside every route, create a middleware function:

// middleware/logger.js

export const logger = (req, res, next) => {
  console.log(`${req.method} ${req.url}`);
  next();
};

Then register it in app.js:

import express from "express";
import movieRoutes from "./routes/movieRoutes.js";
import { logger } from "./middleware/logger.js";

const app = express();

app.use(express.json());
app.use(logger);

app.use("/movies", movieRoutes);

export default app;

Now every request passes through the same logging logic.

Middleware is especially useful for concerns such as:

authentication,
authorization,
validation,
request logging,
error handling.

The main advantage is reuse.

If the same request-related logic appears in multiple routes, that is usually a good sign that it belongs in middleware.

At the same time, not every small piece of logic needs its own middleware file. Creating middleware only when it actually solves duplication keeps the project easier to understand.

4. Keep Data Models Separate

If your application uses a database, keeping model definitions in a separate folder helps prevent database structure from becoming mixed with routing or controller logic.

For example, with Mongoose you might create a simple movie model:

// models/Movie.js

import mongoose from "mongoose";

const movieSchema = new mongoose.Schema({
  title: {
    type: String,
    required: true,
  },
  year: {
    type: Number,
  },
});

const Movie =
  mongoose.models.Movie || mongoose.model("Movie", movieSchema);

export default Movie;

This file is responsible only for describing the structure of movie data and creating the model.

Then the controller can use that model:

// controllers/movieController.js

import Movie from "../models/Movie.js";

export const getMovies = async (req, res) => {
  const movies = await Movie.find();

  res.json(movies);
};

This keeps responsibilities separated:

models/ describes the application's data,
controllers/ works with that data,
routes/ connects URLs to controllers.

The fallback in this line:

mongoose.models.Movie || mongoose.model("Movie", movieSchema);

helps avoid redefining the same model in environments where the module may be loaded more than once.

You do not need a separate model layer for every project.

But once a database is involved, keeping schema definitions away from route files usually makes the code easier to read and maintain.

5. Keep Error Handling Centralized

Note: The examples in this article assume Express 5. In Express 5, rejected promises and errors thrown inside async route handlers are automatically forwarded to the error-handling middleware.

As the project grows, repeating try/catch blocks and response logic in every route or controller can make the code noisy.

A simple error-handling middleware gives the application one place to return unexpected errors.

// middleware/errorHandler.js

export const errorHandler = (err, req, res, next) => {
  console.error(err);

  if (res.headersSent) {
    return next(err);
  }

  res.status(err.status || 500).json({
    message: err.message || "Internal Server Error",
  });
};

import express from "express";
import movieRoutes from "./routes/movieRoutes.js";
import { logger } from "./middleware/logger.js";
import { errorHandler } from "./middleware/errorHandler.js";

const app = express();

app.use(express.json());
app.use(logger);

app.use("/movies", movieRoutes);

app.use(errorHandler);

export default app;

The order matters here.

Express processes middleware from top to bottom, so the error handler should normally be registered after the application routes.

For a small project, this is enough to establish a clear place for unexpected errors without introducing a complex error architecture.

6. What the Final Structure Looks Like

After these small separations, the project might look like this:

src/
├── controllers/
│   └── movieController.js
├── middleware/
│   ├── errorHandler.js
│   └── logger.js
├── models/
│   └── Movie.js
├── routes/
│   └── movieRoutes.js
├── app.js
└── server.js

This is still a small structure.

There are no extra layers just for the sake of architecture.

Each folder exists because it has a clear responsibility:

routes/ defines endpoints,
controllers/ handles requests,
models/ defines application data,
middleware/ contains reusable request-related logic,
app.js configures the application,
server.js starts the server.

7. Add Complexity Only When You Need It

A common mistake is assuming that a professional backend must start with many layers, folders, and abstractions.

It does not.

If the project becomes larger, you may eventually introduce things like service layers, validation schemas, configuration modules, or more advanced error handling.

But those additions should solve a real problem.

A good structure is not the one with the most folders.

It is the one that makes responsibilities easy to find and the application easy to change.

Start small, separate responsibilities when they become meaningful, and let the structure grow with the project.

Final Thoughts

A Node.js + Express project does not need a complicated architecture to be maintainable.

A practical starting point is enough:

keep server startup separate from application configuration,
keep routes focused on routing,
move request logic into controllers when it starts growing,
keep database models separate,
use middleware for reusable request logic,
centralize error handling.

The goal is not to predict every future requirement.

The goal is to make today's code clear without making tomorrow's changes unnecessarily difficult.

5 Common Mistakes Beginners Make When Building an Express API

Yasin Besni — Sun, 04 Oct 2026 18:25:46 +0000

Building your first Express API is usually straightforward.

You install Express, create a server, add a few routes, and suddenly you have a working backend.

The harder part comes later.

As the project grows, small decisions that seemed harmless at the beginning can make the code harder to understand, test, and maintain.

Here are five common mistakes beginners make when building Express APIs, along with practical ways to avoid them.

1. Putting Everything in `server.js`

A small Express application often starts like this:

import express from "express";

const app = express();

app.get("/users", (req, res) => {
  // fetch users
});

app.post("/users", (req, res) => {
  // create user
});

app.listen(3000);

There is nothing wrong with this when you are learning.

The problem begins when the same file starts containing:

routes
validation
database queries
authentication
error handling
business logic

At that point, server.js stops being an entry point and becomes the entire application.

A better direction is to gradually separate responsibilities.

For example:

src/
├── server.js
├── routes/
├── controllers/
├── middleware/
└── models/

You do not need a complex architecture on day one.

The goal is simply to keep unrelated responsibilities from becoming tightly coupled.

2. Ignoring Middleware Order

In Express, middleware runs in the order in which it is registered.

That sounds simple, but it is one of the easiest things to overlook.

Consider this example:

app.use(requestContext);
app.use(requestLogger);

The first middleware creates information that the second middleware can use.

For example:

import { randomUUID } from "node:crypto";

export function requestContext(req, res, next) {
  req.requestId = randomUUID();
  next();
}

Then the logger can use that value:

export function requestLogger(req, res, next) {
  console.log(`${req.method} ${req.originalUrl} [${req.requestId}]`);
  next();
}

If you reverse the order, requestLogger runs before requestId exists.

That means this:

app.use(requestLogger);
app.use(requestContext);

does not behave the same way.

Middleware order is part of your application logic.

Do not treat app.use() calls as interchangeable.

3. Repeating Validation Inside Every Route

Another common pattern is validating request data directly inside each route:

app.post("/api/messages", (req, res) => {
  if (!req.body.message) {
    return res.status(400).json({
      message: "Message is required",
    });
  }

  // continue...
});

This works.

But if several routes need similar checks, validation logic quickly becomes repetitive.

A simple middleware can make the responsibility clearer:

export function validateMessage(req, res, next) {
  const { message } = req.body;

  if (typeof message !== "string" || message.trim() === "") {
    return res.status(400).json({
      message: "The message field must be a non-empty string.",
    });
  }

  req.body.message = message.trim();

  next();
}

Now the route can focus on what it actually needs to do:

app.post("/api/messages", validateMessage, (req, res) => {
  res.status(201).json({
    message: req.body.message,
  });
});

This is one of the main benefits of middleware:

reusable request-processing logic without duplicating it across routes.

4. Handling Every Error Inside the Route

Beginners often write error responses directly inside every route:

if (!book) {
  return res.status(404).json({
    message: "Book not found",
  });
}

Again, this is not automatically wrong.

But when the application grows, you may repeat the same patterns dozens of times.

A centralized error flow gives you one place to control how API errors are returned.

A small custom error class can help:

export class AppError extends Error {
  constructor(statusCode, message) {
    super(message);

    this.statusCode = statusCode;
    this.isOperational = true;
  }
}

Then a route can forward the error:

if (!book) {
  return next(new AppError(404, "Book not found."));
}

And centralized middleware handles the response:

export function errorHandler(err, req, res, next) {
  if (res.headersSent) {
    return next(err);
  }

  const statusCode =
    Number.isInteger(err.statusCode) && err.statusCode >= 400
      ? err.statusCode
      : 500;

  const message =
    statusCode === 500 && !err.isOperational
      ? "Internal server error"
      : err.message;

  if (statusCode === 500) {
    console.error(err);
  }

  res.status(statusCode).json({
    status: "error",
    message,
  });
}

The route becomes easier to read, and the API gets a more consistent error format.

5. Sending Internal Error Details to the Client

This is a more serious mistake.

Imagine something unexpected happens:

throw new Error("Database connection failed at...");

Returning the entire internal error to the client can expose information the user does not need to see.

For unexpected server errors, a safer response is usually something generic:

{
  "status": "error",
  "message": "Internal server error"
}

You can still log the real error on the server:

if (statusCode === 500) {
  console.error(err);
}

This creates an important separation:

developers get the information needed for debugging
API clients receive a safe and predictable response

Expected application errors, such as validation failures or missing resources, can still return useful messages.

Unexpected internal failures should generally stay internal.

Keep the Architecture Proportional to the Project

There is another mistake worth avoiding: overengineering.

A beginner project does not need ten architectural layers just because large production systems use them.

Start simple.

Then separate responsibilities when the code gives you a reason to do so.

A useful progression might look like this:

single Express file
        ↓
routes + controllers
        ↓
middleware
        ↓
centralized error handling
        ↓
database models
        ↓
larger application structure

Each step should solve a real problem.

Architecture is useful when it makes the code easier to understand and change — not when it only adds more folders.

Companion Code

I created a public companion repository with runnable examples for the concepts discussed here:

https://github.com/besniapp-blip/nodejs-backend-development-book

The repository currently includes examples for:

Express basics
middleware flow
request validation
request logging
centralized error handling

I will continue adding practical backend examples over time.