Package Exports

astro-cloudflare-pages-headers

Readme

astro-cloudflare-pages-headers

npm GitHub

GitHub Release Date GitHub last commit

GitHub Actions Workflow Status

A lightweight integration for Astro that automatically generates a Cloudflare Pages _headers file for deployments based on your server header configuration.

Features

Automatic _headers generation: Reads header settings from your astro.config.mjs and generates a _headers file during build.
Flexible configuration: Supports both flat and nested header formats.
Informative logging: Provides useful log messages during setup and build

Installation

Install the integration via the astro add command:

astro add astro-cloudflare-pages-headers

Usage

Add the integration to your Astro configuration file (astro.config.mjs). The integration looks for header settings in the server.headers property:

Example with Flat Headers

astro.config.mjs:

import { defineConfig } from 'astro/config';
import { astroCloudflarePagesHeaders } from 'astro-cloudflare-pages-headers';

export default defineConfig({
  integrations: [
    astroCloudflarePagesHeaders(),
  ],
  server: {
    headers: {
      'X-Custom-Header': 'my-value',
      'X-Another-Header': 'another-value'
    },
  },
});

This configuration generates the following _headers file:

/*
  X-Custom-Header: my-value
  X-Another-Header: another-value

Example with Nested Headers

astro.config.mjs:

import { defineConfig } from 'astro/config';
import { astroCloudflarePagesHeaders } from 'astro-cloudflare-pages-headers';

export default defineConfig({
  integrations: [
    astroCloudflarePagesHeaders(),
  ],
  server: {
    headers: {
      '/api': {
        'Cache-Control': 'max-age=3600',
      },
      '/static': {
        'X-Frame-Options': 'DENY',
      },
    },
  },
});

This configuration generates the following _headers file:

/api
  Cache-Control: max-age=3600

/static
  X-Frame-Options: DENY

How It Works

Setup

astro:config:setup

The integration reads your header configuation from config.server.headers and stores it internally.

Build

astro:build:done

If headers are configured, it converts them into the appropriate Cloudflare Pages format.
It writes the generated content to a _headers file in your build output directory.
Logs inform you if the file is successfully written or if any errors occur.
If no headers are configured, it logs a warning and skips file generation.

Development

Running Unit Tests

This project uses Vitest for testing. To run the tests:

Unit tests cover various scenarios including flat headers, nested headers, error handling, and logging verification.

npm test

pnpm test

yarn test

Testing Your Header Configuration

MDN Observatory is a great tool for testing your headers. You can use it to test your headers locally or after deploying to Cloudflare Pages.

Contributing

Contributions and improvements are welcome. Feel free to open issues or submit pull requests on the repository.

License

This project is licensed under the MIT License. See the LICENSE file for details.

JSPM