Koa Security Headers (Helmet Wrapper)

Common errors

• Error: Cannot find module 'koa-helmet'

  cause The `koa-helmet` package itself has not been installed, or there's a path resolution issue.
  fix Run `npm install koa-helmet` or `bun add koa-helmet`. If using CJS after v9, verify your import path for `require`.

• TypeError: Cannot read properties of undefined (reading 'use') at Object.<anonymous> (file.js:X:Y)

  cause This typically indicates that `app` (your Koa instance) is not correctly initialized or the `koa` peer dependency is missing/misconfigured.
  fix Ensure you have `koa` installed (`npm install koa`) and that your `Koa` instance is correctly created as `const app = new Koa();`.

• Error: Cannot find module 'helmet' or 'koa'

  cause koa-helmet relies on `helmet` and `koa` as peer dependencies, which must be installed separately.
  fix Install the peer dependencies: `npm install helmet koa` or `bun add helmet koa`.

• TypeError: helmet is not a function

  cause This usually happens when attempting to use a named export as a default export, or a CJS module attempting to import an ESM default incorrectly.
  fix If using ESM, ensure `import helmet from 'koa-helmet';` is used for the default export. If trying to use a specific middleware, use named imports like `import { contentSecurityPolicy } from 'koa-helmet';`.

Warnings

• breaking Node.js version requirement increased. koa-helmet v7.0.1 dropped support for Node.js versions below 14. v9.0.0 requires Node.js >= 18.0.0.
  Fix: Upgrade your Node.js environment to version 18.0.0 or higher.
• breaking Upgraded to Helmet v4.1.1 which introduced breaking changes in Helmet itself. This also involved dropping Node 8 support.
  Fix: Review Helmet v4.x documentation for necessary configuration adjustments. Ensure Node.js version is at least 10 (or later, as per other warnings).
• breaking The package now publishes both ESM and CJS versions (dual package). While no API changes, consumers using older Node.js versions or specific bundler configurations might need to verify their import/require statements.
  Fix: For new projects, prefer ESM `import` statements. Existing CJS `require` statements should largely continue to work but be mindful of explicit `"type": "module"` settings in your project's `package.json`.
• gotcha koa-helmet has `helmet` and `koa` as peer dependencies. These must be explicitly installed alongside `koa-helmet` for the package to function correctly.
  Fix: Ensure you run `npm install koa-helmet helmet koa` (or `bun add koa-helmet helmet koa`) to install all necessary packages.
• gotcha In versions 8.0.0 through 8.0.2, the package inadvertently included `"type": "module"` in its package.json, which could lead to unexpected ESM treatment in some Node.js environments when intending to use CJS.
  Fix: Upgrade to `koa-helmet@8.0.3` or later to resolve this issue, which explicitly removed the erroneous `"type": "module"`.

Install

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

Imports

• helmet
  wrong:

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

  correct:

  import helmet from 'koa-helmet';

  ESM default import for `helmet` to apply all default security middlewares. While `require` works for CJS, ESM is preferred in modern Node.js environments.
• contentSecurityPolicy
  wrong:

  const { contentSecurityPolicy } = require('koa-helmet');

  correct:

  import { contentSecurityPolicy } from 'koa-helmet';

  Named ESM import for specific Helmet middlewares when you want to apply them individually or with custom options.
• Koa
  wrong:

  const Koa = require('koa');

  correct:

  import Koa from 'koa';

  This package is for Koa applications. Ensure Koa itself is imported correctly, typically as a default ESM import in modern projects.

Quickstart

Demonstrates a basic Koa application integrating `koa-helmet` to apply all default security headers, then starts the server.

import Koa from "koa";
import helmet from "koa-helmet";

const app = new Koa();

// Apply all default security headers provided by Helmet
app.use(helmet());

app.use((ctx) => {
  ctx.body = "Hello World - Secured by Koa-Helmet!";
});

const PORT = process.env.PORT ?? 4000;
app.listen(PORT, () => {
  console.log(`Koa app listening on http://localhost:${PORT}`);
});