orbitpush 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +320 -2
- package/dist/cli.js +175 -0
- package/package.json +62 -4
- package/schema.json +135 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Lars Graubner
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,321 @@
|
|
|
1
|
-
#
|
|
1
|
+
# orbitpush
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Deploy a static site or SPA to **your own** [bunny.net](https://bunny.net) account: a storage zone with a pull zone in front. No server, no platform, bring your own key.
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
export BUNNY_API_KEY=... # https://dash.bunny.net/account/api-key
|
|
7
|
+
npm run build
|
|
8
|
+
npx orbitpush deploy # first run: sets up the site, then deploys
|
|
9
|
+
npx orbitpush domains add www.example.com # optional: your own domain
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
`orbitpush disable`, `orbitpush enable` and `orbitpush destroy` take a site offline, bring it back, or delete it from bunny.net (see below).
|
|
13
|
+
|
|
14
|
+
## `orbitpush init`
|
|
15
|
+
|
|
16
|
+
Sets up a site without deploying it. In a terminal you rarely need it: the first `deploy` asks the same questions. It asks for the project name, build output directory, the main storage region, replication regions and CDN delivery regions. Then it creates:
|
|
17
|
+
|
|
18
|
+
1. a storage zone (name = project name),
|
|
19
|
+
2. a pull zone with the storage zone as its origin (available at `https://<name>.b-cdn.net`),
|
|
20
|
+
3. with `--domain` and `--alias`, those hostnames on the pull zone, and prints the DNS record for each.
|
|
21
|
+
|
|
22
|
+
Domains are not asked for: add them with [`orbitpush domains add`](#orbitpush-domains), which waits for DNS and turns on HTTPS. For a domain given to `init`, run `domains add` for it once its DNS record is set.
|
|
23
|
+
|
|
24
|
+
Each prompt can be skipped with a flag; an option no command knows stops with an error. Without a terminal, `init` needs `--name` and `--dir`, or `--yes` to take the defaults:
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
npx orbitpush init --name my-site --dir dist --domain www.example.com --alias example.com --region DE --delivery-region EU --delivery-region US --yes
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
The pull zone and storage zone names are global across bunny.net. If the name is taken, choose another one.
|
|
31
|
+
|
|
32
|
+
If `init` fails before `orbitpush.json` is written, it deletes the zones it just created, so you can run it again with the same name. If that cleanup fails too, `init` names the zone to delete in the dashboard. Failures after that point, such as a missing SSL certificate, are fixed by the next deploy.
|
|
33
|
+
|
|
34
|
+
## `orbitpush deploy`
|
|
35
|
+
|
|
36
|
+
In a terminal, `deploy` without an `orbitpush.json` asks whether to set up a new site, asks the `init` questions, and deploys right after. The output directory must exist, so build first. Without a terminal it stops with an error instead, so CI never creates a site.
|
|
37
|
+
|
|
38
|
+
1. Reads `orbitpush.json` and `BUNNY_API_KEY`.
|
|
39
|
+
2. Compares the output directory with the storage zone using SHA256 checksums and uploads only changed files, HTML files last. A symlinked file is uploaded with the content it points to; a symlinked directory or a broken symlink is skipped with a warning.
|
|
40
|
+
3. Applies the settings: [SPA mode](#spa-mode) or the [404 page](#404-page) from the output directory, and replication regions, delivery regions and domains from `orbitpush.json`.
|
|
41
|
+
4. Turns `redirects` and `headers` into edge rules (see below).
|
|
42
|
+
5. Deletes files from the storage zone that have not been in the build for 7 days, so an installed PWA or an open page still running the previous version can load its old assets. The date each file left the build is kept in `/.orbitpush/stale.json` in the storage zone, which the pull zone serves publicly like every other file there. It lists only paths the site served before. If you delete it, the next deploy treats every stale file as stale since then. `.orbitpush/` in the storage zone belongs to orbitpush, so `deploy` skips files under `.orbitpush/` in the output directory with a warning.
|
|
43
|
+
6. Purges the pull zone cache.
|
|
44
|
+
|
|
45
|
+
bunny.net applies edge rule changes one by one, a few seconds after `deploy` finishes (2–6 s in our tests).
|
|
46
|
+
|
|
47
|
+
A hostname on the pull zone that `orbitpush.json` does not list, such as a removed alias or a former `domain`, keeps serving the site without a redirect, and `deploy` warns about it. `orbitpush domains remove <host>` removes one; `orbitpush deploy --prune-hostnames` removes every such hostname except `<name>.b-cdn.net`, with its certificate, including hostnames added in the dashboard. A former primary domain usually belongs in `aliases` instead, so that its links redirect to the new one: `orbitpush domains add <host>`.
|
|
48
|
+
|
|
49
|
+
In CI, set `BUNNY_API_KEY` as a secret:
|
|
50
|
+
|
|
51
|
+
```yaml
|
|
52
|
+
- run: npx orbitpush deploy
|
|
53
|
+
env:
|
|
54
|
+
BUNNY_API_KEY: ${{ secrets.BUNNY_API_KEY }}
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
## `orbitpush domains`
|
|
58
|
+
|
|
59
|
+
Puts the site on your own domains. Each command updates `domain` and `aliases` in `orbitpush.json` and the pull zone together, so editing the file and running `deploy` stays an alternative.
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
npx orbitpush domains add www.example.com # the first domain becomes the primary domain
|
|
63
|
+
npx orbitpush domains add example.com # later ones are aliases that redirect to it
|
|
64
|
+
npx orbitpush domains add example.com --primary # make an alias the primary domain
|
|
65
|
+
npx orbitpush domains remove example.com
|
|
66
|
+
npx orbitpush domains list
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
`domains add` adds the hostname to the pull zone, prints the DNS record to create, and waits until the record points to bunny.net: it checks again 10 seconds after each check, for up to 15 minutes. Then it gets a free SSL certificate, turns on HTTPS and writes the alias redirects. If DNS takes longer, or you stop it with Ctrl+C, run the same command again later: it continues where it stopped. Without a terminal it checks once and exits with status `1` while the domain is not connected.
|
|
70
|
+
|
|
71
|
+
With `--primary`, the domain becomes the primary domain only once it is connected, and the former primary domain becomes an alias that redirects to it. Until then it stays an alias, so visitors are never sent to a domain without HTTPS.
|
|
72
|
+
|
|
73
|
+
`domains remove` removes the hostname from `orbitpush.json` and the pull zone. A primary domain that still has aliases cannot be removed: remove the aliases first, or make another domain primary with `orbitpush domains add <host> --primary`.
|
|
74
|
+
|
|
75
|
+
`domains list` changes nothing. It shows each domain, whether it is connected, and the DNS record it still needs.
|
|
76
|
+
|
|
77
|
+
## Without a terminal (CI, scripts, agents)
|
|
78
|
+
|
|
79
|
+
orbitpush asks nothing when stdin or stderr is not a terminal, or when `CI` is set to anything but `false` or `0`. Every question then has to be answered by a flag, and the API key comes from `BUNNY_API_KEY`:
|
|
80
|
+
|
|
81
|
+
```bash
|
|
82
|
+
export BUNNY_API_KEY=...
|
|
83
|
+
npx orbitpush init --name my-site --dir dist --region DE --delivery-region EU --delivery-region US --yes
|
|
84
|
+
npm run build
|
|
85
|
+
npx orbitpush deploy
|
|
86
|
+
npx orbitpush domains add www.example.com # prints the DNS record, exits 1 until it is set
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
- Commit `orbitpush.json` after `init`. Without a terminal, `deploy` never creates a site; it stops when the file is missing.
|
|
90
|
+
- `init` stops unless it gets `--name` and `--dir`, or `--yes`, so a guessed name never creates zones.
|
|
91
|
+
- `deploy`, `disable` and `enable` take no input. `destroy` needs `--yes`.
|
|
92
|
+
- `domains add` checks DNS once instead of waiting and exits `1` while the domain is not connected; run it again a few minutes later. `domains list` exits `1` while any domain is not connected, so a script can poll it.
|
|
93
|
+
- Errors go to stderr with exit code `1`, an unknown command exits with `2`, and an unknown option stops with `1`, so a typo never falls back to a default.
|
|
94
|
+
- Some coding agents run commands in a pseudo-terminal, where orbitpush would ask its questions and wait. Set `CI=1` for them: then nothing asks, and `domains add` checks once instead of waiting up to 15 minutes.
|
|
95
|
+
|
|
96
|
+
## `orbitpush.json`
|
|
97
|
+
|
|
98
|
+
Commit this file. It never contains the API key.
|
|
99
|
+
|
|
100
|
+
```json
|
|
101
|
+
{
|
|
102
|
+
"$schema": "https://unpkg.com/orbitpush/schema.json",
|
|
103
|
+
"name": "my-site",
|
|
104
|
+
"outputDir": "dist",
|
|
105
|
+
"domain": "www.example.com",
|
|
106
|
+
"aliases": ["example.com"],
|
|
107
|
+
"region": "DE",
|
|
108
|
+
"replicationRegions": ["NY"],
|
|
109
|
+
"geoZones": ["EU", "US"],
|
|
110
|
+
"pullZoneId": 654321
|
|
111
|
+
}
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
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:
|
|
115
|
+
|
|
116
|
+
| Field | Notes |
|
|
117
|
+
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
118
|
+
| `outputDir` | Directory that gets deployed. |
|
|
119
|
+
| `domain` | Optional. Primary domain, a hostname such as `www.example.com`, added with SSL. Set by `orbitpush domains add`; change it with `orbitpush domains add <host> --primary`. Removing it here does **not** remove it from bunny.net; `deploy` warns about it. Use `orbitpush domains remove` instead. |
|
|
120
|
+
| `aliases` | Optional. Hostnames added with SSL that 301-redirect every path and query to `domain`. Need a `domain`, and each is listed once. At most 8: bunny.net allows 10 hostnames per pull zone, `<name>.b-cdn.net` and `domain` included. Removing one leaves it on the pull zone, serving the site without a redirect; `deploy` warns about it, and `orbitpush domains remove` removes it |
|
|
121
|
+
| `region` | Main storage region. Fixed after `init`. |
|
|
122
|
+
| `replicationRegions` | Can only be added. bunny.net does not support removing replication regions. |
|
|
123
|
+
| `geoZones` | CDN delivery regions: `EU`, `US`, `ASIA`, `SA`, `AF`. At least one. |
|
|
124
|
+
| `redirects` | Optional. See [Redirects and headers](#redirects-and-headers). |
|
|
125
|
+
| `headers` | Optional. See [Redirects and headers](#redirects-and-headers). |
|
|
126
|
+
| `trailingSlash` | Optional. `always`, `never` or `ignore`, see [Trailing slashes](#trailing-slashes). |
|
|
127
|
+
|
|
128
|
+
### Domains and search engines
|
|
129
|
+
|
|
130
|
+
Each hostname in `aliases` redirects to `domain` with status `301`, keeping the path and query string, so `https://example.com/a?b=1` goes to `https://www.example.com/a?b=1`. An alias needs the same DNS record as a domain. To make an alias the primary domain, run `orbitpush domains add <alias> --primary` (see [`orbitpush domains`](#orbitpush-domains)); swapping the two in `orbitpush.json` and deploying does the same. Either way, the old alias redirect is deleted before the new one is added, so the two never redirect in a loop. Aliases redirect only once `domain` has an SSL certificate: until then they serve the site themselves, so a swap to a domain whose DNS is not set yet never sends visitors to a hostname without HTTPS.
|
|
131
|
+
|
|
132
|
+
While `domain` is set, responses on `<name>.b-cdn.net` carry `X-Robots-Tag: noindex`, so search engines index the primary domain instead.
|
|
133
|
+
|
|
134
|
+
Both are edge rules that orbitpush manages, like the ones from the rule files below.
|
|
135
|
+
|
|
136
|
+
## `orbitpush migrate-netlify`
|
|
137
|
+
|
|
138
|
+
Copies the redirects and headers of a Netlify site into `orbitpush.json`. Run it after `init`, in the directory with `orbitpush.json`:
|
|
139
|
+
|
|
140
|
+
1. Reads `netlify.toml` from the current directory and `_redirects` and `_headers` from the output directory. If your build copies those files into it, build first.
|
|
141
|
+
2. Writes them to `redirects` and `headers` in `orbitpush.json`: `_redirects` first, then the `[[redirects]]` of `netlify.toml`, the order Netlify applies them in. Headers keep the same order, `_headers` first, so `netlify.toml` wins when both set a header for a URL; Netlify does not document this order.
|
|
142
|
+
3. Warns about every rule that `deploy` will skip because bunny.net can't serve it, such as rewrites or `Language` conditions. These rules are still written, so the file stays a complete copy.
|
|
143
|
+
|
|
144
|
+
It does not copy `Basic-Auth` headers, which hold passwords, or redirects without `to`. It stops without writing when `orbitpush.json` already has redirects or headers, and it never changes or deletes the Netlify files, so the site keeps working on Netlify. Everything else in `netlify.toml`, such as the build command or functions, is ignored. It rewrites `orbitpush.json` in the format `init` writes, so fields left out before, such as an empty `aliases`, appear with their defaults.
|
|
145
|
+
|
|
146
|
+
## `orbitpush disable` and `orbitpush enable`
|
|
147
|
+
|
|
148
|
+
`disable` adds an edge rule named `orbitpush disabled` that blocks every request to the pull zone, then purges the cache. Visitors get bunny.net's `403` page on every hostname. Files, settings and domains stay as they are, and `deploy` keeps working but leaves the block in place and warns about it. `enable` removes the rule and purges the cache again. Both do nothing when the site is already in that state.
|
|
149
|
+
|
|
150
|
+
## `orbitpush destroy`
|
|
151
|
+
|
|
152
|
+
Deletes the storage zone that the pull zone serves, with every file in it, then the pull zone (with its hostnames and certificates), then `orbitpush.json`. It asks you to type the project name first; `--yes` skips that and is required without a terminal. A zone that is already gone counts as deleted, so if `destroy` stops halfway, run it again. `destroy` finds the storage zone through the pull zone, so when the pull zone is already gone, it warns you to check the dashboard for a storage zone with the project name. DNS records you created for your domains are not managed by orbitpush; remove them at your DNS provider.
|
|
153
|
+
|
|
154
|
+
## Redirects and headers
|
|
155
|
+
|
|
156
|
+
`redirects` and `headers` in `orbitpush.json` take the shape of `[[redirects]]` and `[[headers]]` in Netlify's [`netlify.toml`](https://docs.netlify.com/build/configure-builds/file-based-configuration/), written as JSON. Each redirect and each headers entry becomes one edge rule.
|
|
157
|
+
|
|
158
|
+
`_redirects` and `_headers` files in the root of the output directory are neither read nor uploaded, so a site can keep them for Netlify. `deploy` warns about each one, and until `orbitpush.json` has rules it suggests the command below. Copy their rules to `orbitpush.json` with [`orbitpush migrate-netlify`](#orbitpush-migrate-netlify). After that, a change to a file does not reach orbitpush, and a change to `orbitpush.json` does not reach Netlify.
|
|
159
|
+
|
|
160
|
+
Rules created by orbitpush have a description that starts with `orbitpush <hash>`. On deploy, new or changed rules are added, rules that are no longer in `orbitpush.json` are deleted, and every other orbitpush rule is rewritten from `orbitpush.json`, so edits made to it in the dashboard are undone. Edge rules you create yourself in the dashboard are never touched. To take over an orbitpush rule, remove the `orbitpush` prefix from its description; the next deploy then adds a fresh copy unless you also remove the entry from `orbitpush.json`.
|
|
161
|
+
|
|
162
|
+
Unsupported entries print a warning, such as `redirects.3 skipped (...)`, and are skipped. They do not fail the deploy. An entry with a missing field, a field of the wrong type or an unknown key makes `orbitpush.json` invalid.
|
|
163
|
+
|
|
164
|
+
bunny.net allows 50 edge rules per pull zone by default; bunny.net support can raise the limit. Besides one rule per redirect and per headers entry, orbitpush adds one per alias, one for noindex while `domain` is set, one for the [trailing slash](#trailing-slashes) and one while the site is disabled. Rules created in the dashboard count too. bunny.net accepts no change to a full zone, so a deploy can use 49 rules; when it would need more, it fails before uploading anything and says how many rules it needs.
|
|
165
|
+
|
|
166
|
+
### `redirects`
|
|
167
|
+
|
|
168
|
+
```json
|
|
169
|
+
"redirects": [
|
|
170
|
+
{ "from": "/old", "to": "/new" },
|
|
171
|
+
{ "from": "/blog/:year/:id", "to": "/posts/:year/:id", "status": 302 },
|
|
172
|
+
{ "from": "/docs/*", "to": "https://docs.example.com/:splat", "status": 302 },
|
|
173
|
+
{ "from": "/", "to": "/uk", "status": 302, "conditions": { "Country": ["gb", "ie"] } },
|
|
174
|
+
{ "from": "https://example.com/*", "to": "https://www.example.com/:splat", "force": true }
|
|
175
|
+
]
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
| Field | Notes |
|
|
179
|
+
| ------------ | --------------------------------------------------------------------------- |
|
|
180
|
+
| `from` | Path, or a full URL to match one host |
|
|
181
|
+
| `to` | Path or URL. A relative target (`/new`) redirects on the requested hostname |
|
|
182
|
+
| `status` | Optional, default `301` |
|
|
183
|
+
| `force` | Optional. Accepted, and every redirect behaves as forced |
|
|
184
|
+
| `query` | Optional. Not supported: the redirect is skipped with a warning |
|
|
185
|
+
| `conditions` | Optional. Only `Country` is supported |
|
|
186
|
+
|
|
187
|
+
Compared with Netlify's [redirect options](https://docs.netlify.com/manage/routing/redirects/redirect-options/), section by section:
|
|
188
|
+
|
|
189
|
+
| Netlify feature | orbitpush | Notes |
|
|
190
|
+
| -------------------------------------------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------- |
|
|
191
|
+
| Status `301` (default) and `302` | ✅ | |
|
|
192
|
+
| Status `303`, `307`, `308` | ⚠️ | bunny.net serves only `301` and `302`: `303` and `307` are sent as `302`, `308` as `301`, with a warning |
|
|
193
|
+
| Status `404` for a path | ❌ | Skipped with a warning |
|
|
194
|
+
| Status `200` rewrites and proxies | ❌ | A storage zone can't serve another path. Only `/*` to `/index.html` with `200` works, as [SPA mode](#spa-mode) |
|
|
195
|
+
| Custom `404.html` | ✅ | See [404 page](#404-page) |
|
|
196
|
+
| 404 pages per path (`/en/*` to `/en/404.html` with `404`) | ❌ | Only the global 404 page |
|
|
197
|
+
| `force` | ✅ | Accepted, and every redirect behaves as forced |
|
|
198
|
+
| Shadowing: a redirect without `force` only applies if no file exists | ❌ | Edge rules run before the storage zone is asked |
|
|
199
|
+
| 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 |
|
|
200
|
+
| Rule order: the first matching redirect wins | ✅ | |
|
|
201
|
+
| Placeholders (`:name`) | ✅ | As whole segments only: `/a-:id` is skipped |
|
|
202
|
+
| Query parameter matching (`query`) | ❌ | Skipped with a warning |
|
|
203
|
+
| 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` |
|
|
204
|
+
| Trailing slash: a rule matches with and without it | ✅ | |
|
|
205
|
+
| Pretty URLs: `/about` redirects to `/about/` | ✅ | [`trailingSlash`](#trailing-slashes) `always`, the default |
|
|
206
|
+
| Pretty URLs: `/about.html` is served at `/about/` | ❌ | A storage zone can't serve another path |
|
|
207
|
+
| Domain-level redirects (`https://blog.example.com/*`) | ✅ | One rule matches both `http` and `https` |
|
|
208
|
+
| Proxy to another host, `headers` and `signed` on a proxy | ❌ | `headers` and `signed` make `orbitpush.json` invalid |
|
|
209
|
+
| `Country` condition | ✅ | Two-letter codes. Every 5 countries take one edge rule, because a bunny.net rule matches at most 5 |
|
|
210
|
+
| `Language` condition | ❌ | Skipped with a warning |
|
|
211
|
+
| `Role` condition | ❌ | Needs Netlify Identity |
|
|
212
|
+
| `Cookie` condition | ❌ | Skipped with a warning |
|
|
213
|
+
| A `_redirects` file | ❌ | Not read or uploaded; deploy warns, see above |
|
|
214
|
+
|
|
215
|
+
### SPA mode
|
|
216
|
+
|
|
217
|
+
The redirect `{ "from": "/*", "to": "/index.html", "status": 200 }` turns on SPA mode: the storage zone serves `index.html` with status `200` for a missing path without a file extension. It is not an edge rule. With `force` or `conditions` it is skipped with a warning.
|
|
218
|
+
|
|
219
|
+
### `headers`
|
|
220
|
+
|
|
221
|
+
```json
|
|
222
|
+
"headers": [
|
|
223
|
+
{ "for": "/*", "values": { "X-Frame-Options": "DENY" } },
|
|
224
|
+
{ "for": "/assets/*", "values": { "Cache-Control": "public, max-age=31536000, immutable" } }
|
|
225
|
+
]
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
Compared with Netlify's [custom headers](https://docs.netlify.com/manage/routing/headers/), section by section:
|
|
229
|
+
|
|
230
|
+
| Netlify feature | orbitpush | Notes |
|
|
231
|
+
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
232
|
+
| `[[headers]]` with `for` and `values` | ✅ | As JSON in `orbitpush.json` |
|
|
233
|
+
| A `_headers` file | ❌ | Not read or uploaded; deploy warns, see above |
|
|
234
|
+
| Header names are case-insensitive | ✅ | `Cache-Control` and `cache-control` in one entry are joined with `, `, sent with the first spelling |
|
|
235
|
+
| `/*` for every path | ✅ | |
|
|
236
|
+
| Wildcards: `*` anywhere in a path, matching any characters | ✅ | `/assets/*.js` also matches `/assets/lib/app.js`, as on Netlify |
|
|
237
|
+
| Placeholders: `:name` as a whole segment | ✅ | |
|
|
238
|
+
| A wildcard and a placeholder in one segment (`/t/:name*`) | ❌ | Skipped with a warning; Netlify doesn't support it either |
|
|
239
|
+
| Multi-value headers | ✅ | Write the values in one string, separated by `, ` |
|
|
240
|
+
| Most response headers, such as `Content-Type`, `Cache-Control` or `Content-Security-Policy` | ✅ | |
|
|
241
|
+
| `Set-Cookie` | ✅ | Served as written |
|
|
242
|
+
| Headers Netlify ignores: `Accept-Ranges`, `Age`, `Allow`, `Alt-Svc`, `Connection`, `Content-Encoding`, `Content-Length`, `Content-Range`, `Date`, `Location`, `Server`, `Trailer`, `Transfer-Encoding`, `Upgrade` | ✅ | Skipped with a warning, as are names starting with `CDN-`. bunny.net rejects several of them, which would fail the deploy |
|
|
243
|
+
| Headers on proxied URLs and functions | – | orbitpush has no proxies or functions |
|
|
244
|
+
| Headers per branch or deploy context | – | orbitpush has no deploy contexts |
|
|
245
|
+
| Cookies across subdomains only on your own domain | ⚠️ | `b-cdn.net` is not on the [Public Suffix List](https://publicsuffix.org/), so other sites on `b-cdn.net` can set cookies for `<name>.b-cdn.net`. Use your own domain for anything that relies on cookies |
|
|
246
|
+
| Basic authentication (`Basic-Auth`) | ❌ | Skipped with a warning, so the password is never sent as a header |
|
|
247
|
+
|
|
248
|
+
Not on Netlify's page:
|
|
249
|
+
|
|
250
|
+
- If several entries set the same header for a URL, the last entry wins, as on Netlify
|
|
251
|
+
- Headers also apply to the 404 page, to redirects and to the `index.html` that [SPA mode](#spa-mode) serves
|
|
252
|
+
|
|
253
|
+
### Moving from Netlify or Vercel
|
|
254
|
+
|
|
255
|
+
From Netlify, run [`orbitpush migrate-netlify`](#orbitpush-migrate-netlify). The way back is a copy: each entry in `redirects` and `headers` is one `[[redirects]]` or `[[headers]]` block of `netlify.toml` with the same keys.
|
|
256
|
+
|
|
257
|
+
`vercel.json` uses the same top-level names with different fields, so its entries need rewriting:
|
|
258
|
+
|
|
259
|
+
| `vercel.json` | `orbitpush.json` |
|
|
260
|
+
| ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
|
|
261
|
+
| `redirects[].source`, `destination` | `from`, `to` |
|
|
262
|
+
| `/blog/:path*` to `/news/:path*` | `/blog/*` to `/news/:splat` |
|
|
263
|
+
| `/:slug` (one segment) | `/:slug` |
|
|
264
|
+
| Regex in `source`, such as `/(.*)` or `:id(\\d+)` | Not supported; `/(.*)` is `/*` |
|
|
265
|
+
| `permanent` (default `true`, sends `308`) | `status`, default `301`. `308` is sent as `301`, `307` as `302` |
|
|
266
|
+
| `statusCode` | `status` |
|
|
267
|
+
| `has` / `missing` | Not supported, except a country: `"conditions": { "Country": [...] }` instead of `has` on `x-vercel-ip-country` |
|
|
268
|
+
| `headers[].source`, `headers: [{ key, value }]` | `for`, `values: { key: value }` |
|
|
269
|
+
| `rewrites` to `/index.html` from `/(.*)` | The [SPA mode](#spa-mode) redirect |
|
|
270
|
+
| `trailingSlash: true` / `false` / unset | `trailingSlash: "always"` / `"never"` / `"ignore"` |
|
|
271
|
+
| `cleanUrls` | Not supported: a storage zone can't serve `/about.html` at `/about` |
|
|
272
|
+
| `outputDirectory` | `outputDir` |
|
|
273
|
+
|
|
274
|
+
## Trailing slashes
|
|
275
|
+
|
|
276
|
+
bunny.net serves `guides/index.html` at both `/guides` and `/guides/`. At `/guides`, relative links such as `./intro.html` resolve to `/intro.html` and break. Set `trailingSlash` in `orbitpush.json` to pick one form:
|
|
277
|
+
|
|
278
|
+
- `always` (default): a path whose last segment has no file extension, such as `/guides`, redirects with `301` to `/guides/`. Only HTML responses redirect, so files without an extension, such as `.well-known/apple-app-site-association`, are served as they are. Like Netlify's Pretty URLs, except that `/about.html` is not served at `/about/`: a storage zone can't serve another path. A missing path such as `/nope` redirects to `/nope/` and then gets the 404.
|
|
279
|
+
- `never`: `/guides/` redirects with `301` to `/guides`, except when the URL has a query string.
|
|
280
|
+
- `ignore`: no redirect. This is the default in [SPA mode](#spa-mode), where client routes such as `/projects` have no directory.
|
|
281
|
+
|
|
282
|
+
The redirect drops the query string, like a redirect with a fixed target in `redirects`. It is an edge rule that orbitpush manages, and the entries in `redirects` run first.
|
|
283
|
+
|
|
284
|
+
## Caching
|
|
285
|
+
|
|
286
|
+
Browsers get `Cache-Control: public, max-age=0` for every file, so they check for a new version on every visit, as on Netlify, and a deploy shows up right away. bunny.net still caches every file at its edge until the next deploy purges it.
|
|
287
|
+
|
|
288
|
+
For files whose name changes with their content, such as the fingerprinted assets of most build tools, set a long cache time in `headers`:
|
|
289
|
+
|
|
290
|
+
```json
|
|
291
|
+
"headers": [
|
|
292
|
+
{ "for": "/assets/*", "values": { "Cache-Control": "public, max-age=31536000, immutable" } }
|
|
293
|
+
]
|
|
294
|
+
```
|
|
295
|
+
|
|
296
|
+
A `Cache-Control` from `headers` also applies to bunny.net's edge: with `max-age=0` or `no-cache`, every request for those files goes to the storage zone.
|
|
297
|
+
|
|
298
|
+
## 404 page
|
|
299
|
+
|
|
300
|
+
Without SPA mode, a `404.html` in the root of the output directory is served with status `404` for every missing file.
|
|
301
|
+
|
|
302
|
+
## Development
|
|
303
|
+
|
|
304
|
+
```bash
|
|
305
|
+
npm install # also installs the lefthook git hooks
|
|
306
|
+
npm test # vitest, no network
|
|
307
|
+
npm run format # oxfmt
|
|
308
|
+
npm run lint # oxlint with type-aware rules
|
|
309
|
+
npm run typecheck # tsc
|
|
310
|
+
npm run build # bundles everything into dist/cli.js (no runtime dependencies)
|
|
311
|
+
npm run check # format check, lint, type-check, tests and build: must pass before a change is done
|
|
312
|
+
npm run test:e2e # Playwright against real bunny.net, see below
|
|
313
|
+
```
|
|
314
|
+
|
|
315
|
+
`npm run test:e2e` deploys each demo site in `e2e/sites/` to the bunny.net account of `BUNNY_API_KEY`, tests it in Chromium, then disables, enables and destroys it. It creates real zones named `orbitpush-e2e-<site>-<run>`; if a run is killed, delete leftovers in the dashboard. Set `E2E_COUNTRY` to the two-letter code of where you run it (`E2E_COUNTRY=de`) to also test a matching `Country=` redirect. Custom hostnames under `E2E_DOMAIN` need no DNS records: requests to them connect to `<name>.b-cdn.net`, so SSL certificates are not tested.
|
|
316
|
+
|
|
317
|
+
Dependencies are pinned to exact versions. Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/) (`type(scope): subject`); a lefthook `commit-msg` hook runs commitlint and rejects other messages, and a `pre-commit` hook formats the staged files. CI runs the same checks on pull requests and `main`, checks the commit messages and pull request title, and publishes to npm from `main` when `package.json` holds a new version.
|
|
318
|
+
|
|
319
|
+
## License
|
|
320
|
+
|
|
321
|
+
MIT
|