Setting Up Express & Middleware

Middleware functions are the backbone of Express applications. They have access to the request object, response object, and the next middleware function in the application’s request-response cycle. This guide covers best practices for organizing, implementing, and using middleware in Express applications.

Middleware Fundamentals

Middleware functions can perform a variety of tasks:

• Execute code during the request-response cycle
• Modify request or response objects
• End the request-response cycle
• Call the next middleware in the stack

Middleware Execution Flow

const express = require('express');
const app = express();

// Middleware 1
app.use((req, res, next) => {
  console.log('Middleware 1 executed');
  next(); // Pass control to the next middleware
});

// Middleware 2
app.use((req, res, next) => {
  console.log('Middleware 2 executed');
  next();
});

// Route handler
app.get('/', (req, res) => {
  res.send('Hello World');
});

app.listen(3000);

Tip

The order of middleware registration is crucial. Middleware functions are executed in the order they are added.

Organizing Middleware

Project Structure

We organize middleware in a dedicated /middlewares folder to keep the codebase clean and maintainable:

• Directorysrc/

  • Directorymiddlewares/

    • authMiddleware.js
    • loggerMiddleware.js
    • errorMiddleware.js
    • validationMiddleware.js
    • corsMiddleware.js
    • notFoundMiddleware.js
  • Directoryroutes/

    • …
  • Directorycontrollers/

    • …
  • app.js
  • server.js

Note

Use camelCase for middleware file names to maintain consistency with JavaScript naming conventions and make imports more intuitive.

Middleware Registration

All middleware should be registered in app.js with consistent camelCase naming:

// app.js
const express = require('express');
const cors = require('cors');
const helmet = require('helmet');
const logger = require('./utils/logger');

const corsMiddleware = require('./middlewares/corsMiddleware');
const loggerMiddleware = require('./middlewares/loggerMiddleware');
const errorMiddleware = require('./middlewares/errorMiddleware');
const authMiddleware = require('./middlewares/authMiddleware');
const notFoundMiddleware = require('./middlewares/notFoundMiddleware');

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

const app = express();

// Third-party middleware
app.use(express.json());
app.use(express.urlencoded({ extended: true }));
app.use(corsMiddleware);
app.use(helmet()); // Directly applying helmet with default settings

// Logging middleware - choose one approach
// Option 1: Use morgan for HTTP request logging
// app.use(morgan('dev'));

// Option 2: Use custom logger middleware for more detailed logging
app.use(loggerMiddleware);

// Routes
app.use('/api/auth', require('./routes/auth.routes'));
app.use('/api/products', require('./routes/products.routes'));
app.use('/api/admin', require('./routes/admin.routes'));

// Not found middleware
app.use(notFoundMiddleware);

// Error middleware (always last)
app.use(errorMiddleware);

app.listen(PORT, () => {
  logger.info(`Server running on port ${PORT}`);
});

module.exports = app;

Tip

Choose either Morgan or a custom logger middleware based on your needs, but typically not both. Morgan is simpler and sufficient for most applications, while a custom logger gives you more control over what gets logged and how.

Common Middleware

Essential Third-Party Middleware

cors

// middlewares/corsMiddleware.js
const cors = require('cors');

const corsOptions = {
  origin: function (origin, callback) {
    // Allow requests with no origin (like mobile apps, curl)
    const allowedOrigins = ['http://localhost:3000', 'https://yourdomain.com'];

    if (!origin || allowedOrigins.includes(origin)) {
      callback(null, true);
    } else {
      callback(new Error('Not allowed by CORS'));
    }
  },
  credentials: true,
  optionsSuccessStatus: 200,
  methods: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'],
  allowedHeaders: ['Content-Type', 'Authorization']
};

const corsMiddleware = cors(corsOptions);

module.exports = corsMiddleware;

What it does:

CORS (Cross-Origin Resource Sharing) middleware allows your Express API to handle requests from different origins (domains). It works by adding appropriate HTTP headers to the server’s responses, which tell browsers whether they should allow web applications running at different origins to access your API.

Key features:

• Controls which domains can access your API
• Configures allowed HTTP methods
• Specifies allowed headers
• Handles preflight requests
• Enables credentials for cross-origin requests (cookies, authentication)

morgan

// middlewares/morganMiddleware.js
const morgan = require('morgan');
const logger = require('../utils/logger'); // Custom logger (e.g., winston)

// Create a custom token for request ID
morgan.token('id', function getId(req) {
  return req.id;
});

// Define different formats for development and production
const developmentFormat = ':method :url :status :response-time ms - :res[content-length] - :id';
const productionFormat = ':id :method :url :status :response-time ms';

// Create a write stream for morgan
const stream = {
  write: (message) => logger.info(message.trim())
};

const morganMiddleware = process.env.NODE_ENV === 'production'
  ? morgan(productionFormat, { stream })
  : morgan(developmentFormat, { stream });

module.exports = morganMiddleware;

What it does:

Morgan is an HTTP request logger middleware for Express that generates logs for every incoming request. It provides visibility into your API’s traffic and helps with debugging and monitoring.

Key features:

• Logs HTTP request details (method, URL, status code, response time)
• Supports customizable logging formats
• Can be integrated with other logging systems
• Helps track request performance
• Provides different preset formats (‘dev’, ‘combined’, ‘common’, etc.)

