{"id":17222,"library":"express-correlation-id","title":"Express Correlation ID Middleware","description":"express-correlation-id is an Express middleware that provides a unique correlation identifier for each incoming HTTP request, ensuring consistency across all asynchronous operations within the request's lifecycle. It automatically generates a UUID if no `x-correlation-id` header is present (or a configurable custom header). The library is currently stable at version 3.0.1, with recent updates indicating active maintenance. Version 3.x introduced a breaking change by requiring Node.js 16 or newer, with Node.js 20 being recommended. Its key differentiators include a simple API to access the ID via both the `req` object (`req.correlationId()`) and a static module method (`correlator.getId()`), as well as the ability to programmatically set the ID. It differentiates itself by its focus on robust async context handling for the correlation ID.","status":"active","version":"3.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/toboid/express-correlation-id","tags":["javascript","express","logging","correlation","debug"],"install":[{"cmd":"npm install express-correlation-id","lang":"bash","label":"npm"},{"cmd":"yarn add express-correlation-id","lang":"bash","label":"yarn"},{"cmd":"pnpm add express-correlation-id","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The `correlator` module exports a default function which is the Express middleware. It also exposes static methods like `getId` and `setId` directly on the imported `correlator` object. Use `import correlator from 'express-correlation-id'` for modern ES Modules.","wrong":"const correlator = require('express-correlation-id'); // CommonJS in ESM project\nimport { correlator } from 'express-correlation-id'; // If correlator is default export","symbol":"correlator","correct":"import correlator from 'express-correlation-id';"},{"note":"The `getId` function is a static method of the default exported `correlator` object, not a separate named export. It returns `undefined` if called outside an active request context.","wrong":"import { getId } from 'express-correlation-id'; // getId is a method on the default export, not a named export.","symbol":"correlator.getId","correct":"import correlator from 'express-correlation-id';\nconst id = correlator.getId();"},{"note":"The `setId` function is a static method of the default exported `correlator` object. It must be called within an active request context; otherwise, it will throw an error.","wrong":"import { setId } from 'express-correlation-id'; // setId is a method on the default export, not a named export.","symbol":"correlator.setId","correct":"import correlator from 'express-correlation-id';\ncorrelator.setId('my-custom-id');"}],"quickstart":{"code":"import express from 'express';\nimport correlator from 'express-correlation-id';\n\nconst app = express();\n\n// The correlator middleware should generally be placed after other middleware\n// that might need to run before a correlation ID is established.\napp.use(express.json()); // Example: other middleware\napp.use(correlator());\n\napp.get('/', (req, res) => {\n  // Access the correlation ID via the request object\n  console.log('ID for this request (from req.correlationId()):', req.correlationId());\n  // Access the correlation ID via the module's static method\n  console.log('ID for this request (from correlator.getId()):', correlator.getId());\n  res.send(`Correlation ID: ${req.correlationId()}`);\n});\n\napp.get('/set-id', (req, res) => {\n  const newId = `custom-${Math.random().toString(36).substring(2, 9)}`;\n  req.setCorrelationId(newId); // Set via req object\n  // correlator.setId(newId); // Alternatively, set via static method\n  console.log('New ID set for this request:', req.correlationId());\n  res.send(`New Correlation ID set: ${req.correlationId()}`);\n});\n\nconst PORT = process.env.PORT || 3000;\napp.listen(PORT, () => {\n  console.log(`Server listening on port ${PORT}`);\n});","lang":"javascript","description":"This quickstart demonstrates how to integrate the `express-correlation-id` middleware into an Express application, access the generated or provided correlation ID, and programmatically set a new ID for a request."},"warnings":[{"fix":"Upgrade your Node.js environment to version 16 or higher (20 recommended). Alternatively, for older Node.js versions, use `express-correlation-id@2.x`.","message":"Version 3.0.0 of `express-correlation-id` raised the minimum required Node.js version to 16. Previous versions (2.x) supported Node.js >=12.17.0. Running v3.x on older Node.js environments will lead to compatibility issues.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Ensure `app.use(correlator())` is called after other relevant middleware, such as `express.json()` or authentication middleware, to guarantee the correlation scope correctly encompasses subsequent handlers.","message":"The `correlator()` middleware should be placed strategically after any other middleware that needs to run before the correlation ID is established. The `README` specifically notes it should be placed *after* other middleware.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always ensure that calls to `correlator.getId()` and `correlator.setId(id)` are made within a request's processing lifecycle, typically within Express middleware or route handlers. For setting the ID, consider using `req.setCorrelationId(id)` as it's scoped to the request object.","message":"Calling `correlator.getId()` or `correlator.setId(id)` outside the context of an active HTTP request will result in `undefined` for `getId()` or an error for `setId()`.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Import the default export and access `getId` as a method: `import correlator from 'express-correlation-id'; const id = correlator.getId();`","cause":"Attempting to destructure `getId` from the `express-correlation-id` module (e.g., `import { getId } from 'express-correlation-id'`) when `getId` is a method on the default exported middleware function object.","error":"TypeError: correlator.getId is not a function"},{"fix":"Ensure `correlator.setId(id)` is only called from within an Express middleware or route handler. If available, use `req.setCorrelationId(id)` as it implicitly operates within the request context.","cause":"The `correlator.setId()` method was invoked in a global context or outside an active HTTP request's asynchronous scope.","error":"Error: setId can only be called in the context of a request"},{"fix":"Use ES Module syntax: `import correlator from 'express-correlation-id';`. Ensure your project's `package.json` has `\"type\": \"module\"` or uses `.mjs` file extensions for ESM.","cause":"Attempting to use `require('express-correlation-id')` in an ES Module-only Node.js project or when a project explicitly configures itself for ESM.","error":"ERR_REQUIRE_ESM: require() of ES Module ... not supported"}],"ecosystem":"npm","meta_description":null}