Skip to content
orbitpush

orbitpush.json

Every field of the configuration file that describes your site.

orbitpush init (or the first deploy) writes orbitpush.json in your project. Commit it: every deploy reads it, and it never contains the API key.

{
  "$schema": "https://unpkg.com/orbitpush/schema.json",
  "name": "my-site",
  "outputDir": "dist",
  "domain": "www.example.com",
  "aliases": ["example.com"],
  "region": "DE",
  "replicationRegions": ["NY"],
  "geoZones": ["EU", "US"],
  "pullZoneId": 654321
}

The $schema line gives editors such as VS Code autocompletion and inline descriptions for every field.

Settings are applied on every deploy, so you can change them later. A key not listed here, such as a misspelled field, makes orbitpush.json invalid, and the command stops with an error.

Fields

Field Required Notes
name Yes Name of the storage zone and pull zone, set by init. Letters, numbers and dashes.
outputDir Yes Directory that gets deployed.
domain No Primary domain, a hostname such as www.example.com, added with SSL. Set by domains add.
aliases No Hostnames added with SSL that 301-redirect every path and query to domain. Need a domain, each listed once, at most 8.
region Yes Main storage region: DE, UK, SE, NY, LA, SG, SYD, BR or JH. Fixed after init.
replicationRegions Yes Extra storage regions, same values as region. Can only be added: bunny.net does not support removing replication regions.
geoZones Yes CDN delivery regions: EU, US, ASIA, SA, AF. At least one.
redirects No See Redirects and SPA mode.
headers No See Headers.
trailingSlash No always, never or ignore. See Trailing slashes.
pullZoneId Yes ID of the pull zone, set by init. orbitpush finds the storage zone through it.

Older files may contain storageZoneId. It is no longer used and is ignored.

Domains

Change domains with orbitpush domains. It updates domain and aliases in orbitpush.json and the pull zone together. Editing the file and running deploy also works, with one exception: removing a hostname from the file does not remove it from bunny.net. It keeps serving the site without a redirect, and deploy warns about it. Use orbitpush domains remove instead.

Regions

region is where your files are stored, and replicationRegions keeps extra copies closer to visitors in other parts of the world. geoZones decides which bunny.net delivery regions serve your site. See bunny.net limits for the full list and what can change later.

A full example

{
  "$schema": "https://unpkg.com/orbitpush/schema.json",
  "name": "my-site",
  "outputDir": "dist",
  "domain": "www.example.com",
  "aliases": ["example.com"],
  "region": "DE",
  "replicationRegions": [],
  "geoZones": ["EU", "US"],
  "trailingSlash": "always",
  "redirects": [
    { "from": "/old", "to": "/new" },
    {
      "from": "/docs/*",
      "to": "https://docs.example.com/:splat",
      "status": 302
    }
  ],
  "headers": [
    { "for": "/*", "values": { "X-Frame-Options": "DENY" } },
    {
      "for": "/assets/*",
      "values": { "Cache-Control": "public, max-age=31536000, immutable" }
    }
  ],
  "pullZoneId": 654321
}