Skip to content

Add a Frameworks section to Edge Scripting, and the bunny sites reference - #429

Draft
bogdan-at-bunny wants to merge 15 commits into
mainfrom
docs/edge-scripting-astro-guide
Draft

Add a Frameworks section to Edge Scripting, and the bunny sites reference#429
bogdan-at-bunny wants to merge 15 commits into
mainfrom
docs/edge-scripting-astro-guide

Conversation

@bogdan-at-bunny

@bogdan-at-bunny bogdan-at-bunny commented Aug 19, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

What changed

  • Adds a Frameworks group to the Edge Scripting docs, between Script Types and Deployment.
  • Adds scripting/frameworks/index.mdx, which explains how a framework server runs at the edge and what constrains it.
  • Adds scripting/frameworks/astro.mdx, a guide that renders Astro per request on Edge Scripting with the bunny.net adapter.
  • Adds cli/commands/sites.mdx, the reference for bunny sites. It covers both shapes of site: a directory of files, and a build that renders per request.
  • Adds the static layer to cdn/custom-404-page.mdx and storage/static-site-hosting/index.mdx: a deploy's own 404.html, _redirects, and _headers.
  • Links the new section from the Edge Scripting index and from the frontend deployment guides.

Why

A reader who wants a framework on Edge Scripting had no page to start from. The Storage guides cover fully static sites, and stop where the dynamic part begins.

Astro is a server-first framework, so a guide that only prerenders it misses the point. An Astro build that renders per request is a (Request) => Response handler, which is the shape a script already needs.

One deploy command

An earlier revision of this branch documented a bunny deploy command beside bunny sites deploy. There is only one command now, bunny sites deploy, and it reads the build to decide what to send. So cli/commands/deploy.mdx is gone and cli/commands/sites.mdx covers both shapes. Neither page has shipped, so no redirect is needed.

Both pages also say when the adapter offer appears, which readers could not tell before: only a project that renders a page on demand is offered an adapter. A project that prerenders every page deploys as files and hears nothing about adapters.

Two things the guide got wrong

Found by running the commands again for this revision:

  • The example GitHub Actions workflow deployed without building. A workflow has nobody to ask, so an unattended deploy never offers a build: it needs --build.
  • --env and --env-file were shown without --build. They apply to the build, and the command reports the mistake rather than ignoring them.

Depends on the adapter package

This guide uses @bunny.net/astro-adapter. The package has to be published to npm before this merges. Until then the install command in the guide does not resolve.

The adapter is what keeps the guide short. It adds itself to the config, and it does not set output:

export default defineConfig({
  adapter: bunny(),
});

Verified

Every command in the guide was run against a real account, with the adapter installed the way a reader would install it.

  • A build that renders per request produced a script of about 660 kB, against the 10 MB script limit.
  • Deployed to a real site. Pages that render per request, src/pages/api/, dynamic routes, prerendered pages from Storage, hashed assets, and the build's own 404 page all answered as the guide says.
  • A build with every route prerendered deployed as files, got its own preview URL, and answered a missing path with its own 404 page.
  • Publishing an earlier deploy took back the page and the asset it names, together.
  • Both verification sites were deleted afterwards.
  • mint broken-links reports no new broken links.

One table on the bunny sites page waits on a CLI fix. It says a page may be cached for 60 seconds, which is what the router asks for. In the live run a page reached the browser with a far longer lifetime, because the router only sets Cache-Control on a response that carries none, and Bunny Storage sends one. The table describes the behaviour this documents, and the CLI change is tracked in BunnyWay/cli#172. Neither branch has shipped, so the fix can land before either merges.

🤖 Generated with Claude Code

https://claude.ai/code/session_01NpdDkzyH7pPq5FZqPCRhzE

@bogdan-at-bunny @claude
Add a Frameworks section to Edge Scripting, with an Astro guide
60ba7fd 
Add a new "Frameworks" group under Edge Scripting. It shows how to run a web
framework on a standalone script: keep the build in Bunny Storage, and let the
script serve the files and the dynamic routes.

