Skip to content
Last updated on February 23, 2023
6 min read

Headers are small pieces of information that are sent between the client (usually a web browser) and the server. They contain metadata about the request and response, such as the content type, cache-control directives, and authentication tokens. HTTP headers can be found in both the HTTP Request and HTTP Response.

By using headers effectively, you can optimize the performance and security of your application on Vercel's edge network. Here are some tips for using headers on Vercel:

  1. Use caching headers: Caching headers instruct the client and server to cache resources like images, CSS files, and JavaScript files, so they don't need to be reloaded every time a user visits your site. By using caching headers, you can significantly reduce the time it takes for your site to load.
  2. Use compression headers: Use the Accept-Encoding header to tell the client and server to compress data before it's sent over the network. By using compression, you can reduce the amount of data that needs to be sent, resulting in faster load times.
  3. Use custom headers: You can also use custom headers in your vercel.json file to add metadata specific to your application. For example, you could add a header that indicates the user's preferred language or the version of your application. See Project Configuration docs for more information.

The following headers are sent to each Vercel deployment and can be used to process the request before sending back a response. These headers can be read from the Request object in your Serverless Function.

This header represents the domain name as it was accessed by the client. If the deployment has been assigned to a preview URL or production domain and the client visits the domain URL, it contains the custom domain instead of the underlying deployment URL.

By default, Vercel assigns your deployment to IAD1 region, which ensures that your Serverless Functions are located geographically close to a US-East data center.

When your deployment gets multiple regions, the first is closest to the user, and the second is deployed to the data center. If there is no region, then it's considered a regional miss. In such a case, you change the region to IAD1 irrespective of your pricing plan.

This header is identical to the host header.

This header represents the protocol of the forwarded server, typically https in production and httpin development.

The public IP address of the client that made the request. If you are trying to use Vercel behind a proxy, we currently overwrite the X-Forwarded-For header and do not forward external IPs. This restriction is in place to prevent IP spoofing. Please contact us if allowing Vercel to trust your X-Forwarded-For IP is a feature your Team needs (Enterprise only).

This header is identical to the x-forwarded-for header. However, x-forwarded-for could be overwritten if you're using a proxy on top of Vercel.

This header is identical to the x-forwarded-for header.

This header represents the unique deployment, not the preview URL or production domain. For example, *

A two-character ISO 3166-1 country code for the country associated with the location of the requester's public IP address.

A string of up to three characters containing the region-portion of the ISO 3166-2 code for the first level region associated with the requester's public IP address. Some countries have two levels of subdivisions, in which case this is the least specific one. For example, in the United Kingdom this will be a country like "England", not a county like "Devon".

The city name for the location of the requester's public IP address. Non-ASCII characters are encoded according to RFC3986.

The latitude for the location of the requester's public IP address. For example, 37.7749.

The longitude for the location of the requester's public IP address. For example, -122.4194.

The name of the time zone for the location of the requester’s public IP address in ICANN Time Zone Database name format such as America/Chicago.

The following headers are included in Vercel deployment responses and indicate certain factors of the environment. These headers can be viewed from the Browser's Dev Tools or using an HTTP client such as curl -I <DEPLOYMENT_URL>.

Used to specify directives for caching mechanisms in both the Network layer cache and the browser cache. See the Cache Control Headers section for more detail.

The default value is cache-control: public, max-age=0, must-revalidate which instructs both the Edge Network and the browser not to cache.

An integer that indicates the number of bytes in the response.

The media type that describes the nature and format of the response.

A timestamp indicating when the response was generated.

Shows where the request came from. This header can be overridden by other proxies (e.g., Cloudflare).

A header often abbreviated as HSTS that tells browsers that the resource should only be requested over HTTPS. The default value is strict-transport-security: max-age=63072000 (2 years)

This header is automatically added with noindex to Preview Deployments to prevent search engines from crawling them. A deployment without this header can be created by pointing a production domain to it. If this is not desired, one can always disable the header manually using the headers configuration.

This header's value indicates whether the response was served from Vercel's edge cache.

The following values are possible when the content being served is static or uses a Cache-Control header.

The response was not found in the edge and thus fetched from an origin server. (Learn more)
The response was served from the edge. (Learn more)
The response is stale (served from the edge). A background request to the origin was made to get a fresh version. (Learn more)
The cache was bypassed and so the response was served from an origin server. (Learn more)
The response was served from static storage. (Learn more)
The response was served from origin and the cache was refreshed due to an authorization from the user in the incoming request. (Learn more)

To understand under what situations each of the above headers are generated, review the diagrams on this page.

The unique identifier for each request. Contains a list of regions through which the request has traversed, usually the region center closest to the visitor.

Vercel's Edge Network supports a variety of Cache-Control directives.

The default value is cache-control: public, max-age=0, must-revalidate which instructs both the Edge Network and the browser not to cache.

The following example instructs the Edge Network to cache the response for 60 seconds. A response can be cached a minimum of 1 second and maximum of 31536000 seconds (1 year).

Cache-Control: s-maxage=60

Note: When s-maxage is set, Vercel's Edge strips the s-maxage directive and does not return it to the client.

The following example instructs the Edge Network to:

  • Serve content from the Edge cache for 1 second
  • Return a stale request (if requested after 1 second)
  • Update the cache in the background asynchronously (if requested after 1 second)
Cache-Control: s-maxage=1, stale-while-revalidate=59

If you need to do a synchronous revalidation you can set the pragma: no-cache header along with the cache-control header. This can be used to understand how long the background revalidation took. It sets the x-vercel-cache header to REVALIDATED.

Note: Many browser developer tools set pragma: no-cache by default, which reveals the true load time of the page with the synchronous update to the cache.

Using configuration, you can assign custom headers to each response.

Custom headers can be configured with the headers property in next.config.js for Next.js projects, or it can be configured in vercel.json for all other projects.

Alternatively, a Serverless Function can assign headers to the Response object.

Note: Response headers x-matched-path, server, and content-length are reserved and cannot be modified.