How To Implement Content Security Policy (CSP) Headers For Astro

Content Security Policy is like a bouncer for your website. It tells the browser what content is allowed to load and from where. This helps prevent a whole bunch of nasty attacks, like Cross-Site Scripting (XSS) and data injection.

Update: Astro Now Has Native CSP Support

As of Astro 5.9.0, you can enable native CSP support through an experimental feature. This is the recommended approach now instead of the workarounds below.

Here’s the basic setup:

1
import { defineConfig } from 'astro/config';
2

3
export default defineConfig({
4
  experimental: {
5
    csp: true
6
  }
7
});

Astro automatically generates CSP hashes for your inline scripts and styles. No more 'unsafe-inline' directives.

If you’re using Vercel, Netlify, or Node adapters, enable experimentalStaticHeaders to serve CSP headers properly:

1
import { defineConfig } from 'astro/config';
2
import vercel from '@astrojs/vercel';
3

4
export default defineConfig({
5
  experimental: {
6
    csp: true
7
  },
8
  adapter: vercel({
9
    experimentalStaticHeaders: true
10
  })
11
});

You can customize CSP directives in your config:

1
export default defineConfig({
2
  experimental: {
3
    csp: {
4
      directives: [
5
        "default-src 'self'",
6
        "img-src 'self' https://images.cdn.example.com"
7
      ],
8
      scriptDirective: {
9
        resources: ["https://cdn.example.com"],
10
        strictDynamic: true
11
      }
12
    }
13
  }
14
});

For per-page CSP customization, use the runtime API in your Astro components:

1
---
2
Astro.csp.insertDirective("default-src 'self'");
3
Astro.csp.insertScriptResource("https://scripts.cdn.example.com");
4
---

This eliminates the need for vercel.json files or Cloudflare Page Rules. The CSP is now part of Astro’s build process.

Legacy Approaches

The methods below still work but are no longer the recommended way. Use native CSP support instead.

Content Security Policy (CSP) should be implemented as a response header, not a request header. The server sends the CSP directives to the browser as part of its response, and the browser enforces these policies when loading content.

Here’s a basic CSP setup using the old astro.config.mjs approach (development only):

1
import { defineConfig } from 'astro/config';
2

3
export default defineConfig({
4
  server: {
5
    headers: {
6
      "Content-Security-Policy": "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline';"
7
    }
8
  }
9
});

The default-src 'self' directive only allows resources from the same origin. The script-src and style-src directives allow inline scripts and styles, which Astro uses for hydration.

The Astro CSP Gotcha

Astro has a unique architecture that can trip up CSP. It uses a technique called “partial hydration” where some components are static and others are interactive. This means your CSP needs to be flexible enough to allow for this hybrid approach.

Here’s a more comprehensive CSP for a typical Astro site.

1
export default defineConfig({
2
  server: {
3
    headers: {
4
      "Content-Security-Policy": `
5
        default-src 'self';
6
        script-src 'self' 'unsafe-inline' 'unsafe-eval';
7
        style-src 'self' 'unsafe-inline';
8
        img-src 'self' data: https:;
9
        font-src 'self';
10
        object-src 'none';
11
        base-uri 'self';
12
        form-action 'self';
13
        frame-ancestors 'none';
14
        block-all-mixed-content;
15
        upgrade-insecure-requests;
16
      `
17
    }
18
  }
19
});

This policy is more permissive but still secure. It allows for Astro’s hydration needs 'unsafe-eval' and common use cases like loading images from HTTPS sources.

Vercel Approach

With Vercel, you can use a vercel.json file in your project root:

1
{
2
  "headers": [
3
    {
4
      "source": "/(.*)",
5
      "headers": [
6
        {
7
          "key": "Content-Security-Policy",
8
          "value": "default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval'; style-src 'self' 'unsafe-inline';"
9
        }
10
      ]
11
    }
12
  ]
13
}

This applies the CSP header to all routes on your Vercel-deployed Astro site. All you have to do with git push to deploy your changes.

Cloudflare Approach

Cloudflare uses Page Rules to add headers. Go to your Cloudflare dashboard, navigate to Rules > Page Rules, and click the ‘Modify Response Headers’ tab. Create a new rule and add a static header to the response with the header name Content-Security-Policy and your CSP string as the value.

The advantage here is you can update your CSP without redeploying your site.

Read Also

• Frontend Security Checklist
• MDN Web Docs: Content Security Policy