bunny sites - bunny.net Documentation

bunny sites hosts a site on bunny.net. Each site is three resources, provisioned and wired together for you:

Resource	What it does
A storage zone	Holds every deploy’s files
A pull zone	The site’s URL, its cache, and its domains
An Edge Script	The static site’s router, or the build’s own server

Zones are named sites-<name>-<suffix>. The prefix groups them in the dashboard. The suffix is there because zone names are global across bunny.net. The commands take the clean site name. The Edge Script is what the two kinds of site differ by:

A static site’s script is the router this CLI writes. It maps each request to the deploy that answers it, and it serves the deploy’s own 404.html, _redirects and _headers.
A site that renders per request runs the build’s own server in the script. Its client files still come from Bunny Storage, and each deploy keeps its own server bundle, so publishing an earlier deploy restores its pages and its assets together.

One command deploys both. bunny sites deploy reads .bunny/build.json, the manifest a framework adapter writes, and takes the path it names. The CLI knows no framework: it reads the manifest, so a new adapter needs no new CLI.

bunny sites deploy                 # build if needed, then deploy
bunny sites deploy --build         # run the project's own build first
bunny sites deploy ./dist          # deploy a directory of files
bunny sites deploy --production    # publish a static deploy as the live site

Deploy this project

bunny login

Run the command in your project

bunny sites deploy

With no site linked yet, the command offers to create one. A project that renders pages on demand also gets an offer to add the bunny.net adapter for its framework:

ℹ This Astro project renders on demand: src/pages/api/time.ts sets prerender = false.
? Add @bunny.net/astro-adapter to astro.config.mjs? › (Y/n)

? Site name: › my-site
✓ Created site "my-site".
✓ Deployed a1b2c3d4: 42 files (1.9 MB), script 653 KB.
ℹ Production  https://sites-my-site-k3f9wq.b-cdn.net

Add your domain

The site’s first deploy offers one. To add it later:

bunny sites domains add www.example.com

Nothing above asks for a password. The CLI creates the storage zone, so it already holds the credentials. It sets them on the script as secrets. Every deploy goes to its own directory in the storage zone. So publishing an earlier one restores its pages, and the files those pages name, together.

A project that renders per request

The build writes .bunny/build.json, and the deploy acts on it. It uploads the client files and publishes the script. It also applies the pull zone settings the adapter asks for, and sets the variables the script reads. Then it asks the live site for a page. A green line above a URL that answers 400 is the worst thing this command can do, so a script that does not start is reported instead:

⚠ The site answered 400, so the script is not serving.
  The script is 8.2 MB, and a script has 500 ms to start. Every byte is parsed first.
  The deploy before it is still there: bunny sites deployments publish --previous

One script serves one release, so such a deploy publishes to production, and the command says so. Preview environments for a site that renders per request are not built yet.

bunny sites create provisions a static site. For a project that renders per request, let bunny sites deploy create the site: it needs the build manifest to know what the site runs, and create runs no build.

When the adapter is offered

Only a project that asks for a server hears about an adapter. Any one of these counts as asking:

The signal	What it means
The config names another vendor’s adapter	The project renders on demand somewhere else today
The config sets `output: "server"`	Every page renders per request
The bunny.net adapter is already a dependency	Somebody installed it and stopped
A route under `src/pages/` sets `prerender = false`	That one route renders per request

A project with none of these prerenders every page. It deploys as a directory of files, it is never offered an adapter, and its config is never edited. The last signal is the one that matters most. Since Astro 5 a project prerenders every page unless a page opts out, and astro build stops with its own error when a page opts out and no adapter is installed. Reading the routes puts the offer before that failure.

A build that renders nothing

A build with no route to render per request writes no script at all. The deploy is the files, and the site is served by the static router below: it answers a miss with the build’s own 404.html, and it reads _redirects and _headers from the deploy. The build says which of the two it produced, and why.

Deploy a directory

