Feat(cloudflare): configure prerender environment by OliverSpeir · Pull Request #15711 · withastro/astro

OliverSpeir · 2026-03-02T10:36:35Z

Changes

Adds a prerenderEnvironment config option to cloudflare adapter

Adds prerenderEnvironment: 'workerd' | 'node' to the adapter options (defaults to 'workerd'). When set to 'node', we skip the custom workerd-based prerenderer and the @cloudflare/vite-plugin prerender worker config, falling back to Astro's built-in prerender environment instead.

Makes prerenderEnvironment: 'node' work during astro dev by adding a Vite plugin that intercepts requests for prerendered pages and renders them through the prerender environment which is, currently, node instead of workerd.

Testing

adds tests to start up dev server and verify it is using the correct environement

Docs

/cc @withastro/maintainers-docs for feedback!
withastro/docs#13389

changeset-bot · 2026-03-02T10:36:43Z

🦋 Changeset detected

Latest commit: 6ed27df

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

packages/integrations/cloudflare/src/vite-plugin-dev-server-prerender-middleware.ts

codspeed-hq · 2026-03-02T10:52:53Z

Merging this PR will not alter performance

✅ 18 untouched benchmarks

_{Comparing feat/cloudflare-conf-prerender-env (6ed27df) with main (1cdaf9f)}

ematipico · 2026-03-02T11:01:52Z

@OliverSpeir please restore our PR template and fill it accordingly

ematipico

Blocking because the testing part wasn't filled. Since this is a sensitive change, I want to make sure testing is done properly

ematipico · 2026-03-02T11:12:26Z

packages/integrations/cloudflare/src/vite-plugin-dev-server-prerender-middleware.ts

I'm not sure I understand why we're using this plugin. Can't we use the default Astro behaviour? It seems we're repeating code here, and we risk to diverge even more the dev behaviour from the "default" one

Might have missed an obvious way to do this, how would you do it?

If we don't load the CF plugin, Astro automatically uses its own dev server.

astro/packages/astro/src/vite-plugin-astro-server/plugin.ts

Lines 52 to 56 in 6acc91c

// Cloudflare handles its own requests

// TODO: let this handle non-runnable environments that don't intercept requests

if (!isRunnableDevEnvironment(viteServer.environments[ASTRO_VITE_ENVIRONMENT_NAMES.ssr])) {

return;

}

So the question is, what is this plugin actually doing? I read the documentation provided, and it seems it's meant for astro dev, correct?

Yeah the scenario is we want pre-rendered pages to go through astro default dev server and on demand pages to go through workerd so that it aligns with the new option which uses node for prerendered pages instead of workerd

another way would be if the cloudflare vite plugin accepted a shouldHandle function

https://github.com/cloudflare/workers-sdk/blob/596b8a0cb/packages/vite-plugin-cloudflare/src/plugins/dev.ts#L267

could just return next() and then astros default dev server would handle it and we don't need this plugin at all

We want to forward prerender pages to the astro environment in development, and prerenderer in build.

Yes in dev, in build we are actually just changing the prerenderer by not setting it to use the workerd one

We want to forward ssr pages to the ssr environment in development, and prerenderer in build.

on demand pages stay ssr for both dev and build

Currently all dev server requests go to ssr environment, and the cloudflare vite-plugin implements its own ssr which intercepts all requests indiscriminately via adding a vite middleware - so this PR creates a middleware that runs before the vite-plugin's and checks if the request is for a prerendered route and if it is it sends it to the astro environment which already exists but isnt used for dev server typically (no particular reason to use this environment its just that it already exists and has a runnable dev environment) and if it is not a prerendered route we let it go through to the ssr environment which is workerd

@ematipico bump

created cloudflare/workers-sdk#12747 as well

As a stop gap you could use configResolved and null out the dev plugin for cloudflare. https://github.com/cloudflare/workers-sdk/blob/main/packages/vite-plugin-cloudflare/src/plugins/dev.ts#L61

Pseudo-code:

const cloudflareDev = plugins.find(plugin => plugin.name === 'vite-plugin-cloudflare:dev'); cloudflareDev.configureServer = null

I do agree with James here though, that seems like a fairly clean way to do it: cloudflare/workers-sdk#12747

I vibe coded James' idea here: 65cfde8

.changeset/cloudflare-prerender-environment.md

sarah11918

Great changeset @OliverSpeir ! 🎉

We'll just need a corresponding docs PR here in the Cloudflare adapter options section for prerenderEnvironment: https://v6.docs.astro.build/en/guides/integrations-guide/cloudflare/#options (You can use the headings for sessionKVBindingsName as a model for the API reference, since this one will need the <Since /> component too.)

.changeset/cloudflare-prerender-environment.md

Co-authored-by: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com>

…ecks

pkg-pr-new · 2026-03-10T13:53:24Z

npm i https://pkg.pr.new/astro@15711

npm i https://pkg.pr.new/@astrojs/cloudflare@15711

