A lightweight integration for Astro that automatically generates a Cloudflare Pages _headers file for deployments based on your server header configuration.
!GitHub Release Date
!GitHub last commit
!GitHub Actions Workflow Status
!GitHub Actions Workflow Status
!GitHub Actions Workflow Status
!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.
- 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
Install the integration via the astro add command:
``bash`
astro add astro-cloudflare-pages-headers
Add the integration to your Astro configuration file (astro.config.mjs). The integration looks for header settings in the server.headers property:
astro.config.mjs:
`js,ts
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:
`plaintext`
/*
X-Custom-Header: my-value
X-Another-Header: another-value
astro.config.mjs:`js,ts
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:
`plaintext
/api
Cache-Control: max-age=3600
/static
X-Frame-Options: DENY
`
astro:config:setup
The integration reads your header configuation from config.server.headers and stores it internally.
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.
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.
`bash`
npm test
`bash`
pnpm test
`bash``
yarn test
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.
Contributions and improvements are welcome. Feel free to open issues or submit pull requests on the repository.
This project is licensed under the MIT License. See the LICENSE file for details.
- Astro
- Configuration Reference
- Server Headers
- Integrations
- Cloudflare Pages
- Cloudflare Pages Documentation
- Customizing Headers
- MDN Observatory
- mdn-http-observatory
- Vitest
- MIT License