- Add an overview page that explains the pattern and its constraints.
- Add a guide that deploys an Astro site end to end.
- Link the new section from the Edge Scripting index.
- Point readers of the frontend deployment guides here when they need dynamic
  routes.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Et5xuUCDVjxBHpCGtZcECv
@mintlify

mintlify Bot commented Aug 19, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated (UTC)
bunny 🟢 Ready View Preview Aug 19, 2026, 7:54 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

@bogdan-at-bunny
bogdan-at-bunny marked this pull request as draft August 19, 2026 07:55
@bogdan-at-bunny @claude
Lead the Astro guide with server-side rendering
41dc255 
Testing showed that Astro's server runs inside an Edge Script. An SSR build is
a (Request) => Response handler, which is the shape a standalone script needs.
A minimal site bundles to about 600 KB, well inside the 10 MB limit.

The first draft claimed Edge Scripting cannot run a framework server. That was
wrong, so the guide now leads with SSR.

- Add a complete Astro adapter for Edge Scripting, in two short files.
- Show the Edge Script entry that renders SSR routes and reads assets and
  prerendered pages from Bunny Storage.
- Keep the static build as a smaller alternative, and say what it gives up.
- Add troubleshooting for the sharp image service, the origin check on POST,
  and prerendered routes.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Et5xuUCDVjxBHpCGtZcECv
@bogdan-at-bunny bogdan-at-bunny changed the title Add a Frameworks section to Edge Scripting, with an Astro guide Add a Frameworks section to Edge Scripting, with an Astro SSR guide Aug 19, 2026
@bogdan-at-bunny @claude
Fix three defects in the Astro adapter
61bd003 
Building a fuller demo of the guide found three problems in the adapter it
publishes.

- Astro.cookies.set() did nothing. The adapter now passes addCookieHeader to
  app.render(), so Astro writes the Set-Cookie header itself.
- The build warned that entrypointResolution "explicit" is deprecated. The
  adapter now uses "auto" with a project-relative entrypoint, which also drops
  the fileURLToPath import.
- A script's pull zone strips Set-Cookie by default, so cookies still failed
  after the code was correct. Troubleshooting now covers the Disable cookies
  setting.

Also adds troubleshooting for two traps found while testing: a hashed CSS name
changes on every style edit, so the client upload must run with every deploy;
and middleware runs during prerendering, where there is no request to read.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Et5xuUCDVjxBHpCGtZcECv
@bogdan-at-bunny bogdan-at-bunny mentioned this pull request Aug 19, 2026
Merged
@bogdan-at-bunny @claude
Use the new Astro adapter package in the guide
a9228a4 
@bunny.net/astro-adapter now holds the code this guide used to ask readers to
write. The setup is a config change instead of an adapter, a request handler,
and a bundler.

- Replace roughly 200 lines of copied code with `adapter: bunny()`.
- Use `bunny-astro upload` for the client build, which removes the step people
  forget and which silently drops the site's styles.
- Rename the runtime variables to BUNNY_STORAGE_ZONE, BUNNY_STORAGE_HOST, and
  BUNNY_STORAGE_KEY, matching the package.
- Keep the troubleshooting entries, since the traps are unchanged.

The guide is now 262 lines instead of 425, and none of it is glue.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Et5xuUCDVjxBHpCGtZcECv
@bogdan-at-bunny @claude
Bring the Astro guide up to the adapter it documents
5bd7c80 
The adapter moved to BunnyWay/bunny-adapters, and it gained the platform
features Astro has hooks for. The guide now covers them:

- `bunny-astro deploy`, one command for the upload and the deploy.
- Bunny Optimizer as the image service.
- Sessions, in a second storage zone the script may write to.
- `routeRules`, `CDN-Tag`, and purging.
- `Astro.locals.runtime` and `astro preview`.
- A link to the live demo, which is also the adapter's test fixture.

