Custom Headers

Custom headers enable you to modify or supplement the default HTTP headers provided by Stormkit when a client requests your site.

Overview

Custom headers enable you to modify or supplement the default HTTP headers provided by Stormkit when a client requests your site. This is useful for setting security headers, CORS policies, caching directives, and more.

Custom headers are not applied to responses from serverless functions.

Configuration

By default, Stormkit looks for a _headers file in your repository root. If you need to use a different location, you can specify it by navigating to Environment > Config > Headers > File Location in your Stormkit dashboard.

1. Create headers file

   Create a _headers file in your repository root (or specify a custom location in your Stormkit dashboard)

2. Define header rules

   Define your header rules using the format described below

3. Deploy

   Commit and deploy your changes. Headers will be applied automatically.

Check out our YouTube video to see custom headers in action.

Header File Format

Header rules are structured in multi-line blocks. Each block begins with a URL or URL pattern that specifies where the rule’s headers should take effect. Following this, header names and their corresponding values are listed on indented lines.

_headers

# Apply X-Message to all requests
/*
  X-Message: Hello World!

# Apply following headers to .js files only
/*.js
  Access-Control-Allow-Origin: *
  Access-Control-Allow-Headers: *
  Access-Control-Allow-Methods: *

Common Use Cases

Security Headers

Add security headers like CSP, X-Frame-Options, and HSTS to protect your application.

CORS Configuration

Configure Cross-Origin Resource Sharing headers for API endpoints and assets.

Cache Control

Set cache directives to optimize performance and control browser caching.

Custom Metadata

Add custom headers for tracking, debugging, or application-specific metadata.

Examples

Security Headers

_headers

/*
  X-Frame-Options: DENY
  X-Content-Type-Options: nosniff
  Referrer-Policy: strict-origin-when-cross-origin
  Permissions-Policy: geolocation=(), microphone=(), camera=()
  Content-Security-Policy: default-src 'self'; script-src 'self' 'unsafe-inline'

CORS Headers

_headers

/api/*
  Access-Control-Allow-Origin: *
  Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
  Access-Control-Allow-Headers: Content-Type, Authorization
  Access-Control-Max-Age: 86400

Cache Control

_headers

# Cache static assets for 1 year
/static/*
  Cache-Control: public, max-age=31536000, immutable

# Don't cache HTML files
/*.html
  Cache-Control: no-cache, no-store, must-revalidate

Custom Headers by File Type

_headers

# Headers for JavaScript files
/*.js
  Content-Type: application/javascript; charset=utf-8
  Cache-Control: public, max-age=31536000

# Headers for CSS files
/*.css
  Content-Type: text/css; charset=utf-8
  Cache-Control: public, max-age=31536000

# Headers for images
/*.{png,jpg,jpeg,gif,webp}
  Cache-Control: public, max-age=31536000

Environment Level Custom Headers

You can specify the same rules at an environment level, which will override the _headers file in your repository.

1. Navigate to Headers config

   Go to Environment Config > Headers

2. Enable overwrite

   Switch Overwrite headers toggle

3. Add rules

   Specify the rules from the Headers Editor

4. Save

   Click save

These rules will be applied to all of your deployments and take effect instantly. There is no need for a deployment.

Viewing Applied Headers

You can review the deployment manifest to understand how Stormkit builds your code. This allows you to easily see which headers are applied to which files.

Best Practices

• Test headers locally - Verify header syntax before deploying
• Use specific patterns - Target specific file types or paths for better control
• Security first - Always include security headers for production environments
• Monitor performance - Use cache headers wisely to balance freshness and performance
• Document custom headers - Keep a record of why specific headers are set

Troubleshooting

Headers not applying

• Verify the _headers file is in the correct location
• Check the file format and indentation
• Ensure the path pattern matches your files
• Remember: headers don’t apply to serverless functions

Headers conflict

• Environment-level headers override file-based headers
• More specific patterns override general patterns
• Check for duplicate header definitions

CORS errors persisting

• Ensure CORS headers are applied to the correct paths
• Check that preflight OPTIONS requests are handled
• Verify Origin header matches allowed origins