Helmet

Common errors

• ERR_REQUIRE_ESM: require() of ES Module .../node_modules/helmet/index.js from ... not supported.

  cause Attempting to import Helmet using CommonJS `require()` in an environment or project configured for ES Modules, or when Helmet itself is published as an ESM-only package.
  fix Change your import statement from `const helmet = require('helmet');` to `import helmet from 'helmet';`. Ensure your `package.json` specifies `"type": "module"` if it's a pure ESM project, or use a bundler that handles ESM correctly.

• Refused to load the script 'https://cdn.example.com/script.js' because it violates the following Content Security Policy directive: "script-src 'self'".

  cause Your Content Security Policy (CSP) is blocking a script from loading because its source is not explicitly allowed in the `script-src` directive. The default Helmet CSP is strict.
  fix Modify your `contentSecurityPolicy` directives in Helmet to include the allowed domain for scripts, e.g., `scriptSrc: ["'self'", 'https://cdn.example.com']`. For inline scripts, consider using `nonce` attributes or hashes.

• Helmet is not a function

  cause This error typically occurs if Helmet is imported incorrectly. It is a default export in its ESM form, or the CommonJS `require` result is not directly callable as a function.
  fix For ESM, ensure you use `import helmet from 'helmet';`. For CommonJS in older projects, use `const helmet = require('helmet');` and then `app.use(helmet());`.

Warnings

• breaking Helmet versions 6 and above are primarily ESM (ECMAScript Modules) by default. Projects using CommonJS (`require`) may encounter `ERR_REQUIRE_ESM` or other import issues, especially in modern Node.js environments.
  Fix: Migrate your project to use ESM `import` statements and configure `package.json` with `"type": "module"` if necessary. If a CJS-only project, ensure appropriate loaders or bundler configurations are in place to handle ESM dependencies.
• breaking Node.js versions below 18 are no longer supported since Helmet v8. Attempting to use Helmet v8.x with older Node.js versions will result in runtime errors.
  Fix: Upgrade your Node.js environment to version 18 or higher.
• breaking Several headers have been removed or disabled by default in recent major versions (e.g., `X-Powered-By` in v4, `X-XSS-Protection` and `Expect-CT` in v6/v7). Refer to the changelog for specific version changes.
  Fix: Review your application's security requirements and explicitly enable any previously relied-upon headers if still needed, or use separate, dedicated packages for removed functionalities (e.g., `expect-ct` package for `Expect-CT`). Note that `X-XSS-Protection` is often disabled for security reasons.
• gotcha Content Security Policy (CSP) is powerful but complex. Misconfigurations can block legitimate resources (scripts, styles, images) and break your application's functionality, especially with inline content or external CDNs.
  Fix: Thoroughly test your CSP in a development environment. Start with `reportOnly: true` to log violations without enforcing them. Gradually refine directives, explicitly allowing necessary sources and considering `nonce` attributes or hashes for inline scripts/styles instead of `unsafe-inline` where possible.
• gotcha The order of middleware matters in Express/Connect applications. Helmet should generally be applied early in your middleware chain to ensure all routes and subsequent middlewares receive the security headers.
  Fix: Place `app.use(helmet());` at the beginning of your middleware stack, before defining routes or other middleware that might send responses.

Install

• npm install helmet npm
• yarn add helmet yarn
• pnpm add helmet pnpm

Imports

• helmet
  wrong:

  const helmet = require('helmet');

  correct:

  import helmet from 'helmet';

  Helmet v6+ is primarily designed for ESM. While `require` might work in some CJS contexts, the recommended and type-safe approach for Node.js >=18 is ESM `import`.
• HelmetOptions

  import type { HelmetOptions } from 'helmet';

  Import types for configuration options, especially when using TypeScript, to leverage autocompletion and type checking.
• SpecificHeaderMiddleware
  wrong:

  import { x-content-type-options } from 'helmet';

  correct:

  import { xContentTypeOptions } from 'helmet';

  Individual header middlewares can be imported for specific use cases or to override global Helmet settings. Use camelCase for named imports.

Quickstart

This quickstart demonstrates how to initialize Helmet with default security headers in an Express application and provides an example of custom Content Security Policy (CSP) configuration.

import express from 'express';
import helmet from 'helmet';

const app = express();
const PORT = process.env.PORT || 3000;

// Apply Helmet with default security headers
app.use(helmet());

// Example: Customize Content Security Policy (CSP)
// This CSP allows scripts only from 'self' (your domain) and 'cdn.example.com'
// and disallows inline scripts unless explicitly whitelisted with a nonce.
app.use(
  helmet({
    contentSecurityPolicy: {
      directives: {
        defaultSrc: ["'self'"],
        scriptSrc: ["'self'", 'cdn.example.com'],
        styleSrc: ["'self'", "'unsafe-inline'"], // 'unsafe-inline' often needed for CSS frameworks
        imgSrc: ["'self'", 'data:'],
        connectSrc: ["'self'"],
        fontSrc: ["'self'", 'https:', 'data:'],
        objectSrc: ["'none'"],
        upgradeInsecureRequests: true,
      },
    },
  }),
);

// Route to demonstrate the application
app.get('/', (req, res) => {
  res.send(`
    <!DOCTYPE html>
    <html lang="en">
    <head>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <title>Secure App</title>
    </head>
    <body>
        <h1>Hello, secure world with Helmet!</h1>
        <script src="/test-script.js"></nscript>
    </body>
    </html>
  `);
});

// Simple static file for script-src testing
app.get('/test-script.js', (req, res) => {
  res.set('Content-Type', 'application/javascript');
  res.send('console.log("Script loaded securely!");');
});

app.listen(PORT, () => {
  console.log(`Server running on http://localhost:${PORT}`);
  console.log('Open your browser to see security headers in action.');
});