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

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 contains a few different rewrites :

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

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

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

The second rule rewrites requests to "/resize/:width/:height" to "/api/sharp", which 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.

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

This example 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/. For 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. This file specifies three different redirects:

1. Rewrites all requests from /api/* to https://api.example.com/*. The :path* syntax is a wildcard that captures any path under /api/ and passes it to the destination URL
2. Rewrites requests from /resize/:width/:height to /api/sharp; a serverless function that processes image resizing requests. For example, /resize/100/50 would be rewritten to /api/sharp?width=100&height=50
3. Uses a has key to specify that this rewrite only happens when the x-vercel-ip-country header has a value of GB. When a request comes from the UK, it will be rewritten to a UK-specific path

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 and simple to understand. 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*"
    }
  ]
}

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