@jackdbd/eleventy-plugin-content-security-policy v2.2.0

@jackdbd/eleventy-plugin-content-security-policy

Eleventy plugin that writes Content-Security-Policy and Content-Security-Policy-Report-Only headers to a _headers file when Eleventy builds your site.

• Installation
• About
• Usage
• Configuration
• Troubleshooting
• Dependencies
• License

Installation

npm install @jackdbd/eleventy-plugin-content-security-policy

Note: this library was tested on Node.js >=18. It might work on other Node.js versions though.

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 Content-Security-Policy (CSP) or a Content-Security-Policy-Report-Only header in your Eleventy configuration file, and then it automatically writes those headers into your _headers file when you build your site.

Usage

In your Eleventy config file:

import { contentSecurityPolicyPlugin } from '@jackdbd/eleventy-plugin-content-security-policy'

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

  // use the default CSP directives (not recommended)...
  eleventyConfig.addPlugin(contentSecurityPolicyPlugin)

  // ...or define your CSP directives
  eleventyConfig.addPlugin(contentSecurityPolicyPlugin, {
    allowDeprecatedDirectives: true,
    
    directives: {
      'base-uri': ['self'],

      // allow only self-hosted fonts (i.e. fonts hosted on this origin)
      'font-src': ['self'],

      // allow scripts hosted on this origin, on plausible.io (analytics),
      // cloudflareinsights.com (analytics), unpkg.com (preact)
      'script-src-elem': [
        'self',
        'https://plausible.io/js/plausible.js',
        'https://static.cloudflareinsights.com/beacon.min.js',
        'https://unpkg.com/htm/preact/standalone.module.js'
      ],

      // allow CSS hosted on this origin, and inline styles that match a sha256
      // hash automatically computed at build time by this 11ty plugin.
      // See also here for the pros and cons of 'unsafe-inline'
      // https://stackoverflow.com/questions/30653698/csp-style-src-unsafe-inline-is-it-worth-it
      'style-src-elem': ['self', 'sha256'],
    },

    // Only .html files should be served with the Content-Security-Policy header. Avoid header bloat by making sure that other files are not served with Content-Security-Policy header.
    globPatternsDetach: ['/*.png'],

    includePatterns: ['/**/**.html']
  })

  // some other eleventy configuration...
}

Configuration

Refer also to the library @jackdbd/content-security-policy for the configuration.

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

⚠️ Peer Dependencies

This package defines 2 peer dependencies.

License

© 2022 - 2024 Giacomo Debidda // MIT License