Deploy

bunny sites deploy ./dist

The deploy lands on its own preview URL, and the first deploy of a site offers to publish it.

Publish

bunny sites deploy ./dist --production

Publishing points the router at that deploy and purges the cache. Nothing moves, so going live and rolling back are both instant.

Immutable deploys

Every deploy uploads to its own directory in the storage zone, and gets a pull zone of its own. That is a permanent HTTPS URL, and it needs no DNS or certificate setup:

https://sites-dpl-a1b2c3d4-x1y2z3.b-cdn.net

A preview serves from the site’s root, not under a path prefix. So a client-side router and a root-absolute asset behave exactly as they do in production. Preview responses carry X-Robots-Tag: noindex. The deploy ID is the git short SHA when the working tree is clean, and a content hash otherwise. So re-deploying identical content is a no-op. Use --force to override that.

bunny sites deployments list                 # ● Live / ○ Previous, created, source, files, size
bunny sites deployments publish a1b2c3d4     # promote a past deploy
bunny sites deployments publish --previous   # instant rollback
bunny sites deployments prune --keep 10      # delete old deploys and their preview URLs

A rollback of a site that renders per request reads that deploy’s stored server bundle back out of storage. So the pages and the files they name come back together.

What the deploy configures

A static site’s router reads three file names out of the deploy it is serving. Cloudflare Pages and Netlify read the same three. So a build that already writes them works here unchanged, and the router knows no framework.

File in the deploy	What the router does with it
`404.html`	Answers a path the deploy does not hold, at status 404
`_redirects`	Sends a redirect with a real status
`_headers`	Adds response headers, which Bunny Storage cannot hold on its own

Without a 404.html in the deploy, a missing path answers with bunny.net’s own error page instead of your site’s. So bunny sites deploy asks the published site for a path it cannot hold. It warns you when the answer is not your page.

A site that renders per request gets none of this. Its script is the build’s own server, and the build decides what it answers with.

`_redirects`

One rule per line: a path, a target, and an optional status. Lines starting with # are comments.

