How can Vercel redirect only requests for a particular hostname?

Definition: Add a has condition with "type": "host" to a Vercel configuration redirect. The condition limits the rule to the hostname in value, while source and destination control the request path and redirect target.

Key facts

• Vercel defines redirects as rules that send users to a different URL from the one they requested. Vercel's redirects documentation places configuration redirects in framework configuration or vercel.json.
• A redirect's source matches each incoming pathname, excluding the query string, according to Vercel's vercel.json reference.
• The has property is an optional array for conditional redirects. Its type can be header, cookie, host, or query.
• Vercel's hostname example uses "your-project\\.vercel\\.app" as the host value, sends the matched path to https://www.example.com/:path*, and sets "permanent": true.
• Vercel documents that the hostname-scoped example preserves the path and passes query parameters through unless the destination replaces them.

How does the hostname condition work?

The redirect object has two separate matching layers. The source pattern selects the pathname, and the has array adds a request property condition. For a hostname condition, the reference allows host as the type; the value is the value to check. Vercel also documents regex-like strings for value, including capture syntax, so the escaped dots in the hostname example are part of the configured match.

The documented example uses a catch-all path and a host value:

{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "redirects": [
    {
      "source": "/:path*",
      "has": [{ "type": "host", "value": "your-project\\.vercel\\.app" }],
      "destination": "https://www.example.com/:path*",
      "permanent": true
    }
  ]
}

What does this redirect preserve?

Vercel's hostname redirect example uses /:path* in both the source and destination. The matched path therefore appears after the destination hostname. The same example states that query parameters pass through unless the destination explicitly replaces them.

The exact host value matters for scope. Vercel says that matching the source hostname avoids redirecting the destination back to itself or redirecting every preview URL. Replace both example hostnames with the production host and destination used by the project.

The permanent property controls the documented default redirect behavior. Vercel's configuration reference says true produces status code 308, while false produces 307. A statusCode integer is available when a value other than 307 or 308 is needed, and it cannot be used with the permanent boolean.

How can the rule be checked?

Vercel recommends checking a nested path and query string on both domains and confirming that preview URLs still work. The documented command shape is:

curl -I 'https://your-project.vercel.app/about?ref=test'
curl -I 'https://www.example.com/about?ref=test'

For the permanent example, Vercel says to expect 308 and a Location value pointing to https://www.example.com/about?ref=test. The configuration reference adds one deployment detail: has does not work locally with vercel dev, but it works when deployed.

Related terms

• How do I configure redirects in vercel.json?
• How do Vercel redirects handle query parameters?
• How do I redirect a whole URL section on Vercel?
• HTTP redirects

FAQ

Does the host condition replace the path condition?

No. The has object adds a host check to the source pathname pattern. Keep source for the paths that the redirect should handle.

Will a path and query string reach the destination?

Yes, for the documented pattern. The /:path* capture carries the path to the destination, and query parameters pass through unless the destination replaces them.

Can you test this with vercel dev?

The reference says has works when deployed and does not work locally with vercel dev. Use a deployed environment for this check.

Sources

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

---

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