helmet

What it does:

Helmet helps secure Express apps by setting various HTTP security headers. These headers help protect your application from well-known web vulnerabilities like Cross-Site Scripting (XSS), clickjacking, and other security threats.

Key headers set by Helmet:

• Content-Security-Policy: Controls which resources the browser is allowed to load
• X-XSS-Protection: Enables browser’s built-in XSS filters
• X-Frame-Options: Prevents clickjacking by controlling frame embedding
• Strict-Transport-Security: Forces HTTPS connections
• X-Content-Type-Options: Prevents MIME-type sniffing
• Referrer-Policy: Controls how much referrer information is sent
• X-DNS-Prefetch-Control: Controls DNS prefetching

Custom Middleware Implementation

For specific middleware patterns, refer to their dedicated guides:

• Authentication Middleware: See Authentication & Security guide
• Error Handling & Logging Middlewares: See Error Handling & Logging guide

Not Found

// middlewares/notFoundMiddleware.js
const { StatusCodes } = require('http-status-codes');

/**
 * Not Found middleware
 *
 * This middleware handles requests to routes that don't exist.
 * Should be placed after all route definitions and before the error middleware.
 */
const notFoundMiddleware = (req, res) => {
  res.status(StatusCodes.NOT_FOUND).json({
    statusCode: StatusCodes.NOT_FOUND,
    message: 'Resource not found',
    path: req.originalUrl,
    timestamp: new Date().toISOString()
  });
};

module.exports = notFoundMiddleware;

Request Validation

// middlewares/validationMiddleware.js
const { StatusCodes } = require('http-status-codes');
const { validationResult } = require('express-validator');

const validateRequest = (req, res, next) => {
  const errors = validationResult(req);
  if (!errors.isEmpty()) {
    return res.status(StatusCodes.BAD_REQUEST).json({
      statusCode: StatusCodes.BAD_REQUEST,
      message: 'Validation failed',
      errors: errors.array().map(error => ({
        field: error.param,
        message: error.msg
      })),
      path: req.originalUrl,
      timestamp: new Date().toISOString()
    });
  }
  next();
};

module.exports = validateRequest;

Usage example with route:

// routes/users.routes.js
const express = require('express');
const { body } = require('express-validator');
const { validateRequest } = require('../middlewares/validationMiddleware');
const userController = require('../controllers/user.controller');

const router = express.Router();

router.post(
  '/register',
  [
    body('email').isEmail().withMessage('Please provide a valid email'),
    body('password').isLength({ min: 8 }).withMessage('Password must be at least 8 characters'),
    body('name').notEmpty().withMessage('Name is required')
  ],
  validateRequest,
  userController.register
);

module.exports = router;

Route-Specific Middleware

Sometimes middleware should only apply to specific routes:

// routes/admin.routes.js
const express = require('express');
const router = express.Router();
const { authMiddleware } = require('../middlewares/authMiddleware');
const { authorize } = require('../middlewares/rbac.middleware');
const adminController = require('../controllers/admin.controller');

// Apply middleware to all routes in this router
router.use(authMiddleware);
router.use(authorize('admin'));

// Admin routes
router.get('/users', adminController.getAllUsers);
router.delete('/users/:id', adminController.deleteUser);

module.exports = router;

// In app.js
app.use('/api/admin', require('./routes/admin.routes'));

Error Handling Middleware

Error handling middleware should always be registered last:

// app.js
const express = require('express');
const app = express();
const { errorMiddleware } = require('./middlewares/errorMiddleware');

// Regular middleware and routes...

// Error handling middleware (must be last)
app.use(errorMiddleware);

Best Practices & Common Pitfalls

Best Practices

1. Keep middleware focused

   • Each middleware should have a single responsibility
   • Create separate files for different middleware functions

2. Order matters

   • Place middleware in the correct order based on dependencies
   • Error-handling middleware should always be last

3. Use next() properly

   • Always call next() to pass control
   • Call next(err) to skip to error handlers

4. Modularize your middleware

   • Export individual middleware functions
   • Group related middleware in the same file

5. Handle middleware errors

   • Use try/catch blocks in async middleware
   • Or use express-async-errors package

Common Pitfalls

❌ Forgetting to call next()

• Requests will hang if next() isn’t called in middleware that doesn’t end the response

❌ Using middleware after sending a response

• Once res.send()/res.json()/res.end() is called, subsequent middleware won’t execute

❌ Incorrect middleware order

• Body-parsing middleware must come before routes that need parsed body data
• Authentication middleware should come before protected routes

❌ Not handling async errors

• Unhandled promise rejections can crash your application
• Always use try/catch or a promise-catching utility

Caution

Be careful with middleware that modifies the request or response objects. Such modifications affect all downstream middleware and route handlers.

Conclusion

Middleware is a powerful feature of Express that allows you to insert processing logic into the request-response cycle. By organizing middleware in a dedicated folder and following best practices, you can create a clean, maintainable, and secure Express application.

When implementing middleware, remember:

1. Keep middleware functions focused on a single responsibility
2. Use the correct order of middleware registration
3. Handle errors appropriately
4. Modularize your middleware code
5. Use built-in and third-party middleware wisely

Further Reading

• Express.js Middleware Documentation
• Writing Middleware for Express.js
• Error Handling in Express.js
• Popular Express.js Middleware