Koa ETag Middleware

Common errors

• TypeError: etag is not a function

  cause This error typically occurs when attempting to import `koa-etag` using a named import syntax (e.g., `import { etag } from 'koa-etag'`) or destructuring with `require` (`const { etag } = require('koa-etag')`), despite the package providing a default export.
  fix For CommonJS, use `const etag = require('koa-etag');`. For ESM, use `import etag from 'koa-etag';` to correctly import the default middleware function.

• ETag headers are missing or not functioning correctly, despite `koa-etag` being installed.

  cause A common cause is `koa-conditional-get` not being installed or used, or `koa-compress` being placed after `koa-etag` in the middleware stack. `koa-etag` only *generates* the ETag; `koa-conditional-get` handles the client-side conditional requests, and `koa-compress` must run first to ensure the ETag is calculated on the final (compressed) body.
  fix Ensure both `koa-conditional-get` and `koa-etag` are applied, and crucially, `app.use(compress())` must be called before `app.use(conditional())` and `app.use(etag())`.

Warnings

• deprecated The `koa-etag` package is in maintenance mode and will be formally deprecated in its next major release. Users are strongly advised to migrate to the `@koa/etag` package for continued support, bug fixes, and future feature updates, as it is the direct successor and recommended alternative.
  Fix: Replace `npm install koa-etag` with `npm install @koa/etag` and update import paths accordingly. The API is largely identical.
• gotcha For correct ETag generation and response caching, the `koa-compress` middleware must be applied *before* `koa-conditional-get` and `koa-etag` in the middleware chain. Applying compression after ETag calculation will result in mismatched ETags for compressed content.
  Fix: Ensure `app.use(compress())` is called prior to `app.use(conditional())` and `app.use(etag())` in your Koa application setup.
• breaking Version 5.x of `koa-etag` dropped support for older Node.js versions. It now explicitly requires Node.js 18 or higher due to modern language features and tooling updates.
  Fix: Upgrade your Node.js runtime environment to version 18 or later to use `koa-etag` v5.x.
• gotcha Version 5.x was rewritten in TypeScript and bundled for both ESM and CJS. While `v5.0.2` improved CJS interop, incorrect import statements (e.g., named imports for default exports) can lead to errors.
  Fix: For CommonJS, use `const etag = require('koa-etag');`. For ESM, use `import etag from 'koa-etag';`. Avoid named imports like `import { etag } from 'koa-etag';`.

Install

• npm install koa-etag npm
• yarn add koa-etag yarn
• pnpm add koa-etag pnpm

Imports

• etag
  wrong:

  import { etag } from 'koa-etag';

  correct:

  import etag from 'koa-etag';

  Since v5, the package is ESM-first with CJS interop, exposing the middleware as a default export. Named imports are incorrect.
• etag (CommonJS)
  wrong:

  const { etag } = require('koa-etag');

  correct:

  const etag = require('koa-etag');

  For CommonJS environments, the middleware is the default export. Destructuring is incorrect.
• KoaEtagOptions (TypeScript type)

  import type { KoaEtagOptions } from 'koa-etag';

  Available since v5, used for configuring the middleware with TypeScript.

Quickstart

This example demonstrates how to set up `koa-etag` in a Koa application, showing its typical usage alongside `koa-conditional-get` and `koa-compress`.

const Koa = require('koa');
const etag = require('koa-etag');
const conditional = require('koa-conditional-get');
const compress = require('koa-compress');

const app = new Koa();

// compress must be used before conditional and etag for correct ETag calculation
app.use(compress());

// etag works together with conditional-get for full HTTP caching support
app.use(conditional());
app.use(etag());

app.use(function (ctx) {
  ctx.body = 'Hello World';
});

app.listen(3000);

console.log('Server listening on port 3000');