@jackdbd/eleventy-plugin-permissions-policy
Version:
Eleventy plugin that writes Permissions-Policy and Feature-Policy headers to a `_headers` file when Eleventy builds your site.
128 lines (93 loc) • 5.96 kB
Markdown
# @jackdbd/eleventy-plugin-permissions-policy
[](https://badge.fury.io/js/@jackdbd%2Feleventy-plugin-permissions-policy)
[](https://packagephobia.com/result?p=@jackdbd/eleventy-plugin-permissions-policy)
[](https://app.codecov.io/gh/jackdbd/undici?flags%5B0%5D=eleventy-plugin-permissions-policy)
[](https://socket.dev/npm/package/@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](#installation)
- [About](#about)
- [Docs](#docs)
- [Usage](#usage)
- [Configuration](#configuration)
- [Plugin options](#plugin-options)
- [Permissions-Policy directive](#permissions-policy-directive)
- [Troubleshooting](#troubleshooting)
- [Dependencies](#dependencies)
- [License](#license)
## Installation
```sh
npm install @jackdbd/eleventy-plugin-permissions-policy
```
> :warning: **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](https://developers.cloudflare.com/pages/configuration/headers/) and [Netlify](https://docs.netlify.com/routing/headers/) 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](https://w3c.github.io/webappsec-permissions-policy/) or a [Feature-Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/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](https://jackdbd.github.io/undici/eleventy-plugin-permissions-policy/)
> :open_book: **API Docs**
>
> This project uses [API Extractor](https://api-extractor.com/) and [api-documenter markdown](https://api-extractor.com/pages/commands/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](https://api-extractor.com/pages/setup/generating_docs/) if you want to know more*.
## Usage
In your Eleventy config file:
```js
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](https://scotthelme.co.uk/a-new-security-header-feature-policy/)
- [Goodbye Feature Policy and hello Permissions Policy!](https://scotthelme.co.uk/goodbye-feature-policy-and-hello-permissions-policy/)
- [Permissions Policy Explainer](https://github.com/w3c/webappsec-permissions-policy/blob/main/permissions-policy-explainer.md)
- [Policy Controlled Features](https://github.com/w3c/webappsec-permissions-policy/blob/main/features.md)
- [Controlling browser features with Permissions Policy](https://developer.chrome.com/en/docs/privacy-sandbox/permissions-policy/)
### Plugin options
| Key | Default | Description |
|---|---|---|
| `directives` | `[]` | Permissions-Policy [directives](https://w3c.github.io/webappsec-permissions-policy/#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](https://github.com/debug-js/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:
```sh
# print all logging statements
export DEBUG=11ty-plugin:*
```
## Dependencies
| Package | Version |
|---|---|
| [zod](https://www.npmjs.com/package/zod) | `^3.22.4` |
| [zod-validation-error](https://www.npmjs.com/package/zod-validation-error) | `^3.0.0` |
## License
© 2022 - 2024 [Giacomo Debidda](https://www.giacomodebidda.com/) // [MIT License](https://spdx.org/licenses/MIT.html)