Configuring redirects and rewrites
Configuring redirects and rewrites
Orbit has a built-in redirect and rewrite engine configured directly in KPanel. You do not need a vercel.json, netlify.toml, or _redirects file. Rules are set per environment and take effect from the next deployment.
Where to configure rules
Go to Orbit -> [your project] -> Settings and scroll down to the [Environment name] redirects and rewrites section. If your project has both a production and staging environment, each environment has its own rules section.
Adding a rule
- Click Add rule
- Fill in the source path - the URL pattern to match incoming requests against
- Fill in the destination - where to send the request
- Choose the rule type:
- 301 Permanent - tells browsers and search engines the URL has permanently moved. Browsers cache this.
- 302 Temporary - moves the URL for now but does not cache. Use for temporary campaigns or A/B tests.
- Rewrite - serves the destination path without changing the URL visible in the browser
- Click Save rules
Rules take effect on the next deployment. They do not apply retroactively to the currently-live deployment.
Source path patterns
The source field supports several pattern syntaxes:
| Pattern | What it matches |
|---|---|
/old-page | Exact path /old-page only |
/blog/* | Any path starting with /blog/, one level deep |
/posts/:id | Any path matching /posts/ followed by a single segment, captures :id |
/files/:rest* | Any path starting with /files/, captures everything after as :rest |
Rules are evaluated in order. The first matching rule wins. If no rule matches, the request is served normally.
Using captures in the destination
Named parameters from the source pattern can be referenced in the destination:
- Source:
/blog/:slug - Destination:
/articles/:slug
This rewrites /blog/hello-world to /articles/hello-world.
Common use cases
Renaming a page
You renamed /about-us to /about and want old links to still work:
- Source:
/about-us - Destination:
/about - Type: 301 Permanent
Redirecting an old blog path
Your blog moved from /news/:slug to /blog/:slug:
- Source:
/news/:slug - Destination:
/blog/:slug - Type: 301 Permanent
Proxying an API path (rewrite)
You want requests to /api/v1/* to be served from a different internal path without exposing the change in the URL:
- Source:
/api/v1/:path* - Destination:
/api/internal/:path* - Type: Rewrite
Temporary redirect during maintenance
You want /checkout to redirect to a holding page temporarily:
- Source:
/checkout - Destination:
/maintenance - Type: 302 Temporary
Deleting a rule
Click the trash icon on the right side of any rule row to remove it, then click Save rules to apply the change.
Notes and limitations
- Rules apply to the path portion of the URL only. Query strings and fragments are passed through unchanged.
- Rules are applied before Orbit serves the static files or passes the request to your server process. This means a rewrite to a path that does not exist in your build will result in a 404 rather than the rewrite silently failing.
- There is no wildcard-to-external-domain redirect (for example, redirecting all traffic to a different domain). For full-domain redirects, use the custom domain settings instead.
- Each environment has its own independent set of rules. Rules you configure for production do not automatically apply to staging.