Conceptual
8 min read
Table of Contents

Redirects are rules that instruct Vercel to send users to a different URL than the one they requested. For example, if you rename a public route in your application, adding a redirect ensures there are no broken links for your users.

With redirects on Vercel, you can define HTTP redirects in your application's configuration, regardless of the framework that you are using, including both dynamic and static redirects. Redirects are processed at the Edge across all regions.

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

  • Moving to a new domain: Redirects help maintain a seamless user experience when moving a website to a new domain by ensuring that visitors and search engines are aware of the new location.
  • Replacing a removed page: If a page has been moved, temporarily or permanently, you can use redirects to send users to a relevant new page, thus avoiding any negative impact on user experience.
  • Canonicalization of multiple URLs: If your website can be accessed through several URLs (e.g., acme.com/home, home.acme.com, or www.acme.com), you can choose a canonical URL and use redirects to guide traffic from the other URLs to the chosen one.
  • Geolocation-based redirects: Redirects can be configured to consider the source country of requests, enabling tailored experiences for users based on their geographic location.

We recommend using the framework-native solution for dynamic redirects.

app/api/route.ts
import { redirect } from 'next/navigation';
 
export async function GET(request: Request) {
  redirect('https://nextjs.org/');
}
app/api/route.ts
import { redirect } from 'next/navigation';
 
export const runtime = 'edge';
 
export async function GET(request: Request) {
  redirect('https://nextjs.org/');
}

For dynamic, critical redirects that need to run on every request, you can use Edge Middleware and Edge Config.

Redirects can be stored in an Edge Config and instantly read from Edge Middleware. This enables you to update redirect values without having to redeploy your website.

Deploy a template to get started.

You can redirect a www subdomain to an apex domain, or other domain redirects, through the Domains section of the dashboard.

You can use configuration-based redirects to generate routing rules during the build process. This includes temporary redirects (307), permanent redirects (308), and geolocation-based redirects.

Configuration-based redirects can be defined in framework-specific config file or in the vercel.json file, which is located in the root of your application. The vercel.json should contain a redirects field, which is an array of redirect rules. For more information on all available properties, see the project configuration docs.

When using Next.js, you do not need to use vercel.json. Instead, use the framework-native next.config.js to define configuration-based redirects.

next.config.js
module.exports = {
  async redirects() {
    return [
      {
        source: '/about',
        destination: '/',
        permanent: true,
      },
      {
        source: '/old-blog/:slug',
        destination: '/news/:slug',
        permanent: true,
      },
      {
        source: '/:path((?!uk/).*)',
        has: [
          {
            type: 'header',
            key: 'x-vercel-ip-country',
            value: 'GB',
          },
        ],
        permanent: false,
        destination: '/uk/:path*',
      },
    ];
  },
};

Learn more in the Next.js documentation.

When deployed, these redirect rules will be deployed to every region in Vercel's Edge Network.

Vercel supports both temporary and permanent redirects.

  • 307 Temporary Redirect: Not cached by client, the method and body never changed. This type of redirect does not affect SEO and search engines will treat them as normal redirects.
  • 302 Found: Not cached by client, the method may or may not be changed to GET.
  • 308 Permanent Redirect: Cached by client, the method and body never changed. This type of redirect does not affect SEO and search engines will treat them as normal redirects.
  • 301 Moved Permanently: Cached by client, the method may or may not be changed to GET.

We recommend using status code 307 or 308 to avoid the ambiguity of non GET methods, which is necessary when your application needs to redirect a public API.

If you are exceeding the limits below, we recommend using Edge Middleware and Edge Config to dynamically read redirect values.

LimitMaximum
Number of redirects in the array1,024
String length for source and destination4,096

There are some best practices to keep in mind when implementing redirects in your application:

  1. Test thoroughly: Test your redirects thoroughly to ensure they work as expected. Use a preview deployment to test redirects before deploying them to production
  2. Use relative paths: Use relative paths in your destination field to avoid hardcoding your domain name
  3. Use permanent redirects: Use permanent redirects for permanent URL changes and temporary redirects for temporary changes
  4. Use wildcards carefully: Wildcards can be powerful but should be used with caution. For example, if you use a wildcard in a source rule that matches any URL path, you could inadvertently redirect all incoming requests to a single destination, effectively breaking your site.
  5. Prioritize HTTPS: Use redirects to enforce HTTPS for all requests to your domain
Last updated on April 16, 2024