Skip to content
orbitpush

Redirects

Redirect paths and hosts with Netlify-style rules in orbitpush.json.

redirects in orbitpush.json takes the shape of [[redirects]] in Netlify’s netlify.toml, written as JSON. Each redirect becomes one bunny.net edge rule, and the first matching redirect wins.

"redirects": [
  { "from": "/old", "to": "/new" },
  { "from": "/blog/:year/:id", "to": "/posts/:year/:id", "status": 302 },
  { "from": "/docs/*", "to": "https://docs.example.com/:splat", "status": 302 },
  { "from": "/", "to": "/uk", "status": 302, "conditions": { "Country": ["gb", "ie"] } },
  { "from": "https://example.com/*", "to": "https://www.example.com/:splat", "force": true }
]

Fields

Field Notes
from Path, or a full URL to match one host
to Path or URL. A relative target (/new) redirects on the requested hostname
status Optional, default 301
force Optional. Accepted, and every redirect behaves as forced
query Optional. Not supported: the redirect is skipped with a warning
conditions Optional. Only Country is supported

Patterns

  • Splats: * at the end of from matches the rest of the path, and :splat in to inserts it. /docs/* to /guide/:splat sends /docs/a/b to /guide/a/b.
  • Placeholders: :name matches one whole path segment and can be used in to. /blog/:year/:id to /posts/:year/:id.
  • Hosts: a full URL in from, such as https://blog.example.com/*, matches that host only. One rule matches both http and https.
  • Trailing slash: a rule matches with and without it.

Unsupported entries

An unsupported entry prints a warning, such as redirects.3 skipped (...), and is skipped. It does not fail the deploy. An entry with a missing field, a field of the wrong type or an unknown key makes orbitpush.json invalid.

Compared with Netlify

Compared with Netlify’s redirect options, section by section:

Netlify feature orbitpush Notes
Status 301 (default) and 302 ✅
Status 303, 307, 308 ⚠️ bunny.net serves only 301 and 302: 303 and 307 are sent as 302, 308 as 301, with a warning
Status 404 for a path ❌ Skipped with a warning
Status 200 rewrites and proxies ❌ A storage zone can’t serve another path. Only /* to /index.html with 200 works, as SPA mode
Custom 404.html ✅ See 404 page
404 pages per path (/en/* to /en/404.html with 404) ❌ Only the global 404 page
force ✅ Accepted, and every redirect behaves as forced
Shadowing: a redirect without force only applies if no file exists ❌ Edge rules run before the storage zone is asked
Splats: * at the end, :splat in the target ✅ * in the middle of a path or inside a segment (/a/*/b, /file-*.js) is skipped, as on Netlify
Rule order: the first matching redirect wins ✅
Placeholders (:name) ✅ As whole segments only: /a-:id is skipped
Query parameter matching (query) ❌ Skipped with a warning
Query string passed on to the target ⚠️ Only when the target ends in :splat or a placeholder: /docs/a?x=1 goes to …/a?x=1, but /old?x=1 goes to /new
Trailing slash: a rule matches with and without it ✅
Pretty URLs: /about redirects to /about/ ✅ trailingSlash always, the default
Pretty URLs: /about.html is served at /about/ ❌ A storage zone can’t serve another path
Domain-level redirects (https://blog.example.com/*) ✅ One rule matches both http and https
Proxy to another host, headers and signed on a proxy ❌ headers and signed make orbitpush.json invalid
Country condition ✅ Two-letter codes. Every 5 countries take one edge rule, because a bunny.net rule matches at most 5
Language condition ❌ Skipped with a warning
Role condition ❌ Needs Netlify Identity
Cookie condition ❌ Skipped with a warning
A _redirects file ❌ Not read or uploaded; deploy warns. Copy its rules with migrate-netlify

_redirects files

A _redirects file in the root of the output directory is neither read nor uploaded, so a site can keep it for Netlify. deploy warns about it, and until orbitpush.json has rules it suggests orbitpush migrate-netlify.

Each redirect uses one of the pull zone’s edge rules. See the 50-rule limit.