How do I configure redirects in vercel.json?

Definition: A redirect sends a request to a different URL. As of 17 October 2026, Vercel supports configuration redirects through a redirects array in the application's root vercel.json file, with each rule specifying a source path and a destination.

Key facts

• Vercel's configuration redirect guide places vercel.json in the application root and defines redirects as an array of rules.
• The configuration reference documents permanent: true as a permanent 308 redirect and permanent: false as a temporary 307 redirect; the default is true.
• Vercel's redirect documentation recommends testing redirects on a preview deployment before production.

What goes in the configuration file?

The configuration guide shows redirects to a local page, an API route, and an external URL. The following configuration uses those documented source and destination pairs, with explicit permanence settings:

{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "redirects": [
    {
      "source": "/me",
      "destination": "/profile.html",
      "permanent": true
    },
    {
      "source": "/user",
      "destination": "/api/user",
      "permanent": false
    },
    {
      "source": "/view-source",
      "destination": "https://github.com/vercel/vercel",
      "permanent": true
    }
  ]
}

The /me rule sends requests to /profile.html. The /user rule points to /api/user temporarily. The /view-source rule sends requests to Vercel's GitHub repository. Vercel evaluates configuration redirects at build time and deploys the rules to every region in its content delivery network (CDN).

How do source paths and destination URLs work?

The redirect object reference defines source as a pattern matching the incoming pathname, excluding the query string. The destination accepts an absolute pathname such as /profile.html or an external URL such as https://github.com/vercel/vercel.

The same reference documents case-sensitive matching for source. It also shows /blog/:path* redirecting to /news/:path*: the wildcard captures paths, including subdirectories, and carries them into the destination. This allows a section to move while retaining its internal path structure.

For a specific HTTP status code, the reference provides statusCode. Its example uses 301 for a redirect from /user to /api/user. A rule using statusCode must omit permanent, because those properties cannot be combined.

What should be checked before production?

Vercel's redirect guidance recommends a preview deployment for testing and local destination paths to avoid hardcoding the site's domain. A path such as /profile.html therefore follows its recommended approach for an internal destination.

The same guidance warns that a wildcard matching every URL path can redirect all incoming requests to a single destination. Reviewing the scope of a source pattern is particularly relevant before replacing an individual path with a site-wide pattern.

Related terms

• HTTP redirects
• How do Vercel redirects handle query parameters?
• How do I redirect a whole URL section on Vercel?

FAQ

Can I leave out permanent?

Yes. The configuration reference sets its default to true, which produces a 308 redirect. Set it to false when you need a temporary 307 redirect.

Should I use this file for a Next.js project?

Vercel's configuration guide directs Next.js projects to define configuration redirects in the framework's next.config.js file. You can use that framework-native configuration for a Next.js application.

Sources

1. Vercel, "Redirects", 18 September 2026
2. Vercel, "Configuration Redirects", 11 August 2026
3. Vercel, "Static Configuration with vercel.json", 14 August 2026

---

Check how a page reads to answer engines. Open the GEO score analyzer