Two warnings are new, and they belong together. Smart Cache does not
cache HTML, so a `routeRules` entry does nothing until it is switched
off. A pull zone then applies its own thirty day expiration to any
response with no `Cache-Control`, which would cache a page rendered for
one visitor, so the adapter marks those `private, no-store`.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Et5xuUCDVjxBHpCGtZcECv
@bogdan-at-bunny bogdan-at-bunny mentioned this pull request Aug 19, 2026
Merged
@bogdan-at-bunny @claude
Correct what the Astro guide says about node:fs
66e337a 
The guide implied `fs` was unavailable. Edge Scripting provides most
`node:` built-ins, including `node:fs` over a virtual file system, and
the adapter rewrites a bare `fs` to the prefixed name so a dependency
resolves. Only a package with a native binary is a real problem.

The new section also says what that file system is not. It starts empty
on every cold start, one isolate cannot see what another wrote, and it
lives in the script's memory. So it is a scratch pad for one request,
and anything that has to last belongs in Bunny Storage.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Et5xuUCDVjxBHpCGtZcECv
@bogdan-at-bunny @claude
Warn that Astro.rewrite('/404') cannot reach a prerendered page
8e15e5d 
It is the obvious thing to write in a dynamic route, and it throws a
500: a prerendered route has no server component to rewrite to. Return a
bodyless 404 instead, and the adapter serves the prerendered page out of
Bunny Storage.

An endpoint keeps its own 404, so a JSON client is never handed a web
page.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Et5xuUCDVjxBHpCGtZcECv
@bogdan-at-bunny @claude
Say that Bunny Optimizer cannot read from an Edge Script
5b1459b 
With Optimizer on for the pull zone, every image request that misses the
CDN cache answers 523 Origin Connection Failed. Optimizer fetches the
original from the origin, and a script is not an origin it can read.
Measured on two script-backed pull zones.

The support table also gains the rows the adapter's new tests cover: a
base path, redirects with their real status, locale routing, content
collections, islands, actions, and static page headers.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014WoKonkC5YqNMXi5CEYmL9
@bogdan-at-bunny @claude
Say how a large file is served, and how to make it seekable
ff8b931 
The adapter answers a range request on a stored object, and says
Accept-Ranges on everything it serves. A pull zone will not answer a range
from its cache unless the origin says that, so the header is the part that
matters. Optimize for large object delivery covers a file nobody has
requested yet.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014WoKonkC5YqNMXi5CEYmL9
@bogdan-at-bunny @claude
Describe the Astro deploy we want, not the one we have
4cf9348 
The guide asked for 5 steps before a site was up. It asked for a storage
zone, two passwords, three environment variables, and two raw API calls.
Each step is a place to make a mistake, and each mistake looks like a
broken site.

This rewrites the guide against one command:

    bunny deploy

The CLI detects Astro, offers the adapter, builds, provisions the site,
uploads the build, and publishes the script. It sets each credential
itself, so no password moves through the terminal.

The guide now also covers the parts a deploy tool owes a developer:
previews, rollback, environment variables, and continuous integration.
Manual pull zone settings are gone, because the CLI applies what the
adapter asks for and reports the changes.

None of this is built yet. The plan is in BunnyWay/bunny-adapters, at
plans/one-command-deploys.md. Hold this branch until the CLI ships it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DNEZw6pebXfttb98s3ihG8
@bogdan-at-bunny @claude
Make the Astro guide match the CLI that now exists
8f11d2f 
The previous commit described the deploy we wanted. `bunny deploy` is
built now, so this corrects the guide to the tool:

- Commands that exist: `bunny sites deployments list`, `bunny sites
  domains add`, `bunny scripts env set`. The short aliases and `bunny
  logs` are not built.
- Every deploy publishes to production. Preview URLs per branch need a
  script per environment, which is designed and not built.
- The script reads the build's files from Bunny Storage, so it is the
  script that answers a range request, not the pull zone. The earlier
  text described a pass-through the adapter does not do yet.
- Each deploy keeps its client files and its server bundle in the zone,
  and the published bundle names its own folder. That is what makes a
  rollback restore a page with the assets it names.
- A new section says plainly what the tooling does not do yet: branch
  previews, adopting a hand-built site, and logs from the terminal.

