koa-helmet

library9.0.0jsnpmunverified

koa-helmet is a middleware collection for the Koa.js framework, providing essential HTTP security headers by wrapping the popular `helmet` library. It helps protect Koa applications from common web vulnerabilities by setting various headers like Content Security Policy (CSP), HSTS, X-Frame-Options, and more. The current stable version is 9.0.0, which notably introduces native ESM and CJS publishing without API changes. The package maintains an active release cadence, aligning with updates to both Koa (supporting v2 and v3) and Helmet (supporting versions 6, 7, and 8) via peer dependencies. A key differentiator is its minimal direct dependency footprint, relying solely on peer dependencies for `koa` and `helmet`, ensuring flexibility and control over core library versions in the consuming application. It ships with TypeScript typings, making it suitable for modern TypeScript-based Koa projects.

web-framework auth-security

npm install koa-helmet

github ↗package ↗

INSTALL

IMPORT

SIG · KOA-HELMET

koa-helmet

web-frameworkjavascriptv9.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

helmet

✓ import helmet from 'koa-helmet';

✗ const helmet = require('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

✓ import { contentSecurityPolicy } from 'koa-helmet';

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

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

Koa

✓ import Koa from 'koa';

✗ const Koa = require('koa');

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

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}`); });

Debug

Known issues

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

affects: >=7.0.1

breakingUpgraded 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).

affects: <6.0.0

breakingThe 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`.

affects: >=9.0.0

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

affects: >=2.x

gotchaIn 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"`.

affects: 8.0.0 - 8.0.2

Errors

Common errors & fixes

Error: Cannot find module 'koa-helmet'

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)

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'

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

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

Upgrade

Version history

9.0.0latest on npm

Audit

Dependencies

helmetrequiredProvides the underlying security middleware functions; required peer dependency.

koarequiredThe web framework this middleware is built for; required peer dependency.

Agent activity

12 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/venables/koa-helmet ↗

packagehttps://www.npmjs.com/package/koa-helmet ↗