commit: 76f3a50

…dleware

ematipico

Unblocking. Let's merge after manual testing :)

matthewp · 2026-03-11T13:26:01Z

pnpm add https://pkg.pr.new/@astrojs/cloudflare@a6cac29

matthewp · 2026-03-11T13:29:23Z

I'm hitting an issue in my testing, looking into it.

matthewp · 2026-03-11T14:22:22Z

Ah, I didn't have the right version of Astro because there isn't a changeset. I'll add one.

matthewp · 2026-03-11T14:48:05Z

pnpm add https://pkg.pr.new/astro@71a927a
pnpm add https://pkg.pr.new/@astrojs/cloudflare@71a927a

matthewp · 2026-03-11T16:02:02Z

npm i https://pkg.pr.new/astro@76f3a50
npm i https://pkg.pr.new/@astrojs/cloudflare@76f3a50

.changeset/astro-dev-prerender-core-fixes.md

sarah11918

Approving the changeset for docs (though a suggestion to consider!)

Co-authored-by: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com>

This PR contains the following updates: | Package | Change | [Age](https://docs.renovatebot.com/merge-confidence/) | [Confidence](https://docs.renovatebot.com/merge-confidence/) | |---|---|---|---| | [astro](https://astro.build) ([source](https://github.com/withastro/astro/tree/HEAD/packages/astro)) | [`6.0.2` → `6.0.3`](https://renovatebot.com/diffs/npm/astro/6.0.2/6.0.3) | ![age](https://developer.mend.io/api/mc/badges/age/npm/astro/6.0.3?slim=true) | ![confidence](https://developer.mend.io/api/mc/badges/confidence/npm/astro/6.0.2/6.0.3?slim=true) | --- ### Release Notes <details> <summary>withastro/astro (astro)</summary> ### [`v6.0.3`](https://github.com/withastro/astro/blob/HEAD/packages/astro/CHANGELOG.md#603) [Compare Source](https://github.com/withastro/astro/compare/astro@6.0.2...astro@6.0.3) ##### Patch Changes - [#15711](withastro/astro#15711) [`b2bd27b`](withastro/astro@b2bd27b) Thanks [@OliverSpeir](https://github.com/OliverSpeir)! - Improves Astro core's dev environment handling for prerendered routes by ensuring route/CSS updates and prerender middleware behavior work correctly across both SSR and prerender environments. This enables integrations that use Astro's prerender dev environment (such as Cloudflare with `prerenderEnvironment: 'node'`) to get consistent route matching and HMR behavior during development. - [#15852](withastro/astro#15852) [`1cdaf9f`](withastro/astro@1cdaf9f) Thanks [@ematipico](https://github.com/ematipico)! - Fixes a regression where the the routes emitted by the `astro:build:done` hook didn't have the `distURL` array correctly populated. - [#15765](withastro/astro#15765) [`ca76ff1`](withastro/astro@ca76ff1) Thanks [@matthewp](https://github.com/matthewp)! - Hardens server island POST endpoint validation to use own-property checks for improved consistency </details> --- ### Configuration 📅 **Schedule**: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined). 🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied. ♻ **Rebasing**: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this PR and you won't be reminded about this update again. --- - [ ] If you want to rebase/retry this PR, check this box --- This PR has been generated by [Renovate Bot](https://github.com/renovatebot/renovate).  Co-authored-by: Renovate Bot <renovate@zarantonello.dev> Co-committed-by: Renovate Bot <renovate@zarantonello.dev>

OliverSpeir added 3 commits March 1, 2026 22:55

feat(cloudflare): add prerenderEnvironment config option

a1b1971

feat(cloudflare): dev server prerender middleware

2364ffc

chore: add changeset

102ba5c

github-actions bot added pkg: integration Related to any renderer integration (scope) pkg: astro Related to the core `astro` package (scope) labels Mar 2, 2026

OliverSpeir commented Mar 2, 2026

View reviewed changes

packages/integrations/cloudflare/src/vite-plugin-dev-server-prerender-middleware.ts Outdated Show resolved Hide resolved

ematipico requested changes Mar 2, 2026

View reviewed changes

sarah11918 reviewed Mar 2, 2026

View reviewed changes

.changeset/cloudflare-prerender-environment.md Outdated Show resolved Hide resolved

fix changeset

5dcff6c

sarah11918 reviewed Mar 2, 2026

View reviewed changes

.changeset/cloudflare-prerender-environment.md Outdated Show resolved Hide resolved

Update .changeset/cloudflare-prerender-environment.md

912d50e

Co-authored-by: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com>

ematipico self-assigned this Mar 2, 2026

bendrucker mentioned this pull request Mar 3, 2026

build(deps): upgrade to Astro 6 bendrucker/bendrucker.me#313

Merged

4 tasks

fix(cloudflare): register prerender middleware after Vite security ch…

b328158

…ecks

OliverSpeir force-pushed the feat/cloudflare-conf-prerender-env branch from 2a5b9dd to b328158 Compare March 4, 2026 03:06

matthewp added the pr preview Apply this label to a PR to generate a preview release label Mar 10, 2026

github-actions bot removed the pr preview Apply this label to a PR to generate a preview release label Mar 10, 2026

Merge branch 'main' into feat/cloudflare-conf-prerender-env

5100050

matthewp added the pr preview Apply this label to a PR to generate a preview release label Mar 10, 2026

github-actions bot removed the pr preview Apply this label to a PR to generate a preview release label Mar 10, 2026

matthewp and others added 5 commits March 10, 2026 12:27

feat(cloudflare): route dev prerender handling through Astro core mid…

65cfde8

…dleware

fix: remove additional astro environment

bf8594e

adds tests

df8133f

update lockfile

1540d39

fix: add todo comment back

3917012

OliverSpeir mentioned this pull request Mar 10, 2026

[Feature Request] option to skip request in dev middleware cloudflare/workers-sdk#12747

Closed

Remove unused settingsSymbol

53c0c72

matthewp approved these changes Mar 11, 2026

View reviewed changes

ematipico approved these changes Mar 11, 2026

View reviewed changes

matthewp added the pr preview Apply this label to a PR to generate a preview release label Mar 11, 2026

github-actions bot removed the pr preview Apply this label to a PR to generate a preview release label Mar 11, 2026

Merge branch 'main' into feat/cloudflare-conf-prerender-env

0b3f414

matthewp added the pr preview Apply this label to a PR to generate a preview release label Mar 11, 2026

github-actions bot removed the pr preview Apply this label to a PR to generate a preview release label Mar 11, 2026

fix: add astro changeset for dev prerender core handling

4ad0770

matthewp added the pr preview Apply this label to a PR to generate a preview release label Mar 11, 2026

github-actions bot removed the pr preview Apply this label to a PR to generate a preview release label Mar 11, 2026

Don't skip dots

11b0193

matthewp added the pr preview Apply this label to a PR to generate a preview release label Mar 11, 2026

github-actions bot removed the pr preview Apply this label to a PR to generate a preview release label Mar 11, 2026

sarah11918 reviewed Mar 11, 2026

View reviewed changes

.changeset/astro-dev-prerender-core-fixes.md Outdated Show resolved Hide resolved

sarah11918 approved these changes Mar 11, 2026

View reviewed changes

Update .changeset/astro-dev-prerender-core-fixes.md

6ed27df

Co-authored-by: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com>

matthewp merged commit b2bd27b into main Mar 11, 2026
25 of 27 checks passed

matthewp deleted the feat/cloudflare-conf-prerender-env branch March 11, 2026 16:48

astrobot-houston mentioned this pull request Mar 11, 2026

[ci] release #15851

Merged

to4iki mentioned this pull request Mar 17, 2026

chore: upgrade to Astro v6 and @astrojs/cloudflare v13 to4iki/mysite#2

Merged

astrobot-houston mentioned this pull request Mar 18, 2026

Dynamic catch all route receives wrong params #15969

Open

1 task

bendrucker mentioned this pull request Mar 29, 2026

OG image generation fails in dev mode with Astro 6 / Cloudflare adapter v13 bendrucker/bendrucker.me#348

Closed

astrobot-houston mentioned this pull request Apr 2, 2026

[Bug]: @astrojs/cloudflare prerender worker inherits queues.consumers, causing Miniflare ERR_MULTIPLE_CONSUMERS error #16199

Open

1 task

	// Cloudflare handles its own requests
	// TODO: let this handle non-runnable environments that don't intercept requests
	if (!isRunnableDevEnvironment(viteServer.environments[ASTRO_VITE_ENVIRONMENT_NAMES.ssr])) {
	return;
	}

Uh oh!

Conversation

OliverSpeir commented Mar 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Testing

Docs

Uh oh!

changeset-bot bot commented Mar 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

Uh oh!

codspeed-hq bot commented Mar 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merging this PR will not alter performance

Uh oh!

ematipico commented Mar 2, 2026

Uh oh!

ematipico left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

OliverSpeir Mar 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

sarah11918 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

pkg-pr-new bot commented Mar 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ematipico left a comment

Choose a reason for hiding this comment

Uh oh!

matthewp commented Mar 11, 2026

Uh oh!

matthewp commented Mar 11, 2026

Uh oh!

matthewp commented Mar 11, 2026

Uh oh!

matthewp commented Mar 11, 2026

Uh oh!

matthewp commented Mar 11, 2026

Uh oh!

Uh oh!

sarah11918 left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

OliverSpeir commented Mar 2, 2026 •

edited

Loading

changeset-bot bot commented Mar 2, 2026 •

edited

Loading

codspeed-hq bot commented Mar 2, 2026 •

edited

Loading

OliverSpeir Mar 3, 2026 •

edited

Loading

pkg-pr-new bot commented Mar 10, 2026 •

edited

Loading

sarah11918 left a comment •

edited

Loading