experimentalStaticHeaders not working on Vercel

[wKovacs64]

Astro Info

Astro                    v5.10.0
Node                     v20.19.1
System                   Linux (x64)
Package Manager          npm
Output                   static
Adapter                  @astrojs/vercel
Integrations             none

If this issue only occurs in one browser, which browser is a problem?

N/A

Describe the Bug

Enabling experimentalStaticHeaders in the @astrojs/vercel adapter (combined with enabling experimental CSP) does write the CSP to .vercel/output/config.json, but the CSP header doesn't actually get included in the document response.

Deployed URL of the minimal template with the documented config options:

https://github-2y2x5yu5-8i6au4xks-justin-halls-projects-df945a1f.vercel.app

What's the expected result?

The document response would include the CSP header.

Link to Minimal Reproducible Example

https://stackblitz.com/edit/github-2y2x5yu5?file=astro.config.mjs

Participation

• I am willing to submit a pull request for this issue.

[ematipico]

Ooooh, I think I messed up the configuration 😅

I implemented this: https://vercel.com/docs/project-configuration

But it should have been this: https://vercel.com/docs/build-output-api/configuration#routes

[moonclavedev]

@ematipico Thanks for all the work you've done here, everything works beautifully up until you start configuring all the allowed domains and the hashes start piling up:

  styleDirective: {
    resources: ["'self'"],
    hashes: [
      "sha256-....",
      "sha256-....",
      "sha256-....",
      "sha256-....",
      "sha256-....",
      "sha256-....",
      "sha256-....",
      "sha256-....",
      "sha256-....",
      "sha256-....",
      "sha256-....etc",
    ],
  },
  scriptDirective: {
    resources: ["'self'"],
    hashes: [
      "sha256-....",
      "sha256-....",
      "sha256-....",
      "sha256-....",
      "sha256-....",
      "sha256-....",
      "sha256-....",
      "sha256-....",
      "sha256-....",
      "sha256-....",
      "sha256-....etc",
    ],
  },

Which unfortunately results in overloading the body size and failing the build with:

Error: Body exceeded 3300kb limit

Build Screenshot:

I confirmed by:

1. Re-running the build to rule out any Vercel hiccups (❌ build failed)
2. Commenting out a bunch of hashes (✅ build passed)

Not sure if this is total size of total build output (we are building 2.5k pages) or if it's the size of each header output individually.

Not seeing anything about this in Vercel docs, but came across a similar issue: https://community.vercel.com/t/deployment-failure-error-body-exceeded-3300kb-limit/6400

[ematipico]

This is one of the limitations of using headers. Response headers have a size limit that depends on the web server: https://stackoverflow.com/questions/686217/maximum-on-http-header-values

You could see how removing some values from the header, led to removing the error.

Not sure if that's directly connected to your issue, but I'm afraid we can't do much to solve the problem

[wKovacs64]

I guess Astro could introduce an option to use self (or whatever) instead of hashes?

[moonclavedev]

@ematipico @wKovacs64

Well after a few days of digging and testing, I've figured out the problem.

Initially I noticed when I removed a bunch of hashes, the build would pass. However, the builds began to fail even with hashes removed - so stripped out additional i18n languages (cutting down dramatically from the ~2.5k pages) the build would then pass.

After realizing that the Vercel “Body exceeded 3300kb limit” build error is about a single payload Vercel is trying to send during build/deploy and not the total size of the built site (or the actual Header payload mentioned above) - I decided to analyze .vercel/output/config.json by running local cli command: vercel build, which would allow me to analyze the output from my machine.

Boom. An extremely bloated 9MB config.json file (way over the 3.3MB limit), with over 15k lines loaded with duplicate csp headers for every single route of the site!

Now realizing the Vercel Adapter outputs CSP header per route, I took advantage of building out a custom Astro Integration which runs astro:build:done hook, polls for .vercel/output/config.json, and then strips the individual route headers and consolidates into a single global CSP header entry bringing us down from 9MB → 10KB!

See here:
https://github.com/aptos-labs/aptos-docs/pull/227/files

While this works perfectly, I do understand this final step is a bit of a hack and would love to propose an option for header consolidation from the Vercel Adapter itself, reducing the need for this custom integration.

I imagine there will be others running into this issue down the road, especially given Astro’s positioning as a framework for large, content-heavy websites. Once you add i18n into the mix it’s pretty easy to bloat this config file. Beyond the build concerns, consolidating headers might also help performance by reducing how many route entries Vercel needs to parse and match against.

Does that sound realistic @ematipico ?

[ematipico]

That's definitely something we would want to address!

How did you consolidate the headers? If you manage to get familiar with the adapter's codebase, please consider sending a PR

[moonclavedev]

@ematipico already have a working patch for the adapter, which has allowed me to remove the hacky Astro Integration.

I'll create a PR next week when I have some time, but basically:

diff --git a/dist/index.js b/dist/index.js
index f3fb62cd0a9be9314860e540ad7cdbc9b057af59..fa7fb11271cc18cf9a68cc2032672bb27fea4505 100644
--- a/dist/index.js
+++ b/dist/index.js	
@@ -410,8 +410,20 @@ function vercelAdapter({
           if (!normalized.routes) {
             normalized.routes = [];
           }
-          if (experimentalStaticHeaders) {
-            const routesWithConfigHeaders = createRoutesWithStaticHeaders(_routeToHeaders, _config);
+          // Normalize `experimentalStaticHeaders` into flags we can use.
+          const _staticHeadersEnabled =
+            experimentalStaticHeaders === true || typeof experimentalStaticHeaders === 'object';
+          const _cspMode =
+            typeof experimentalStaticHeaders === 'object' && experimentalStaticHeaders?.cspMode
+              ? experimentalStaticHeaders.cspMode
+              : 'per-route';
+
+          if (_staticHeadersEnabled) {
+            const routesWithConfigHeaders = createRoutesWithStaticHeaders(
+              _routeToHeaders,
+              _config,
+              _cspMode
+            );
             const fileSystemRouteIndex = normalized.routes.findIndex(
               (r) => "handle" in r && r.handle === "filesystem"
             );
@@ -555,20 +567,31 @@ function getRuntime(process2, logger) {
   }
   return "nodejs22.x";
 }
-function createRoutesWithStaticHeaders(staticHeaders, config) {
+function createRoutesWithStaticHeaders(staticHeaders, config, cspMode = 'per-route') {
   const vercelHeaders = [];
+  if (!config.experimental.csp) return vercelHeaders;
+
+  // GLOBAL MODE — collapse to a single catch-all CSP header
+  if (cspMode === 'global') {
+    let csp;
+    for (const { headers } of staticHeaders.values()) {
+      const v = headers.get('Content-Security-Policy');
+      if (v) { csp = v; break; }
+    }
+    if (csp) {
+      vercelHeaders.push({ src: '/(.*)', headers: { 'content-security-policy': csp } });
+    }
+    return vercelHeaders;
+  }
+
+  // PER-ROUTE MODE — existing behavior
   for (const [pathname, { headers }] of staticHeaders.entries()) {
-    if (config.experimental.csp) {
-      const csp = headers.get("Content-Security-Policy");
-      if (csp) {
-        const _headers = {
-          "content-security-policy": csp
-        };
-        vercelHeaders.push({
-          src: pathname,
-          headers: _headers
-        });
-      }
+    const csp = headers.get("Content-Security-Policy");
+    if (csp) {
+      vercelHeaders.push({
+        src: pathname,
+        headers: { "content-security-policy": csp }
+      });
     }
   }
   return vercelHeaders;