{"id":17755,"library":"koa-response-time","title":"Koa Response Time Middleware","description":"koa-response-time is a minimal Koa middleware designed to automatically add an `X-Response-Time` header to HTTP responses. This header indicates the duration it took for the Koa application to process and respond to a request. Currently at version 2.1.0, which was last published over 7 years ago, the package is highly stable and in maintenance mode, with no anticipated new feature development. Its primary differentiator is its simplicity and direct integration into the Koa ecosystem, providing a standard and unobtrusive way to measure request-response cycles. It supports high-resolution timing via an optional `hrtime` configuration for more precise measurements. The package has no external runtime dependencies, ensuring a lean footprint.","status":"maintenance","version":"2.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/koajs/response-time","tags":["javascript","koa","middleware","response","duration"],"install":[{"cmd":"npm install koa-response-time","lang":"bash","label":"npm"},{"cmd":"yarn add koa-response-time","lang":"bash","label":"yarn"},{"cmd":"pnpm add koa-response-time","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This package is a CommonJS module. While Node.js's ESM loader might attempt to import it as a default, the `require` syntax is the intended and most reliable way to consume it.","wrong":"import responseTime from 'koa-response-time';","symbol":"responseTime","correct":"const responseTime = require('koa-response-time');"},{"note":"As a CommonJS module, it exports a single function. Attempting a named ESM import will result in a runtime error or `undefined`.","wrong":"import { responseTime } from 'koa-response-time';","symbol":"responseTime","correct":"const responseTime = require('koa-response-time');"}],"quickstart":{"code":"const Koa = require('koa');\nconst responseTime = require('koa-response-time');\n\nconst app = new Koa();\n\n// Use the responseTime middleware at the very top to measure all subsequent middleware.\n// Set hrtime to true for nanosecond precision in the X-Response-Time header.\napp.use(responseTime(/* { hrtime: true } */));\n\n// Example middleware - simulates some asynchronous work\napp.use(async (ctx, next) => {\n  await new Promise(resolve => setTimeout(resolve, 50)); // Simulate async operation\n  await next();\n});\n\napp.use(async ctx => {\n  ctx.body = 'Hello Koa!';\n});\n\nconst port = 3000;\napp.listen(port, () => {\n  console.log(`Koa server running on http://localhost:${port}`);\n  console.log('Access http://localhost:3000 and check the X-Response-Time header.');\n});","lang":"javascript","description":"This quickstart demonstrates how to set up a basic Koa application with the `koa-response-time` middleware. It shows how to apply the middleware at the top of the stack and includes an optional configuration for high-resolution timing. The example includes a simulated asynchronous operation to demonstrate the middleware capturing the full request duration before sending a response."},"warnings":[{"fix":"Ensure `app.use(responseTime(...))` is the first middleware applied in your Koa application.","message":"Middleware must be mounted at the very top of the Koa middleware stack. If `koa-response-time` is placed after other significant middleware, it will only measure the execution time of the middleware *after* itself, leading to inaccurate (lower) response times in the `X-Response-Time` header.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always use `const responseTime = require('koa-response-time');` for consistent and reliable imports in Node.js environments.","message":"This package is a CommonJS module and does not natively export ESM. Attempting to use `import` syntax without proper transpilation or Node.js module resolution configuration might lead to import errors or unexpected behavior, such as `undefined` imports.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Understand that the project is stable but not actively developed. For new features or rapidly evolving requirements, consider alternatives if this poses a limitation.","message":"The package's last release (v2.1.0) was over 7 years ago. While stable and functional, this indicates it is in maintenance mode, and users should not expect active feature development, new releases, or updates for compatibility with very recent Node.js features unless critical fixes are required by the Koa community.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Change the import to `const responseTime = require('koa-response-time');` if in a CommonJS context, or use `import responseTime = require('koa-response-time');` in TypeScript for CJS interoperability.","cause":"Attempting to import the CommonJS module using `import responseTime from 'koa-response-time';` in a TypeScript or ESM-configured project, where the transpiler/runtime expects a default export but receives the CJS `module.exports` object directly. The function is the entire export, not a property named 'default'.","error":"TypeError: (0 , koa_response_time_1.default) is not a function"},{"fix":"Verify that `app.use(responseTime());` is present and correctly placed at the beginning of your middleware chain in your Koa application. Check server logs for any early errors preventing middleware execution.","cause":"The `koa-response-time` middleware was not correctly applied to the Koa application, or an error occurred before the middleware could add the header.","error":"X-Response-Time header not present in response."},{"fix":"Move `app.use(responseTime());` to be the *first* middleware registered with your Koa application, before any other `app.use()` calls, to ensure it wraps the entire request processing pipeline.","cause":"The `koa-response-time` middleware is placed too late in the Koa middleware stack, only measuring the time taken by subsequent middleware and not the entire request processing lifecycle.","error":"X-Response-Time header shows unexpectedly low or partial duration (e.g., '2ms' for a complex request)."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}