> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/stormkit-io/stormkit-io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Warning>
  Custom headers are not applied to responses from serverless functions.
</Warning>

## 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.

<Steps>
  <Step title="Create headers file">
    Create a `_headers` file in your repository root (or specify a custom location in your Stormkit dashboard)
  </Step>

  <Step title="Define header rules">
    Define your header rules using the format described below
  </Step>

  <Step title="Deploy">
    Commit and deploy your changes. Headers will be applied automatically.
  </Step>
</Steps>

<Info>
  Check out our [YouTube video](https://www.youtube.com/watch?v=0-JE_MoXP68) to see custom headers in action.
</Info>

## 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.

```yaml _headers theme={null}
# 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

<CardGroup cols={2}>
  <Card title="Security Headers" icon="shield">
    Add security headers like CSP, X-Frame-Options, and HSTS to protect your application.
  </Card>

  <Card title="CORS Configuration" icon="globe">
    Configure Cross-Origin Resource Sharing headers for API endpoints and assets.
  </Card>

  <Card title="Cache Control" icon="clock">
    Set cache directives to optimize performance and control browser caching.
  </Card>

  <Card title="Custom Metadata" icon="tag">
    Add custom headers for tracking, debugging, or application-specific metadata.
  </Card>
</CardGroup>

## Examples

### Security Headers

```yaml _headers theme={null}
/*
  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

```yaml _headers theme={null}
/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

```yaml _headers theme={null}
# 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

```yaml _headers theme={null}
# 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.

<Steps>
  <Step title="Navigate to Headers config">
    Go to **Environment Config** > **Headers**
  </Step>

  <Step title="Enable overwrite">
    Switch **Overwrite headers** toggle
  </Step>

  <Step title="Add rules">
    Specify the rules from the Headers Editor
  </Step>

  <Step title="Save">
    Click save
  </Step>
</Steps>

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

## 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.

<Frame>
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/stormkit-io-stormkit-io/assets/blog/manifest.gif" alt="Deployment manifest showing header details" />
</Frame>

## 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

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="Headers conflict">
    * Environment-level headers override file-based headers
    * More specific patterns override general patterns
    * Check for duplicate header definitions
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>