Astro-cloudflare-pages-headers NPM

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.