Add experimental `prerenderWorker` option by jamesopstad · Pull Request #11697 · cloudflare/workers-sdk

jamesopstad · 2025-12-18T13:04:44Z

Adds an experimental prerenderWorker option for defining a dedicated Worker for pre-rendering.

Example:

cloudflare({
  experimental: {
    prerenderWorker: {
      config(_, { entryWorkerConfig }) {
        return {
          ...entryWorkerConfig,
          name: "prerender",
          main: "./src/prerender.ts",
        };
      },
    },
  },
}),

Internally, the plugin now sets an environment variable during the build that indicates to the preview server that the prerender Worker should be used as the entry. This means that the Vite preview server can be used during the build to send requests to the prerender Worker.

Tests
- Tests included/updated
- Tests not necessary because:
Public documentation
- Cloudflare docs PR(s):
- Documentation not necessary because: experimental and should be undocumented for now
Wrangler V3 Backport
- Wrangler PR:
- Not necessary because: not a Wrangler change

A picture of a cute animal (not mandatory, but encouraged)

changeset-bot · 2025-12-18T13:04:48Z

🦋 Changeset detected

Latest commit: a740392

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

pkg-pr-new · 2025-12-18T13:08:15Z

create-cloudflare

npm i https://pkg.pr.new/create-cloudflare@11697

@cloudflare/kv-asset-handler

npm i https://pkg.pr.new/@cloudflare/kv-asset-handler@11697

miniflare

npm i https://pkg.pr.new/miniflare@11697

@cloudflare/pages-shared

npm i https://pkg.pr.new/@cloudflare/pages-shared@11697

@cloudflare/unenv-preset

npm i https://pkg.pr.new/@cloudflare/unenv-preset@11697

@cloudflare/vite-plugin

npm i https://pkg.pr.new/@cloudflare/vite-plugin@11697

@cloudflare/vitest-pool-workers

npm i https://pkg.pr.new/@cloudflare/vitest-pool-workers@11697

@cloudflare/workers-editor-shared

npm i https://pkg.pr.new/@cloudflare/workers-editor-shared@11697

@cloudflare/workers-utils

npm i https://pkg.pr.new/@cloudflare/workers-utils@11697

wrangler

npm i https://pkg.pr.new/wrangler@11697

commit: a740392

matthewp · 2026-01-26T19:04:17Z

We have this working in withastro/astro#15077

This change works for us.

claude · 2026-01-30T11:51:15Z

Claude finished @jamesopstad's task —— View job

Changeset Review

✅ All changesets look good

The changeset in .changeset/metal-planes-hammer.md:

✅ Version Type: Correctly marked as minor for a new configuration option
✅ Changelog Quality: Clear description with explicit note about experimental status
✅ Markdown Headers: No h1/h2/h3 headers used
✅ Experimental Features: Includes note that this is experimental and may change/be removed
✅ Package: Correctly targets @cloudflare/vite-plugin

jamesopstad · 2026-01-30T14:04:53Z

@@ -76,6 +79,8 @@ export function createBuildApp(
 			return;
 		}

+		// TODO: move static assets from the prerender environment to the client environment


I started working on this but it is quite complex and is not currently needed so I decided to leave it for now.

jamesopstad · 2026-01-30T14:06:05Z

@@ -166,6 +166,7 @@ function readWorkerConfig(
 	};
 }

+// TODO: separate prerender Worker warnings from auxiliary Worker warnings


This can also be left for now I think as in Astro the concept of a pre-render Worker will be invisible to the user.

devin-ai-integration

Devin Review found 1 potential issue.

View issue and 5 additional flags in Devin Review.

edmundhung · 2026-01-30T14:36:07Z

+		// This environment variable is used to indicate to the preview server that it is being run during a build
+		// We need to delete it here as, during testing, preview also runs in the same process after the build completes
+		// eslint-disable-next-line turbo/no-undeclared-env-vars
+		delete process.env.CLOUDFLARE_VITE_BUILD;


Just thinking out loud, would it be safer to clean up the env var through the vite plugin? Just in case our users run into the same problem?

I would like to do that but I'm not sure how. Any suggestions?

I can't figure out a reliable way to clean it up in the right timing as well :(

