Using Netlify Edge Handlers to Add Custom Headers at the Edge

Overview

Netlify Edge Handlers let you run Deno code on Netlify’s global edge nodes before a request reaches your origin or static assets. This is useful for tasks such as adding headers, redirecting traffic, or rewriting HTML without provisioning a full serverless function.

Configuration

Define handlers in netlify.yml under the edge_handlers list. Each entry matches a URL pattern and points to a TypeScript or JavaScript file that exports a default async function.

# netlify.yml
edge_handlers:
  - path: /api/*          # matches any request under /api/
    function: ./edge-handlers/add-header.ts

Example Handler

The handler below forwards the original request, then adds a custom response header x-edge-test with the value true. It uses the fetch‑like API provided by the Edge Handler runtime.

// ./edge-handlers/add-header.ts
export default async (request: Request): Promise {
  // Forward the request to the origin (or static site)
  const response = await fetch(request);
  // Add a custom header
  response.headers.set('x-edge-test', 'true');
  return response;
}

Limits and Common Mistakes

• CPU time limit: Each handler execution is capped at ~50 ms of CPU time. Heavy loops or large data processing will cause a 502 error.
• Environment variables: Only variables explicitly exposed in the site settings are accessible; reading a hidden variable returns undefined.
• Network calls: Outbound fetch is disabled unless you enable the netlify:edge:fetch feature flag in site settings.
• Debugging: Use netlify dev --edge locally; console output appears in deploy logs, not the terminal.

Verification

After deploying, run a request that matches the handler’s path and inspect the response headers.

# Replace with your site’s URL
curl -I https://example.netlify.app/api/hello

Look for x-edge-test: true in the headers. If the header is missing, check the deploy logs for any runtime errors.