Frameguard: X-Frame-Options Middleware

Common errors

• TypeError: frameguard is not a function

  cause Attempting to call `require('frameguard')()` directly without resolving the middleware function, or incorrect ESM default import.
  fix For CommonJS, use `const frameguard = require('frameguard'); app.use(frameguard());`. For ESM, use `import frameguard from 'frameguard'; app.use(frameguard());`.

• Refused to display 'http://example.com/page' in a frame because it set 'X-Frame-Options' to 'DENY'.

  cause This is not an error from the middleware but a browser security message indicating `DENY` is working as intended, potentially blocking a legitimate use case.
  fix If you need to allow framing from the same origin, change the action to `sameorigin`: `app.use(frameguard({ action: 'sameorigin' }));`. If framing from other origins is required, consider using `Content-Security-Policy: frame-ancestors` instead.

• Header 'X-Frame-Options' not found in response headers.

  cause The `frameguard` middleware was not correctly applied to the Express app or was overridden by another middleware.
  fix Ensure `app.use(frameguard(...))` is called before any routes that require the header. Check for other security middleware that might be removing or conflicting with the `X-Frame-Options` header.

Warnings

• gotcha The `X-Frame-Options` header is largely superseded by the more modern and flexible `Content-Security-Policy: frame-ancestors` directive. While `frameguard` is useful for older browsers, for comprehensive security, `frame-ancestors` should be preferred or used in conjunction.
  Fix: Consider implementing a Content Security Policy with the `frame-ancestors` directive for modern browser protection. Example: `app.use(helmet.contentSecurityPolicy({ directives: { frameAncestors: ["'self'", 'https://trusted.com'] } }));`
• breaking The `ALLOW-FROM` directive for `X-Frame-Options` is not supported by this middleware. Attempting to use it will result in an invalid header or no header being set, compromising expected security.
  Fix: If `ALLOW-FROM` functionality is required, you must manually set the `X-Frame-Options` header or use a `Content-Security-Policy` with `frame-ancestors` for more granular control over framing sources.
• breaking When migrating from Helmet v4 to v5, `frameguard` is no longer included by default as a Helmet middleware. You must explicitly import and use `frameguard` as a standalone middleware.
  Fix: Ensure `frameguard` is installed (`npm install frameguard`) and then explicitly import and apply it: `import frameguard from 'frameguard'; app.use(frameguard());`
• gotcha The default action for `frameguard()` when no `action` option is provided is `sameorigin`. This means pages will be frameable by content from the same origin, which might not be the most secure default for all applications.
  Fix: If your application should never be framed, explicitly set `action: 'deny'` (e.g., `app.use(frameguard({ action: 'deny' }));`) for maximum protection against clickjacking.

Install

• npm install frameguard npm
• yarn add frameguard yarn
• pnpm add frameguard pnpm

Imports

• frameguard
  wrong:

  const frameguard = require('frameguard').default;

  correct:

  import frameguard from 'frameguard';

  While v4 primarily shows CommonJS examples in README, for TypeScript or modern ESM projects, default import is typical. For CJS, use `const frameguard = require('frameguard');`
• frameguard
  wrong:

  import frameguard from 'frameguard';

  correct:

  const frameguard = require('frameguard');

  For CommonJS environments (typical for Node.js < v12 or projects not configured for ESM), use `require`. Directly importing in ESM will fail if the package is not dual-module.
• FrameguardOptions
  wrong:

  import { FrameguardOptions } from 'frameguard';

  correct:

  import type { FrameguardOptions } from 'frameguard';

  TypeScript type imports use `import type` to ensure they are stripped from the JavaScript output, preventing runtime errors if the type is not also an exported value.

Quickstart

Demonstrates applying `frameguard` middleware to an Express.js application with different `X-Frame-Options` actions: `deny` and `sameorigin`, and the default behavior.

import express from 'express';
import frameguard from 'frameguard';

const app = express();
const port = 3000;

// Option 1: Prevent all framing (most secure default)
app.use('/deny', frameguard({ action: 'deny' }));

// Option 2: Allow framing only from the same origin
app.use('/sameorigin', frameguard({ action: 'sameorigin' }));

// Option 3: Default to sameorigin (if no action specified)
app.use('/default', frameguard());

app.get('/deny', (req, res) => {
  res.send('This page cannot be framed.');
});

app.get('/sameorigin', (req, res) => {
  res.send('This page can only be framed by same origin.');
});

app.get('/default', (req, res) => {
  res.send('This page defaults to same origin framing.');
});

app.listen(port, () => {
  console.log(`Server listening at http://localhost:${port}`);
  console.log('Try visiting http://localhost:3000/deny in a frame from another origin.');
});