A brittle way to handle this would be setting the env var only if prerenderWorker is configured, then monkey-patching previewServer.close() to clean that up. 😅

Yeah, that is an option. The downside is that it relies on the preview server only being run once for pre-rendering. That's probably a safe assumption to make but I'm not sure. Let's leave for now and revisit.

edmundhung

Looking good. Just some nits.

devin-ai-integration

Devin Review found 1 new potential issue.

View issue and 9 additional flags in Devin Review.

…un during the build

workers-devprod added this to workers-sdk Dec 18, 2025

github-project-automation Bot moved this to Untriaged in workers-sdk Dec 18, 2025

jamesopstad force-pushed the james/prerender-worker branch 5 times, most recently from bae5826 to 8033489 Compare December 19, 2025 09:49

matthewp mentioned this pull request Jan 22, 2026

Support prerendering inside of adapter runtimes withastro/astro#15077

Merged

jamesopstad force-pushed the james/prerender-worker branch from 8033489 to 8e303f7 Compare January 30, 2026 11:50

jamesopstad force-pushed the james/prerender-worker branch from 8e303f7 to a6a6539 Compare January 30, 2026 14:03

jamesopstad marked this pull request as ready for review January 30, 2026 14:03

jamesopstad requested a review from a team as a code owner January 30, 2026 14:03

jamesopstad commented Jan 30, 2026

View reviewed changes

devin-ai-integration Bot reviewed Jan 30, 2026

View reviewed changes

Comment thread packages/vite-plugin-cloudflare/src/context.ts

edmundhung reviewed Jan 30, 2026

View reviewed changes

ascorbic approved these changes Jan 30, 2026

View reviewed changes

github-project-automation Bot moved this from Untriaged to Approved in workers-sdk Jan 30, 2026

edmundhung approved these changes Jan 30, 2026

View reviewed changes

Comment thread packages/vite-plugin-cloudflare/src/plugin-config.ts Outdated

Comment thread packages/vite-plugin-cloudflare/src/plugin-config.ts Outdated

devin-ai-integration Bot reviewed Jan 30, 2026

View reviewed changes

Comment thread packages/vite-plugin-cloudflare/src/build.ts

jamesopstad added 6 commits January 30, 2026 15:58

Add experimental.prerenderWorker option to plugin config

ff083e9

Ensure prerender Worker is built for assets only projects

e1f6b02

Handle prerender environment in output config plugin

87b00d8

Use prerender Worker as the entry Worker in preview when preview is r…

c55214e

…un during the build

Add prerendering playground and tests

1b4694c

Add changeset

d4cd297

jamesopstad added 3 commits January 30, 2026 15:58

Fix early return in isChildEnvironment method

888132a

Remove unused isPrerender property

1b57ad8

Check if fallback build is needed for assets-only projects

a740392

jamesopstad force-pushed the james/prerender-worker branch from a12560b to a740392 Compare January 30, 2026 15:58

jamesopstad merged commit 67a4ab1 into main Jan 30, 2026
55 of 59 checks passed

jamesopstad deleted the james/prerender-worker branch January 30, 2026 17:34

github-project-automation Bot moved this from Approved to Done in workers-sdk Jan 30, 2026

workers-devprod mentioned this pull request Jan 30, 2026

Version Packages #12266

Merged

Conversation

jamesopstad commented Dec 18, 2025 • edited by devin-ai-integration Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot Bot commented Dec 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

pkg-pr-new Bot commented Dec 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

matthewp commented Jan 26, 2026

Uh oh!

claude Bot commented Jan 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changeset Review

Uh oh!

jamesopstad Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

jamesopstad Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

edmundhung Jan 30, 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!

jamesopstad Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

edmundhung Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

edmundhung Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

jamesopstad Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

edmundhung left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

devin-ai-integration Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

jamesopstad commented Dec 18, 2025 •

edited by devin-ai-integration Bot

Loading

changeset-bot Bot commented Dec 18, 2025 •

edited

Loading

pkg-pr-new Bot commented Dec 18, 2025 •

edited

Loading

claude Bot commented Jan 30, 2026 •

edited

Loading

edmundhung Jan 30, 2026 •

edited

Loading