{"id":17139,"library":"koa-helmet","title":"Koa Security Headers (Helmet Wrapper)","description":"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.","status":"active","version":"9.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/venables/koa-helmet","tags":["javascript","csp","headers","helmet","hsts","koa","security","x-frame-options","typescript"],"install":[{"cmd":"npm install koa-helmet","lang":"bash","label":"npm"},{"cmd":"yarn add koa-helmet","lang":"bash","label":"yarn"},{"cmd":"pnpm add koa-helmet","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides the underlying security middleware functions; required peer dependency.","package":"helmet","optional":false},{"reason":"The web framework this middleware is built for; required peer dependency.","package":"koa","optional":false}],"imports":[{"note":"ESM default import for `helmet` to apply all default security middlewares. While `require` works for CJS, ESM is preferred in modern Node.js environments.","wrong":"const helmet = require('koa-helmet');","symbol":"helmet","correct":"import helmet from 'koa-helmet';"},{"note":"Named ESM import for specific Helmet middlewares when you want to apply them individually or with custom options.","wrong":"const { contentSecurityPolicy } = require('koa-helmet');","symbol":"contentSecurityPolicy","correct":"import { contentSecurityPolicy } from 'koa-helmet';"},{"note":"This package is for Koa applications. Ensure Koa itself is imported correctly, typically as a default ESM import in modern projects.","wrong":"const Koa = require('koa');","symbol":"Koa","correct":"import Koa from 'koa';"}],"quickstart":{"code":"import Koa from \"koa\";\nimport helmet from \"koa-helmet\";\n\nconst app = new Koa();\n\n// Apply all default security headers provided by Helmet\napp.use(helmet());\n\napp.use((ctx) => {\n  ctx.body = \"Hello World - Secured by Koa-Helmet!\";\n});\n\nconst PORT = process.env.PORT ?? 4000;\napp.listen(PORT, () => {\n  console.log(`Koa app listening on http://localhost:${PORT}`);\n});","lang":"typescript","description":"Demonstrates a basic Koa application integrating `koa-helmet` to apply all default security headers, then starts the server."},"warnings":[{"fix":"Upgrade your Node.js environment to version 18.0.0 or higher.","message":"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.","severity":"breaking","affected_versions":">=7.0.1"},{"fix":"Review Helmet v4.x documentation for necessary configuration adjustments. Ensure Node.js version is at least 10 (or later, as per other warnings).","message":"Upgraded to Helmet v4.1.1 which introduced breaking changes in Helmet itself. This also involved dropping Node 8 support.","severity":"breaking","affected_versions":"<6.0.0"},{"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`.","message":"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.","severity":"breaking","affected_versions":">=9.0.0"},{"fix":"Ensure you run `npm install koa-helmet helmet koa` (or `bun add koa-helmet helmet koa`) to install all necessary packages.","message":"koa-helmet has `helmet` and `koa` as peer dependencies. These must be explicitly installed alongside `koa-helmet` for the package to function correctly.","severity":"gotcha","affected_versions":">=2.x"},{"fix":"Upgrade to `koa-helmet@8.0.3` or later to resolve this issue, which explicitly removed the erroneous `\"type\": \"module\"`.","message":"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.","severity":"gotcha","affected_versions":"8.0.0 - 8.0.2"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Run `npm install koa-helmet` or `bun add koa-helmet`. If using CJS after v9, verify your import path for `require`.","cause":"The `koa-helmet` package itself has not been installed, or there's a path resolution issue.","error":"Error: Cannot find module 'koa-helmet'"},{"fix":"Ensure you have `koa` installed (`npm install koa`) and that your `Koa` instance is correctly created as `const app = new Koa();`.","cause":"This typically indicates that `app` (your Koa instance) is not correctly initialized or the `koa` peer dependency is missing/misconfigured.","error":"TypeError: Cannot read properties of undefined (reading 'use') at Object.<anonymous> (file.js:X:Y)"},{"fix":"Install the peer dependencies: `npm install helmet koa` or `bun add helmet koa`.","cause":"koa-helmet relies on `helmet` and `koa` as peer dependencies, which must be installed separately.","error":"Error: Cannot find module 'helmet' or 'koa'"},{"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';`.","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.","error":"TypeError: helmet is not a function"}],"ecosystem":"npm","meta_description":null}