Support prerendering inside of adapter runtimes #15077

matthewp · 2025-12-23T13:26:33Z

Needs cloudflare/workers-sdk#11697 before merge

Summary

Enable prerendering in non-Node runtimes.
Allow adapters to do prerendering by providing an implementation.
Keep the default Node-based prerenderer as a fallback when no adapter provides one.

What Changed

Added the AstroPrerenderer interface and setPrerenderer hook on astro:build:start to let adapters control prerendering.
Introduced a default prerenderer that uses the build app in Node when no custom prerenderer is set.
Cloudflare adapter now supplies a workerd-backed prerenderer.
- This runs a preview server and sends requests to generate pages.
Static build and generate flows now route prerendering through the new interface.

New API: AstroPrerenderer

Adapters can implement this interface to handle prerendering in their runtime of choice.

import type { AstroPrerenderer, PathWithRoute } from 'astro';
import type { RouteData } from 'astro';

export const myPrerenderer: AstroPrerenderer = {
  name: 'my-adapter:prerenderer',
  async setup() {
    // Start preview server or runtime sandbox here.
  },
  async getStaticPaths(): Promise<PathWithRoute[]> {
    // Return all static paths with their routes.
    return [];
  },
  async render(request: Request, routeData: RouteData): Promise<Response> {
    // Render a single request in the adapter runtime.
    return new Response('ok');
  },
  async teardown() {
    // Stop any servers or clean up resources.
  },
};

New Hook: setPrerenderer

Adapters can provide a prerenderer during the build.

export default function myAdapter() {
  return {
    name: '@my/adapter',
    hooks: {
      'astro:build:start'({ setPrerenderer }) {
        setPrerenderer(() => myPrerenderer);
      },
    },
  };
}

Example: Cloudflare Prerenderer

Cloudflare now starts a workerd-backed preview server and forwards prerender requests to it.

import { createCloudflarePrerenderer } from '@astrojs/cloudflare/prerenderer';

hooks: {
  'astro:build:start'({ setPrerenderer }) {
    setPrerenderer(() => createCloudflarePrerenderer({
      root: new URL('.', import.meta.url),
      serverDir: new URL('./dist/server/', import.meta.url),
      clientDir: new URL('./dist/client/', import.meta.url),
      base: '/',
      trailingSlash: 'ignore',
    }));
  },
}

Testing

pnpm --filter @astrojs/cloudflare test
All existing tests continue to pass.
New test fixture added to astro core to test setPrerenderer API directly.

Docs

Document custom prerenderers docs#13143

changeset-bot · 2025-12-23T13:26:38Z

🦋 Changeset detected

Latest commit: 6d0049b

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

github-actions · 2025-12-23T13:28:08Z

⚠️ Package Trust Level Decreased

Caution

Decreased trust levels may indicate a higher risk of supply chain attacks. Please review these changes carefully.

📦 Package	🔒 Before	🔓 After
@cloudflare/kv-asset-handler	trusted-with-provenance	none
@cloudflare/unenv-preset	trusted-with-provenance	none
workerd	trusted-with-provenance	none
miniflare	trusted-with-provenance	none
youch	provenance	none
@cloudflare/workerd-darwin-64	trusted-with-provenance	none
@cloudflare/workerd-darwin-arm64	trusted-with-provenance	none
@cloudflare/workerd-linux-64	trusted-with-provenance	none
@cloudflare/workerd-linux-arm64	trusted-with-provenance	none
@cloudflare/workerd-windows-64	trusted-with-provenance	none
wrangler	trusted-with-provenance	none

Move environment builds to top-level builder.buildApp for framework ownership, add post plugin with enforce:'post' for manifest injection and page generation. Enables proper coordination with platform plugins.

Adds a new prerenderer API allowing adapters to control how pages are prerendered. Key changes: - Add AstroPrerenderer interface with setup/getStaticPaths/render/teardown - Add setPrerenderer to astro:build:start hook - Create default prerenderer wrapping current Node-based behavior - Refactor generate.ts to use prerenderer interface - Add astro:static-paths virtual module for runtime getStaticPaths

…erer app.match() filters out prerendered routes by default, causing 404s

- Replace getStaticPaths function with StaticPaths class - Encapsulates RouteCache internally, adapters just pass app - Track pathname→route mapping to avoid route priority issues - Use app.getPathnameFromRequest for base handling - Fall back to app.match for static routes

Redirects don't have page modules in pageMap - pipeline method handles redirects and fallbacks properly.

