Rewrites on Vercel

Rewrites allow you to send users to different URLs without modifying the visible URL. They allow you to change the URL path, query parameters, and headers of the request before it reaches your server.

You can also use them to return different responses depending on the headers of the incoming request (such as User-Agent, which contains the type of device and browser that the request originated from).

The /.well-known path is reserved and cannot be redirected or rewritten. Only Enterprise teams can configure custom SSL. Contact sales to learn more.

Rewrites are defined in a vercel.json file, which is located in the root of your application. For more information on all available properties, see the project configuration docs.

Here's an example of a vercel.json file that rewrites to an external destination:

{
  "rewrites": [
    {
      "source": "/api/:path*",
      "destination": "https://api.example.com/:path*"
    }
  ]
}

In this example, source defines the incoming path pattern to match, and destination defines the URL to rewrite to. The :path* syntax is a wildcard that captures any path after /api/ and passes it to the destination URL.

In the second example below, the rule rewrites incoming requests for /resize/:width/:height to /api/sharp:

{
  "rewrites": [
    {
      "source": "/resize/:width/:height",
      "destination": "/api/sharp"
    }
  ]
}

In this example, /api/sharp could be a Serverless Function that processes image resizing requests. For example, /resize/100/50 would be rewritten to /api/sharp?width=100&height=50.

In the third example below, the rule rewrites requests to any path that does not start with uk/ and has a x-vercel-ip-country header value of GB to a corresponding path under /uk/:

{
  "rewrites": [
    {
      "source": "/:path((?!uk/).*)",
      "has": [
        {
          "type": "header",
          "key": "x-vercel-ip-country",
          "value": "GB"
        }
      ],
      "destination": "/uk/:path*"
    }
  ]
}

In this example, a request to /about would be rewritten to /uk/about. This rule also uses a has key to specify a condition that must be met for the rewrite to be applied. In this case, the condition is that the request must include a x-vercel-ip-country header with a value of GB. This allows the rewrite rule to apply only to requests coming from the UK, while leaving other requests unaffected.

Vercel supports caching rewrites based on your response's Cache-Control headers. You can opt in to caching by setting the request header x-vercel-enable-rewrite-caching to a value of 1.

Here's an example of a vercel.json file that redirects to an external destination and has caching enabled:

{
  "rewrites": [
    {
      "source": "/api/:path*",
      "destination": "https://api.example.com/:path*"
    }
  ]
  "headers": [
    {
      "source": "/(.*)",
      "headers": [
        {
          "key": "x-vercel-enable-rewrite-caching",
          "value": "1"
        }
      ]
    }
  ]
}

Vercel supports many of the most popular frontend frameworks, but rewrite support varies. Frameworks that use client-side routing, or other routing techniques that don't hit proxies, may demonstrate inconsistent behavior.

Read your preferred framework's documentation to understand how its routing works. You can also read our dedicated framework docs to learn if there are any nuances to using your preferred framework with Vercel's rewrites.

Some examples of frameworks that don't support rewrites with vercel.json include:

• Astro
• SvelteKit

When implementing rewrites on Vercel, there are several best practices to keep in mind:

1. Use Descriptive Source and Destination URLs: Source and destination URLs should be descriptive. This helps you and other developers quickly understand what the rule is doing.

2. Be Careful with Wildcards: Wildcards can be powerful, but they can also be dangerous if not used carefully. Make sure you fully understand the implications of using a wildcard before implementing it

3. Use Regex for Complex Patterns: For more complex routing scenarios, use regular expressions in the source field to match specific patterns. Here's an example that rewrites all requests from /api/* or /v1/* to https://api.example.com/*:

{
  "rewrites": [
    {
      "source": "/(api|v1)/:path*",
      "destination": "https://api.example.com/:path*"
    }
  ]
}

4. Test Your Rewrites: Always test your rewrites thoroughly before deploying them to production. You can use a preview deployment to test your rewrites in a staging environment before deploying them to your live site