# dist/_redirects
/old            /about
/gone           /about       302
/blog/*         /news/:splat 301
/moved          /about       301!

The default status is 301. 302, 303, 307 and 308 are read too. A rewrite (200) is not supported.
A trailing * in the path is captured, and :splat in the target is replaced with it.
A rule applies only where the deploy holds no file at that path, so a real file always wins. ! after the status forces the rule ahead of the file.
A path matches with or without its trailing slash, so /about and /about/ are one rule.

`_headers`

A line starting with / opens a block, and the indented Name: value lines below it belong to that block. Where two blocks match one path, the later one wins that header name.

# dist/_headers
/*
  X-Frame-Options: SAMEORIGIN
/assets/*
  Cache-Control: public, max-age=31536000, immutable
/admin/
  X-Robots-Tag: noindex

Caching

The router sets Cache-Control on every response, because Bunny Storage sends none for HTML:

What	How long
A page, and any document	`public, max-age=60`
Anything else	`public, max-age=2592000`
A missing page	`no-cache`
Anything `_headers` names	Whatever `_headers` says

Publishing purges the whole zone, so a promoted deploy answers at once. A purge does not reach a browser, which is why a page keeps only the one minute. A file whose name carries a content hash never changes. Name that directory in _headers, and the browser keeps it for a year.

A site created by an earlier CLI has an earlier router. bunny sites deploy republishes it when it lags, and bunny sites upgrade-router does it on demand.

Custom domains

A custom domain is the site’s production URL. Previews never depend on one.

bunny sites domains add shop.example.com          # prints the DNS record to create
bunny sites domains add shop.example.com --wait   # add, wait for DNS, then issue SSL
bunny sites domains list
bunny sites domains remove shop.example.com --force

Every command

# Provision
bunny sites create                       # prompts for a name
bunny sites create my-site --region NY   # store the files in New York (default: DE)
bunny sites create my-site --domain example.com

# Deploy
bunny sites deploy                       # build if needed, then deploy
bunny sites deploy --build               # run the configured or detected build first
bunny sites deploy ./dist --production
bunny sites deploy --name my-site --region NY   # create the site this deploy needs, unattended

# Inspect
bunny sites list
bunny sites show                         # resources, domains, SSL state, current deploy
bunny sites open --print

# Maintain
bunny sites ci init                      # GitHub Actions: previews on PRs, production on main
bunny sites link my-site
bunny sites unlink
bunny sites upgrade-router
bunny sites delete my-site --keep-storage

Which site a command acts on

Most commands take the site as an optional positional. deploy, ci init, and deployments publish use --site. Either accepts the site name or its storage zone ID. With none given, the site resolves in this order:

The directory’s linked site, in .bunny/site.json
sites.name in bunny.jsonc
An interactive picker, which offers to link the directory

A run that cannot prompt reports an error instead. That is --output json, no TTY, or --force on a destructive command. A --name is an instruction, so an unattended run with one creates the site and needs nothing else. A build and a site have to be the same kind. A script’s type is fixed when it is created, so a static site cannot run a build’s server, and a site that renders per request cannot serve a directory of files. The deploy names the mismatch, and it stops before it uploads anything. Preconfigure the sites block in bunny.jsonc and a deploy needs no arguments:

{
  "sites": {
    "name": "my-site",
    "build": "npm run build",
    "dir": "dist",
  },
}

bunny sites deploy --build --prod

A dir here is an instruction: deploy these files. The command then offers no adapter, and it deploys the directory whatever the project holds. Site state lives at _bunny/site.json inside the storage zone, which the router never serves. .bunny/site.json is only a local pointer. So a fresh clone can bunny sites link, and go on where the last machine stopped.

In a monorepo, run bunny sites deploy at the repository root, and it finds the framework projects below it. Or run it in a project’s own directory to deploy that one. The package manager comes from the workspace, so a pnpm monorepo gets pnpm.

Flags

Flag	Commands	Description
`--region`, `--domain`	`create`	Storage region (default `DE`); custom production domain to attach
`--name`, `--region`	`deploy`	Site name and storage region, for a site this deploy creates
`--site`	`deploy`, `ci init`, `deployments publish`	Site name or storage zone ID
`--build [cmd]`, `--env`, `--env-file`	`deploy`	Build before deploying; build-time environment overrides
`--production`, `--prod`	`deploy`	Publish a static deploy as the live site. A build that renders per request always publishes
`--force`	`deploy`	Deploy even when the content is unchanged
`--previous`	`deployments publish`	Publish the previous deploy
`--keep`	`deployments prune`	Recent deploys to keep (default 5; live and previous are always kept)
`--ssl`, `--wait`, `--force-ssl`	`domains add`	Issue SSL now; wait for DNS then issue it; `--no-force-ssl` keeps HTTP working
`--framework`	`ci init`	Framework preset for the workflow’s build steps
`--print`	`open`	Print the URL instead of opening a browser
`--link`	`create`, `deploy`, `show`, `ci init`, `deployments`	Link the directory to the site; `--no-link` never links
`--keep-storage`	`delete`	Delete the pull zone and router, and keep the files
`--force`, `-f`	`deployments publish`, `prune`, `domains remove`, `delete`	Skip the confirmation prompt

​Deploy this project

​A project that renders per request

​When the adapter is offered

​A build that renders nothing

​Deploy a directory

​Immutable deploys

​What the deploy configures

​_redirects

​_headers

​Caching

​Custom domains

​Every command

​Which site a command acts on

​Flags

Deploy this project

A project that renders per request

When the adapter is offered

A build that renders nothing

Deploy a directory

Immutable deploys

What the deploy configures

`_redirects`

`_headers`

Caching

Custom domains

Every command

Which site a command acts on

Flags