{"id":17756,"library":"koa-requestid","title":"Koa Request ID Middleware","description":"koa-requestid is a lightweight Koa middleware designed to automatically generate and attach a unique request ID to incoming HTTP requests. By default, it uses UUIDv4 for generation and exposes the ID via the `Request-Id` response header, also storing it in `ctx.state.id` for easy access within downstream middleware or route handlers. The current stable version is 2.3.0, with minor updates released periodically based on maintenance needs and dependency updates, as seen in the recent changelogs. Key differentiators include its simplicity, minimal configuration overhead, and the ability to accept custom request IDs from specified request headers or query parameters, which is particularly useful for debugging or tracing across services. Since version 2.0.2, it ships with comprehensive TypeScript definitions, enhancing developer experience for TypeScript-based Koa applications. It is specifically built for Koa applications, leveraging Koa's middleware pattern and context object.","status":"active","version":"2.3.0","language":"javascript","source_language":"en","source_url":"https://github.com/uphold/koa-requestid","tags":["javascript","koa","request","request-id","requestId","typescript"],"install":[{"cmd":"npm install koa-requestid","lang":"bash","label":"npm"},{"cmd":"yarn add koa-requestid","lang":"bash","label":"yarn"},{"cmd":"pnpm add koa-requestid","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This package is a Koa middleware and requires a Koa application to function.","package":"koa","optional":false}],"imports":[{"note":"The primary middleware function is exported as a default export.","wrong":"import { requestId } from 'koa-requestid';","symbol":"requestId","correct":"import requestId from 'koa-requestid';"},{"note":"CommonJS `require` syntax is fully supported and demonstrated in the official documentation.","symbol":"requestId (CommonJS)","correct":"const requestId = require('koa-requestid');"},{"note":"To correctly type `ctx.state.id` in TypeScript, you need to augment Koa's `DefaultState` interface. This is typically done in a global `d.ts` file or directly in a TypeScript file before using the middleware.","symbol":"DefaultState (Koa Context Augmentation)","correct":"declare module 'koa' {\n  interface DefaultState {\n    id: string;\n  }\n}"}],"quickstart":{"code":"import Koa from 'koa';\nimport requestId from 'koa-requestid';\n\n// Augment Koa's Context type to include 'id' in state\ndeclare module 'koa' {\n  interface DefaultState {\n    id: string;\n  }\n}\n\nconst app = new Koa();\n\n// Apply the middleware with custom options\napp.use(requestId({\n  expose: 'X-Request-ID', // Custom header for the response\n  header: 'X-Client-Trace-Id', // Custom header to read from request\n  query: 'traceId' // Custom query parameter to read from request\n}));\n\n// Define a Koa route that uses the request ID\napp.use(async (ctx) => {\n  const reqId = ctx.state.id; // Access the generated or provided request ID\n  console.log(`[${reqId}] Incoming request for ${ctx.path}`);\n  ctx.body = `Hello! Your unique request ID is: ${reqId}`;\n});\n\nconst port = 3000;\napp.listen(port, () => {\n  console.log(`Server running on http://localhost:${port}`);\n  console.log('Test with:');\n  console.log('  curl -v http://localhost:3000');\n  console.log('  curl -v -H \"X-Client-Trace-Id: my-app-123\" http://localhost:3000');\n  console.log('  curl -v http://localhost:3000?traceId=external-abc');\n});","lang":"typescript","description":"This quickstart demonstrates how to integrate `koa-requestid` into a TypeScript Koa application, configure custom headers/query parameters, and access the generated or provided request ID from `ctx.state.id`."},"warnings":[{"fix":"Ensure your Koa application is using Koa 2.x or later. Migrate any generator-based middleware to `async/await` functions. Alternatively, if upgrading Koa is not feasible, use `koa-requestid` versions prior to 2.0.0 (e.g., `^1.0.0`).","message":"Version 2.0.0 introduced a significant breaking change by updating to `koa@2.0.1`. This means the middleware now expects Koa 2.x style `async/await` middleware functions, diverging from Koa 1.x's generator-based middleware. Applications still using Koa 1.x will need to upgrade Koa or remain on an older version of `koa-requestid`.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Upgrade your Node.js environment to version 20 or newer. If forced to use an older Node.js version, consider using an older version of `koa-requestid` if compatible or evaluate alternative request ID middleware for Koa.","message":"The package's `engines.node` field specifies a minimum Node.js version of `20`. Running `koa-requestid` on older Node.js versions may lead to unexpected behavior or failures due to modern JavaScript features or API usage.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"If `koa-requestid` is configured to read custom IDs from client input (e.g., `header` or `query` options are set), add custom middleware *before* `koa-requestid` to validate or sanitize these inputs according to your application's security requirements.","message":"When `koa-requestid` accepts a custom request ID via a header or query parameter, the input value is NOT sanitized. Malicious or malformed input could potentially be exposed in logs or other system components. Developers must implement their own sanitization or validation if accepting untrusted input for request IDs.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Upgrade to `koa-requestid@2.0.2` or newer to leverage official TypeScript definitions. If using older versions, you may need to install `@types/koa-requestid` if available, or declare the module manually.","message":"TypeScript definitions were added in version 2.0.2. Prior versions (e.g., 2.0.0, 2.0.1) do not provide official type definitions, which can lead to type errors or require manual `any` assertions in TypeScript projects.","severity":"gotcha","affected_versions":"<2.0.2"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Ensure your application is built with Koa 2.x or newer. If you are using Express or another framework, `koa-requestid` is not compatible; you'll need a request ID middleware specific to that framework.","cause":"This error typically occurs when attempting to use `koa-requestid` with an application framework that is not Koa (e.g., Express) or with an outdated Koa 1.x application that expects generator-based middleware.","error":"TypeError: app.use is not a function"},{"fix":"To resolve this, you need to augment Koa's `DefaultState` interface in your TypeScript project. Add a declaration like `declare module 'koa' { interface DefaultState { id: string; } }` in a global `.d.ts` file or at the top of a relevant `.ts` file.","cause":"This is a TypeScript error indicating that the Koa `Context`'s `state` object does not have a defined `id` property, which `koa-requestid` adds at runtime.","error":"Property 'id' does not exist on type 'DefaultState'"},{"fix":"First, ensure the package is installed: `npm install koa-requestid` or `yarn add koa-requestid`. Verify the import path `from 'koa-requestid'`. If using an older version of `koa-requestid` (<2.0.2) in TypeScript, consider upgrading or installing `@types/koa-requestid` if available.","cause":"This error can occur if the package is not installed, there's a typo in the import path, or TypeScript cannot locate the type definitions (e.g., for versions prior to 2.0.2 or if `@types/koa-requestid` is missing when needed).","error":"Cannot find module 'koa-requestid' or its corresponding type declarations."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}