Feature Policy Middleware

Common errors

• TypeError: featurePolicy is not a function

  cause Attempting to call the `feature-policy` module directly without passing configuration to its default exported function, or an incorrect import statement (e.g., named import for a default export).
  fix Ensure you are using `app.use(featurePolicy({...}));` in CommonJS or `import featurePolicy from 'feature-policy'; app.use(featurePolicy({...}));` in ESM, correctly invoking the module as a factory function with options.

• Refused to execute '<feature-name>' because it violates the document's feature policy.

  cause A browser feature (like 'fullscreen' or 'geolocation') is being blocked by a `Feature-Policy` directive that is too restrictive or misconfigured for the current context.
  fix Review the `features` configuration within your `featurePolicy` middleware. Ensure that necessary origins (e.e.g., `'self'`, `'none'`, or specific domain names) are correctly applied. Check the browser's developer console for more specific details about the blocked feature and the violated policy.

Warnings

• breaking The `Feature-Policy` HTTP header, which this module sets, has been officially deprecated by all major browsers. It is being superseded by the `Permissions-Policy` header.
  Fix: Migrate to using `Permissions-Policy` headers directly or a module designed for `Permissions-Policy` to ensure future browser compatibility and security for new projects. This module should only be used for maintaining legacy systems.
• gotcha This `feature-policy` module is currently in maintenance mode. No new features, updates to support new browser features, or general enhancements will be added, unless they are critical bug fixes.
  Fix: Evaluate the need for `feature-policy` in new projects carefully. For existing projects, plan for eventual migration to `Permissions-Policy` to avoid relying on a module with static support.
• gotcha Incorrectly configured `feature-policy` directives can unintentionally block legitimate browser features on your site (e.g., fullscreen mode, camera access), leading to a degraded user experience or broken functionality.
  Fix: Thoroughly test all policy configurations across different browsers and user flows. Start with strict policies and gradually relax them if necessary, meticulously observing browser console warnings/errors related to feature blocking.

Install

• npm install feature-policy npm
• yarn add feature-policy yarn
• pnpm add feature-policy pnpm

Imports

• featurePolicy
  wrong:

  import { featurePolicy } from 'feature-policy';

  correct:

  import featurePolicy from 'feature-policy';

  This module uses a default export for the middleware function. For TypeScript, use `import featurePolicy from 'feature-policy';` to correctly import the function and its types.
• featurePolicy
  wrong:

  const { featurePolicy } = require('feature-policy');

  correct:

  const featurePolicy = require('feature-policy');

  In CommonJS environments, the middleware function is the default export and is accessed directly from the `require` call.
• FeaturePolicyOptions

  import type { FeaturePolicyOptions } from 'feature-policy';

  Type import for configuring the middleware options, available since the package ships TypeScript types. Useful for strict type checking in TypeScript projects.

Quickstart

Demonstrates how to integrate and configure `feature-policy` middleware in an Express application to set browser feature permissions, applying a policy to all incoming requests.

const express = require('express');
const featurePolicy = require('feature-policy');
const app = express();

app.use(
  featurePolicy({
    features: {
      fullscreen: ["'self'"],
      vibrate: ["'none'"],
      payment: ["example.com"],
      syncXhr: ["'none'"]
    }
  })
);

app.get('/', (req, res) => {
  res.send('Hello World! Check your response headers for Feature-Policy.');
});

const PORT = process.env.PORT ?? 3000;
app.listen(PORT, () => {
  console.log(`Server listening on port ${PORT}`);
});