Koa Response Time Middleware

2.1.0 verified Thu Apr 23 auth: no javascript maintenance

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.

Common errors

error TypeError: (0 , koa_response_time_1.default) is not a function ↓

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'.

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.

error X-Response-Time header not present in response. ↓

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.

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.

error X-Response-Time header shows unexpectedly low or partial duration (e.g., '2ms' for a complex request). ↓

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.

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.

Warnings

gotcha 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. ↓

fix Ensure `app.use(responseTime(...))` is the first middleware applied in your Koa application.

gotcha 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. ↓

fix Always use `const responseTime = require('koa-response-time');` for consistent and reliable imports in Node.js environments.

gotcha 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. ↓

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.

Install

npm install koa-response-time

yarn add koa-response-time

pnpm add koa-response-time

Imports

responseTime
wrong
```
import responseTime from 'koa-response-time';
```
correct
```
const responseTime = require('koa-response-time');
```
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.
responseTime
wrong
```
import { responseTime } from 'koa-response-time';
```
correct
```
const responseTime = require('koa-response-time');
```
As a CommonJS module, it exports a single function. Attempting a named ESM import will result in a runtime error or `undefined`.

Quickstart

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.

const Koa = require('koa');
const responseTime = require('koa-response-time');

const app = new Koa();

// Use the responseTime middleware at the very top to measure all subsequent middleware.
// Set hrtime to true for nanosecond precision in the X-Response-Time header.
app.use(responseTime(/* { hrtime: true } */));

// Example middleware - simulates some asynchronous work
app.use(async (ctx, next) => {
  await new Promise(resolve => setTimeout(resolve, 50)); // Simulate async operation
  await next();
});

app.use(async ctx => {
  ctx.body = 'Hello Koa!';
});

const port = 3000;
app.listen(port, () => {
  console.log(`Koa server running on http://localhost:${port}`);
  console.log('Access http://localhost:3000 and check the X-Response-Time header.');
});