Project-Level Routing Rules
Project-level routing rules let you add redirects, rewrites, response headers, and other routing logic from the dashboard, API, or CLI, without deploying new code. Changes take effect immediately after publishing.
These rules are separate from deployment-level routes defined in vercel.json or your framework configuration. They run at the CDN level on every request, after bulk redirects and before your deployment's own routes. See the routing order for the full sequence.
- Open your project in the Vercel dashboard.
- Navigate to CDN > Routing Rules.
- Select Add Rule.
- Enter a name and optional description for the rule.
- Define the match conditions that determine which requests the rule applies to.
- Choose one or more actions to apply when a request matches.
- Select Save to add the rule to your staging configuration.
The rule appears in your staging list. To apply it to production, select Publish.
Each rule requires a path condition and supports additional conditions to narrow the match.
Every rule matches against the request path. You can choose from three syntax modes:
| Mode | Description | Example |
|---|---|---|
| Exact match | Matches a specific path | /blog |
| Path pattern | Express-style :param syntax with wildcards | /blog/:slug, /api/:path* |
| Regex | Full regular expression | ^/posts/[0-9]+$ |
You can add conditions to match on other parts of the request. Each condition specifies a field, an operator, and a value.
| Field | Description | Example use case |
|---|---|---|
| Host | The request hostname | Route differently for app.example.com vs www.example.com |
| Header | A request header key and value | Match requests with a specific Accept-Language |
| Cookie | A cookie key and value | Target users with a specific session or feature flag cookie |
| Query | A query parameter key and value | Match requests with ?preview=true |
Each condition supports these operators:
| Operator | Description |
|---|---|
| Equals | Exact string match |
| Contains | Substring match |
| Matches regex | Regular expression match |
| Exists | Field is present (value isn't checked) |
You can also negate any condition to match when the field is missing or doesn't match.
When a request matches a rule, one or more actions run. Actions fall into two groups: primary actions (mutually exclusive) and modify actions (combinable).
You can use one primary action per rule.
| Action | Description | Configuration |
|---|---|---|
| Rewrite | Forwards the request to a different URL. The visitor's browser still shows the original URL. | A destination URL. Can be internal (/new-path) or external (https://api.example.com/:path*). |
| Redirect | Sends the visitor's browser to a different URL with an HTTP status code. | A destination URL and a status code: 301 (permanent), 302 (found), 307 (temporary), or 308 (permanent). |
| Set status code | Returns a specific HTTP status code without changing the URL. | An HTTP status code (e.g., 404, 503). |
You can combine multiple modify actions with each other, or pair one with a primary action.
| Action | Description | Operations |
|---|---|---|
| Modify response headers | Adds, changes, or removes response headers. | Set: replace or add a header. Append: add a value to an existing header. Delete: remove a header. |
| Modify request headers | Adds, changes, or removes headers on the incoming request before it reaches your application. | Set, Append, Delete |
| Modify request query | Adds, changes, or removes query parameters on the incoming request. | Set, Append, Delete |
Routing rules use a staging workflow so you can review changes before they affect production traffic.
- Stage: When you create or edit a rule, it's saved to a staging version. Staging changes are visible in the dashboard but don't affect production.
- Test: Use the Test Rules feature to verify that a specific URL matches the expected rule and produces the correct action.
- Publish: Select Publish to promote your staging changes to production. Changes take effect immediately across all regions.
If a published change causes issues, you can roll back to a previous version from the History tab.
Rules execute in the order they appear in the list. You can drag and drop rules to change their priority. When a request matches multiple rules, the first matching rule with a primary action (rewrite, redirect, or set status) wins. Modify actions from all matching rules still apply.
You can also create, read, update, and delete routing rules through the Vercel REST API. Use the API to automate rule management in CI/CD pipelines or manage rules through infrastructure-as-code tools like Terraform.
Project-level routing rules support the same core actions as vercel.json routes: rewrites, redirects, status codes, and header modifications. The main difference is that project-level rules run at the CDN without access to your deployment's code, so Routing Middleware isn't available. If your routing logic requires custom code (for example, authentication checks or A/B test assignments), use Routing Middleware in your deployment instead.
A few other vercel.json fields are also deployment-only: locale for i18n routing, and the internal fields handle, check, continue, and mitigate.
Was this helpful?