getStaticPaths() now returns PathWithRoute[] instead of string[]. render() receives routeData from caller, eliminating path manipulation.

The map-based route lookup added complexity and broke i18n fallback tests. Reverting to pass routeData directly to render() as before.

codspeed-hq · 2026-01-20T19:57:14Z

Merging this PR will not alter performance

✅ 9 untouched benchmarks

_{Comparing workerd-prerender (6d0049b) with next (8983f17)}

matthewp · 2026-01-25T20:27:57Z

packages/astro/src/core/app/entrypoint.ts

-import { createConsoleLogger } from './logging.js';
-
-export function createApp(dev = import.meta.env.DEV): BaseApp {
-	if (dev) {


DevApp (and its deps) were being bundled in the prod build. We don't minify the server builds and so tree-shaking doesn't happen. Fix was to move to a virtual module.

packages/integrations/node/test/test-utils.js

.changeset/custom-prerenderer-api.md

florian-lefebvre · 2026-01-26T09:04:46Z

.changeset/custom-prerenderer-api.md

+}
+```
+
+Also adds the `astro:static-paths` virtual module, which exports a `StaticPaths` class for adapters to collect all prerenderable paths from within their target runtime.


This may also need an example

packages/astro/src/core/create-vite.ts

florian-lefebvre · 2026-01-26T09:11:29Z

packages/astro/src/types/public/integrations.ts

+	 * @param request - The request to render
+	 * @param routeData - The route data for this request
+	 */
+	render: (request: Request, routeData: RouteData) => Promise<Response>;


Should the shape match app.render(), ie. 2nd argument is an object with routeData and more stuff?

That makes sense. I don't think we need to add any more stuff right not, but having it an object would allow expansion in the future.

Updated this, thanks.

packages/astro/src/vite-plugin-css/index.ts

packages/integrations/cloudflare/src/index.ts

packages/integrations/cloudflare/virtual.d.ts

packages/internal-helpers/src/path.ts

florian-lefebvre · 2026-01-26T09:21:52Z

packages/astro/src/core/build/generate.ts

-		for (const routeData of pagesToGenerate) {
-			if (routeData.prerender) {
-				// i18n domains won't work with pre rendered routes at the moment, so we need to throw an error
-				if (app.manifest.i18n?.domains && Object.keys(app.manifest.i18n.domains).length > 0) {


I may be wrong but it seems this check has been completely removed, not moved

Added this back.

Co-authored-by: Florian Lefebvre <contact@florian-lefebvre.dev>

florian-lefebvre

I think it looks pretty good! My only concern is that we may design the API to be very specific to Cloudflare because it's the only adapter we know needs this. Not for this PR but before stable, it may be useful to try migrate all our adapters to the new APIs to see if we encounter limitations

ematipico

Blocking to avoid accidental merges, since it contains pkg.pr.new packages. I understand more or less the flow of the build.

Things that are unclear or I would like to see addressed:

More actionable errors. At the moment it's just "error occurred" without telling users what the could do (maybe using AstroError)
New entry points. I don't know what they are, but they don't seem to be internal things, so we should look for a more future-proof solution. Should we document them?
Tests for the new normalizePathname

ematipico · 2026-01-26T14:38:58Z

packages/astro/src/core/build/static-build.ts


-	// Inject manifest and content placeholders into extracted chunks
-	await runManifestInjection(opts, internals, extractedChunks);
+	settings.timer.end('SSR build');


Is this correct? Asking because with all the refactor, it's hard to see it

ematipico · 2026-01-26T14:43:12Z

packages/astro/src/core/build/static-build.ts

+				const ssrOutputs = viteBuildReturnToRollupOutputs(ssrOutput);
+				const ssrChunks = extractRelevantChunks(ssrOutputs, false);
+				ssrOutput = undefined as any;


Wouldn't it make more sense to have an if here? Plus, we assume SSR build always returns items.

Here's the change I suggest

let ssrOutput = undefined; if (settings.buildOutput === 'static') { ssrOutput = await builder.build(builder.environments[ASTRO_VITE_ENVIRONMENT_NAMES.ssr]) const ssrOutputs = viteBuildReturnToRollupOutputs(ssrOutput); const ssrChunks = extractRelevantChunks(ssrOutputs, false); ssrOutput = undefined as any; }

However, if this code was made like this for a specific reason, maybe we should add a comment

ematipico · 2026-01-26T14:47:12Z

packages/astro/src/vite-plugin-css/index.ts

 			name: MODULE_DEV_CSS_ALL,
+			applyToEnvironment(env) {
+				return (
+					env.name === ASTRO_VITE_ENVIRONMENT_NAMES.ssr ||


You might want to add astro too, which our second dev environment.

Where do we use the astro environment? I don't think I understand what its for.

AFAIK it's another runnable dev environment for when we can't use the ssr one, eg. when it's not runnable

We use this environment in content collections and fonts. It's used to import modules using runner.import.

Maybe now that we know of the existence of environment.fetchModule, we might not need that anymore

ematipico · 2026-01-26T14:48:26Z

packages/astro/package.json

+    "./app/entrypoint-dev": "./dist/core/app/entrypoint-dev.js",
+    "./app/entrypoint-prod": "./dist/core/app/entrypoint-prod.js",


Why not entrypoint/dev and entrypoint/prod?

ematipico · 2026-01-26T14:49:55Z

packages/astro/package.json

    "./app/entrypoint": "./dist/core/app/entrypoint.js",
+    "./app/entrypoint-dev": "./dist/core/app/entrypoint-dev.js",
+    "./app/entrypoint-prod": "./dist/core/app/entrypoint-prod.js",
+    "./app/manifest": "./dist/core/app/manifest.js",


Eventually we will have to document all these new entrypoints

I'll add a v6 task to review these and figure something out. A lot (if not most) of these are actually internal and are part of the export map because they need to be, but are loaded without the astro package. Maybe we need a ./internal/ folder or something to convey that.

I have some plans around that but I think that's not blocking for v6

A lot (if not most) of these are actually internal

I thought so. It's a weird situation. I don't mind keeping things internal. Should they be mentioned in the docs though?

ematipico · 2026-01-26T14:57:19Z

packages/integrations/cloudflare/src/prerenderer.ts

+			if (address && typeof address === 'object') {
+				serverUrl = `http://localhost:${address.port}`;
+			} else {
+				throw new Error('Failed to get preview server address');


We should provide an error message that tell the user how to fix the problem, or what to do in order to fix (e.g. file a bug).

ematipico · 2026-01-26T14:57:53Z

packages/integrations/cloudflare/src/prerenderer.ts

+
+		async getStaticPaths(): Promise<PathWithRoute[]> {
+			// Call the workerd endpoint to get static paths
+			const response = await fetch(`${serverUrl}/__astro_static_paths`, {


Another occurrence. Yeah we really should provide more generic, future proof functions

ematipico · 2026-01-26T14:58:21Z

packages/integrations/cloudflare/src/prerenderer.ts

+			});
+
+			if (!response.ok) {
+				throw new Error(`Failed to get static paths: ${response.statusText}`);


Better error message to tell the user what to do

ematipico · 2026-01-26T14:59:15Z

packages/integrations/cloudflare/src/prerenderer.ts

+		async teardown() {
+			if (previewServer) {
+				await previewServer.close();
+				previewServer = undefined;


Maybe lease a command explaining why we explicitly set undefined

ematipico · 2026-01-26T14:59:49Z

packages/internal-helpers/src/path.ts

+ * @param buildFormat - The build format ('file', 'directory', or 'preserve')
+ * @param trailingSlash - The trailing slash setting ('always', 'never', or 'ignore')
+ */
+export function normalizePathname(


Please add some tests

florian-lefebvre · 2026-01-26T21:21:32Z

I think the prerendering paths should only be available during prerendering, which I don't think is currently the case. Otherwise there may be security concerns?

ematipico · 2026-01-27T10:10:02Z

I think the prerendering paths should only be available during prerendering, which I don't think is currently the case. Otherwise there may be security concerns?

Not sure it's possible. The prendering uses the preview server as foundation, which means they are always available in a way

florian-lefebvre · 2026-01-27T10:13:39Z

Maybe there's a way to check it's in preview with an env variable or something like that

refactor to use buildApp

f079456

github-actions bot added the pkg: astro Related to the core `astro` package (scope) label Dec 23, 2025

matthewp and others added 6 commits December 23, 2025 08:54

fix build

68bdab4

remove any casting

b5dff96

Merge branch 'next' into workerd-prerender

6a25928

refactor: split buildApp into top-level config and post plugin

aa5fdc4

Move environment builds to top-level builder.buildApp for framework ownership, add post plugin with enforce:'post' for manifest injection and page generation. Enables proper coordination with platform plugins.

Merge branch 'next' into workerd-prerender

5334e9a

github-actions bot added the docs pr label Jan 15, 2026

matthewp added 8 commits January 15, 2026 11:57

Merge branch 'next' into workerd-prerender

74a9587

fix: pass allowPrerenderedRoutes=true when matching routes in prerend…

85f8835

…erer app.match() filters out prerendered routes by default, causing 404s

fix: use pipeline.getComponentByRoute for redirect handling

e5ae343

Redirects don't have page modules in pageMap - pipeline method handles redirects and fallbacks properly.

refactor: pass routeData to prerenderer.render() to avoid re-matching

0f7d44c

getStaticPaths() now returns PathWithRoute[] instead of string[]. render() receives routeData from caller, eliminating path manipulation.

fix: remove unused PathWithRoute import

d8fea9c

fix: add prerender conflict detection to generate.ts

429e6ec

fix: lint issues - type import and unused exports

460d4dd

matthewp mentioned this pull request Jan 20, 2026

hybrid sites broken in Cloudflare workers in Astro 6? #15237

Open

1 task

matthewp added 5 commits January 20, 2026 10:43

Fix API to not require routeData

ac16b4b

don't use own prerender entry when prerenderer defined already

f63cce7

Fix some more tests

3a68f22

Revert render(request) only approach, restore routeData parameter

4ed3c25

The map-based route lookup added complexity and broke i18n fallback tests. Reverting to pass routeData directly to render() as before.

Merge branch 'next' into workerd-prerender

9689b96

Get it working

ec39290

github-actions bot added the pkg: integration Related to any renderer integration (scope) label Jan 21, 2026

matthewp added 2 commits January 21, 2026 15:41

Merge branch 'next' into workerd-prerender

1a295f7

Fix build

c50b119

matthewp added 12 commits January 23, 2026 11:24

Fix lint

dc4eee1

Allow more process listeners

de1f9c9

Add some debug info for handles

fbde819

Preoptimize static-paths

a855fd3

use the exact module name

a2a3496

Expand when we do this

0fac7a7

no js

134ec8f

use the virtual module of course

54ed399

REmove debugging stuff

c397e54

Add a test

4b0f7ec

reorder entryType

81e2ed2

Add changesets

16834e2

matthewp mentioned this pull request Jan 25, 2026

Document custom prerenderers withastro/docs#13143

Open

matthewp commented Jan 25, 2026

View reviewed changes

packages/integrations/node/test/test-utils.js Outdated Show resolved Hide resolved

more fixes

05c0453

matthewp marked this pull request as ready for review January 25, 2026 20:32

florian-lefebvre reviewed Jan 26, 2026

View reviewed changes

matthewp and others added 6 commits January 26, 2026 08:10

Update packages/astro/src/core/create-vite.ts

35e102f

Co-authored-by: Florian Lefebvre <contact@florian-lefebvre.dev>

Update .changeset/custom-prerenderer-api.md

2bf127e

Co-authored-by: Florian Lefebvre <contact@florian-lefebvre.dev>

Use an options object.

02dcc4c

Directly pass Prerenderer

4f93cbc

PR comments

0507d17

Fix build

6d0049b

florian-lefebvre reviewed Jan 26, 2026

View reviewed changes

ematipico requested changes Jan 26, 2026

View reviewed changes

matthewp mentioned this pull request Jan 26, 2026

Add experimental prerenderWorker option cloudflare/workers-sdk#11697

Draft

6 tasks

		"./app/entrypoint-dev": "./dist/core/app/entrypoint-dev.js",
		"./app/entrypoint-prod": "./dist/core/app/entrypoint-prod.js",

Uh oh!

Support prerendering inside of adapter runtimes #15077

Are you sure you want to change the base?

Support prerendering inside of adapter runtimes #15077

Conversation

matthewp commented Dec 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What Changed

New API: AstroPrerenderer

New Hook: setPrerenderer

Example: Cloudflare Prerenderer

Testing

Docs

Uh oh!

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

Uh oh!

🦋 Changeset detected

Uh oh!

github-actions bot commented Dec 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ Package Trust Level Decreased

Uh oh!

codspeed-hq bot commented Jan 20, 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!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

florian-lefebvre left a comment

Choose a reason for hiding this comment

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!

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

matthewp commented Dec 23, 2025 •

edited

Loading

changeset-bot bot commented Dec 23, 2025 •

edited

Loading

github-actions bot commented Dec 23, 2025 •

edited

Loading

codspeed-hq bot commented Jan 20, 2026 •

edited

Loading