@jackdbd/eleventy-plugin-permissions-policy

Eleventy plugin that writes Permissions-Policy and Feature-Policy headers to a _headers file when Eleventy builds your site.

• Installation
• About
• Docs
• Usage
• Configuration
  • Plugin options
  • Permissions-Policy directive
• Troubleshooting
• Dependencies
• License

Installation

npm install @jackdbd/eleventy-plugin-permissions-policy

⚠️ Peer Dependencies

This package defines 2 peer dependencies.

Peer	Version range
@11ty/eleventy	>=2.0.0 or 3.0.0-alpha.4
debug	>=4.0.0

About

Hosting providers like Cloudflare Pages and Netlify allow to define custom response headers in a plain text file called _headers. This file must be placed in the publish directory of your site (e.g. usually _site for a Eleventy site).

This plugin allows you to define a Permissions-Policy or a Feature-Policy header in your Eleventy configuration file, and then it automatically writes those headers into your _headers file when you build your site.

Docs

Docs generated by TypeDoc

📖 API Docs

This project uses API Extractor and api-documenter markdown to generate a bunch of markdown files and a .d.ts rollup file containing all type definitions consolidated into a single file. I don't find this .d.ts rollup file particularly useful. On the other hand, the markdown files that api-documenter generates are quite handy when reviewing the public API of this project.

See Generating API docs if you want to know more.

Usage

In your Eleventy config file:

import { permissionsPolicyPlugin } from '@jackdbd/eleventy-plugin-permissions-policy'

export default function (eleventyConfig) {
  // some eleventy configuration...

  eleventyConfig.addPlugin(permissionsPolicyPlugin, {
    directives: [
      { feature: 'autoplay', allowlist: ['*'] },
      { feature: 'geolocation', allowlist: ['self'] },
      { feature: 'camera', allowlist: ['self', 'https://trusted-site.example'] },
      { feature: 'fullscreen', allowlist: [] }
    ],
    includeFeaturePolicy: true
  })

  // some more eleventy configuration...
}

Configuration

Read these resources to understand how to configure the Permissions-Policy and the Feature-Policy HTTP response headers.

• A new security header: Feature Policy
• Goodbye Feature Policy and hello Permissions Policy!
• Permissions Policy Explainer
• Policy Controlled Features
• Controlling browser features with Permissions Policy

Plugin options

Key	Default	Description
directives	[]	Permissions-Policy directives.
excludePatterns	[]	Files that match these patterns will not be served with the Permissions-Policy header (nor with the Feature-Policy header, if generated).
includeFeaturePolicy	true	Whether to generate also a Feature-Policy header.
includePatterns	`[
"/",
"/*/"
]`	Files that match these patterns will be served with the Permissions-Policy header (and also with the Feature-Policy header, if generated).
jsonRecap	false

Permissions-Policy directive

Key	Default	Description
allowlist	undefined	A set of origins and/or special values (*, none, self, src).
feature	undefined	A policy-controlled feature is an API or behaviour which can be enabled or disabled in a document by referring to it in a permissions policy.

Troubleshooting

This plugin uses the debug library for logging. You can control what's logged using the DEBUG environment variable.

For example, if you set your environment variables in a .envrc file, you can do:

# print all logging statements
export DEBUG=11ty-plugin:*

Dependencies

Package	Version
zod	^3.22.4
zod-validation-error	^3.0.0

License

© 2022 - 2024 Giacomo Debidda // MIT License