The first-run transcript is now the CLI's real output, from a fresh
`npm create astro` project deployed to a live account.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DNEZw6pebXfttb98s3ihG8
bogdan-at-bunny and others added 2 commits August 19, 2026 16:09
@bogdan-at-bunny @claude
Say that the adapter never touches output
e438c46 
Three real Astro projects met `bunny deploy`, and what they taught goes in
the guide. The command adds the adapter and nothing else: Astro's own
default prerenders pages, and a page asks for the edge itself. Setting
`output: "server"` over that took astro.build's script from 7.83 MB to
22.30 MB.

The guide now says what the build decides and why, what a project moving
from another host sees, how a monorepo behaves, and what the 10 MB limit
looks like when a build hits it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DNEZw6pebXfttb98s3ihG8
@bogdan-at-bunny @claude
Say that 10 MB is not the script size to aim at
8289069 
A script has 500ms to start, and every byte of it is parsed and evaluated
first. So a bundled framework server well under 10 MB can fail to start, and
the edge then answers 400 with an empty body. Measured in August 2026: the
same code served every request at 7.44 MB and none at 7.83 MB.

The limits page now says the two limits work together, and the Astro guide
has the 400 in its troubleshooting.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DNEZw6pebXfttb98s3ihG8
@bogdan-at-bunny
Document the static layer, and give the CLI its two missing pages
2e8d360 
The 404 page, the redirects and the headers of a static site belong to the
`bunny sites` router, not to a framework adapter. Four pages say so:

- New `cli/commands/sites.mdx`: what a site is, immutable deploys and their
  preview URLs, and the three file names the router reads out of the deploy.
  It names the subset of `_redirects` and `_headers` that is supported, and the
  `Cache-Control` the router sets on every response.
- New `cli/commands/deploy.mdx`: one command for a project that renders per
  request and one that ships as files, and what the deploy checks afterwards.
- `cdn/custom-404-page.mdx` gains the measured facts. The folder is read at the
  zone root and a copy in a sub-folder is ignored, the status is 404, the page
  answers `no-cache`, and one page belongs to one zone.
- `storage/static-site-hosting/index.mdx` points at the one command that does
  the whole page for you, and says what a storage zone cannot do alone.
- The Astro guide no longer says a prerendered site needs a script for its 404
  page. The router answers it, and the build writes `_redirects` and `_headers`.
@bogdan-at-bunny @claude
Document one deploy command, not two
86ac60b 
`bunny deploy` is gone from the CLI, and `bunny sites deploy` deploys both shapes
of site: a directory of files, and a build that renders each page per request.
So `cli/commands/deploy.mdx` goes, and `cli/commands/sites.mdx` covers both. No
redirect is needed, because neither page has shipped.

The Astro guide and the frameworks index name the new command. `bunny rollback`
becomes `bunny sites deployments publish --previous`, and `--open` becomes
`bunny sites open`, because neither flag exists any more.

Two things the guide said were wrong before this change, and are now right:

- The example workflow ran `bunny sites deploy` with no build. A workflow has
  nobody to ask, so an unattended deploy never offers a build: it needs `--build`.
- `--env` and `--env-file` apply to the build, so they need `--build` too. Without
  it the command reports the mistake.

Both pages also say when the adapter offer appears, which is new: only a project
that renders a page on demand is offered one. A project that prerenders every page
deploys as files, and hears nothing about adapters.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NpdDkzyH7pPq5FZqPCRhzE
@bogdan-at-bunny bogdan-at-bunny changed the title Add a Frameworks section to Edge Scripting, with an Astro SSR guide Add a Frameworks section to Edge Scripting, and the bunny sites reference Aug 21, 2026
@bogdan-at-bunny

bogdan-at-bunny commented Aug 21, 2026

Copy link
Copy Markdown
Contributor Author

@mintlify deploy to staging

@mintlify

mintlify Bot commented Aug 21, 2026

Copy link
Copy Markdown
Contributor

AI credits exhausted for this billing cycle. Upgrade your plan or wait for your credits to renew.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@bogdan-at-bunny