Passing Variables Between Middleware in Express.js: The Correct Way Using res.locals

Challenges in Variable Passing Between Middleware

During Express.js development, developers often need to pass data between different middleware functions. A common mistake is directly attaching variables to the request object, such as req.somevariable = variable1;, and then attempting to access req.somevariable in subsequent middleware. This approach leads to undefined variable errors because Express.js does not guarantee state consistency of the request object across different middleware.

Proper Usage of res.locals

The Express.js official documentation explicitly recommends using the res.locals object to store request-level local variables. This object is specifically designed for passing data between middleware and views within the same request/response cycle. Unlike directly modifying the request object, res.locals provides a reliable state preservation mechanism.

In the first middleware, variables should be set as follows:

app.use(function(req, res, next) {
    res.locals.somevariable = variable1;
    next();
});

In subsequent middleware, the variable can be accessed in the same manner:

app.use(function(req, res, next) {
    var myVariable = res.locals.somevariable;
    // Logic using the variable
    next();
});

Detailed Code Example

Let's demonstrate the correct implementation through a complete example. Suppose we need to pass user information between authentication middleware and authorization middleware:

// Authentication middleware
app.use(function(req, res, next) {
    // Simulate user authentication logic
    var user = {
        id: 12345,
        name: "John Doe",
        role: "admin"
    };
    
    // Store user information using res.locals
    res.locals.user = user;
    res.locals.authenticated = true;
    
    next();
});

// Authorization middleware
app.use(function(req, res, next) {
    // Retrieve user information from res.locals
    if (res.locals.authenticated) {
        console.log("User ID: " + res.locals.user.id);
        console.log("User Role: " + res.locals.user.role);
        
        // Perform authorization checks based on role
        if (res.locals.user.role === "admin") {
            // Admin permission logic
            console.log("Has administrator privileges");
        }
    }
    
    next();
});

Advantages of res.locals

Using res.locals offers several important advantages. First, it provides a clear scope where variables are only valid within the current request cycle, preventing data pollution between different requests. Second, it integrates seamlessly with Express.js's view rendering system, allowing variables stored in res.locals to be directly used in templates. Most importantly, this is the officially recommended and supported approach by Express.js, ensuring code stability and maintainability.

Common Mistakes and Solutions

Many developers attempt to use the req.somevariable approach, often due to migration from other frameworks or programming patterns. In Express.js, the request object is primarily used for receiving client data, while the response object manages data and state sent from the server to the client. res.locals, as part of the response object, is specifically designed for managing temporary state within the request cycle.

Another common mistake involves improper variable passing in asynchronous operations. Due to JavaScript's asynchronous nature, it's essential to ensure all necessary variables are set before calling next(). For example:

// Incorrect approach
app.use(function(req, res, next) {
    someAsyncFunction(function(result) {
        res.locals.data = result;
        // Forgetting to call next() or calling it at an inappropriate position
    });
    next(); // next() called before asynchronous callback completes
});

// Correct approach
app.use(function(req, res, next) {
    someAsyncFunction(function(result) {
        res.locals.data = result;
        next(); // next() called after asynchronous operation completes
    });
});

Best Practices Summary

In Express.js middleware development, following these best practices can prevent many common issues: always use res.locals for variable passing between middleware; ensure variable setup is complete before calling next() in asynchronous operations; avoid directly modifying the request object unless specifically required; maintain single responsibility for each middleware, with each handling specific functionality. By adhering to these principles, developers can build more robust and maintainable Express.js applications.