Support prerendering inside of adapter runtimes (#15077)

* refactor to use buildApp

* fix build

* remove any casting

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

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.

* feat: add AstroPrerenderer interface for adapter-controlled prerendering

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

* fix: pass allowPrerenderedRoutes=true when matching routes in prerenderer

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

* refactor: StaticPaths class for cleaner prerenderer API

- 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

* fix: use pipeline.getComponentByRoute for redirect handling

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

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

* fix: remove unused PathWithRoute import

* fix: add prerender conflict detection to generate.ts

* fix: lint issues - type import and unused exports

* Fix API to not require routeData

* don't use own prerender entry when prerenderer defined already

* Fix some more tests

* Revert render(request) only approach, restore routeData parameter

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

* Get it working

* Fix build

* fix lint issues

* bad merge thing

* skipping tests

* temp skip netlify

* exclude cloudflare for test

* Add some logging

* Add unhandled rejection logging

* Don't run CSS plugin in prerender

* Some changes

* Fix weird resolution

* Fix lint

* Allow more process listeners

* Add some debug info for handles

* Preoptimize static-paths

* use the exact module name

* Expand when we do this

* no js

* use the virtual module of course

* REmove debugging stuff

* Add a test

* reorder entryType

* Add changesets

* more fixes

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

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

* Update .changeset/custom-prerenderer-api.md

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

* Use an options object.

* Directly pass Prerenderer

* PR comments

* Fix build

* Reorganize timers and build block

* Add astro environment to dev CSS plugin

* Add pnpm override to force single vite version (7.3.1)

* Move entrypoint files to entrypoint/dev and entrypoint/prod

* Refactor prerender endpoints into separate utility module

- Create prerender.ts with documented helper functions
- Add isPrerender flag to virtual cloudflare config (only true in prerender env)
- Guard prerender endpoints so they're only active during build
- Use helper functions for cleaner, more readable handler code

* Improve error message for prerender server startup failure

* Use shared endpoint constants in prerenderer

* Improve error message for static paths fetch failure

* Add comment explaining previewServer cleanup

* Add tests for normalizePathname function

* Upgrade to latest cloudflare vite plugin

* Remove the override

* dedupe

* fix types

* Move constants into constants file

* Fix prerendered styles in cloudflare

* Use astro.config for typing

* Add back missing i18n fallback code

* Add comment explaining why prerender is excluded

* Update .changeset/custom-prerenderer-api.md

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

* Add a better comment

---------

Co-authored-by: Florian Lefebvre <contact@florian-lefebvre.dev>
Co-authored-by: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com>

Author: 3 people

.changeset/cloudflare-workerd-prerender.md

@@ -0,0 +1,7 @@
+---
+'@astrojs/cloudflare': minor
+---
+
+Adds support for prerendering pages using the workerd runtime.
+
+The Cloudflare adapter now uses the new `setPrerenderer()` API to prerender pages via HTTP requests to a local preview server running workerd, instead of using Node.js. This ensures prerendered pages are built using the same runtime that serves them in production.

.changeset/custom-prerenderer-api.md

@@ -0,0 +1,61 @@
+---
+'astro': minor
+---
+
+Updates the Integration API to add `setPrerenderer()` to the `astro:build:start` hook, allowing adapters to provide custom prerendering logic.
+
+The new API accepts either an `AstroPrerenderer` object directly, or a factory function that receives the default prerenderer:
+
+```js
+'astro:build:start': ({ setPrerenderer }) => {
+  setPrerenderer((defaultPrerenderer) => ({
+    name: 'my-prerenderer',
+    async setup() {
+      // Optional: called once before prerendering starts
+    },
+    async getStaticPaths() {
+      // Returns array of { pathname: string, route: RouteData }
+      return defaultPrerenderer.getStaticPaths();
+    },
+    async render(request, { routeData }) {
+      // request: Request
+      // routeData: RouteData
+      // Returns: Response
+    },
+    async teardown() {
+      // Optional: called after all pages are prerendered
+    }
+  }));
+}
+```
+
+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 is useful when implementing a custom prerenderer that runs in a non-Node environment:
+
+```js
+// In your adapter's request handler (running in target runtime)
+import { App } from 'astro/app';
+import { StaticPaths } from 'astro:static-paths';
+
+export function createApp(manifest) {
+  const app = new App(manifest);
+  
+  return {
+    async fetch(request) {
+      const { pathname } = new URL(request.url);
+      
+      // Expose endpoint for prerenderer to get static paths
+      if (pathname === '/__astro_static_paths') {
+        const staticPaths = new StaticPaths(app);
+        const paths = await staticPaths.getAll();
+        return new Response(JSON.stringify({ paths }));
+      }
+      
+      // Normal request handling
+      return app.render(request);
+    }
+  };
+}
+```
+
+See the [adapter reference](https://v6.docs.astro.build/en/reference/adapter-reference/#custom-prerenderer) for more details on implementing a custom prerenderer.
+

.changeset/internal-helpers-normalize-pathname.md

@@ -0,0 +1,5 @@
+---
+'@astrojs/internal-helpers': minor
+---
+
+Adds `normalizePathname()` utility function for normalizing URL pathnames to match the canonical form used by route generation.

packages/astro/client.d.ts

@@ -286,6 +286,10 @@ declare module 'astro:ssr-manifest' {
 	export const manifest: import('./dist/types/public/internal.js').SSRManifest;
 }
 
+declare module 'astro:static-paths' {
+	export const StaticPaths: typeof import('./dist/runtime/prerender/static-paths.js').StaticPaths;
+}
+
 // Everything below are Vite's types (apart from image types, which are in `client.d.ts`)
 
 // CSS modules

packages/astro/dev-only.d.ts

@@ -77,3 +77,7 @@ declare module 'virtual:astro:dev-css-all' {
 	import type { ImportedDevStyles } from './src/types/astro.js';
 	export const devCSSMap: Map<string, () => Promise<{ css: Set<ImportedDevStyles> }>>;
 }
+
+declare module 'virtual:astro:app' {
+	export function createApp(): import('./src/core/app/base.js').BaseApp;
+}

packages/astro/package.json

@@ -52,6 +52,9 @@
     "./app": "./dist/core/app/index.js",
     "./app/node": "./dist/core/app/node.js",
     "./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",
     "./entrypoints/prerender": "./dist/entrypoints/prerender.js",
     "./entrypoints/legacy": "./dist/entrypoints/legacy.js",
     "./client/*": "./dist/runtime/client/*",

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

@@ -1,38 +1 @@
-import { manifest } from 'virtual:astro:manifest';
-import { App } from './app.js';
-import type { BaseApp } from './base.js';
-import { DevApp } from './dev/app.js';
-import { createConsoleLogger } from './logging.js';
-import type { RouteInfo } from './types.js';
-import type { RoutesList } from '../../types/astro.js';
-
-let currentDevApp: DevApp | null = null;
-
-export function createApp(dev = import.meta.env.DEV): BaseApp {
-	if (dev) {
-		const logger = createConsoleLogger(manifest.logLevel);
-		currentDevApp = new DevApp(manifest, true, logger);
-
-		// Listen for route updates via HMR
-		if (import.meta.hot) {
-			import.meta.hot.on('astro:routes-updated', async () => {
-				if (!currentDevApp) return;
-				try {
-					// Re-import the routes module to get fresh routes
-					const { routes: newRoutes } = await import('virtual:astro:routes');
-					const newRoutesList: RoutesList = {
-						routes: newRoutes.map((r: RouteInfo) => r.routeData),
-					};
-					currentDevApp.updateRoutes(newRoutesList);
-				} catch (e: any) {
-					// Log error but don't crash - route updates are non-critical
-					logger.error('router', `Failed to update routes via HMR:\n ${e}`);
-				}
-			});
-		}
-
-		return currentDevApp;
-	} else {
-		return new App(manifest);
-	}
-}
+export { createApp } from 'virtual:astro:app';

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

@@ -0,0 +1,33 @@
+import { manifest } from 'virtual:astro:manifest';
+import type { BaseApp } from '../base.js';
+import { DevApp } from '../dev/app.js';
+import { createConsoleLogger } from '../logging.js';
+import type { RouteInfo } from '../types.js';
+import type { RoutesList } from '../../../types/astro.js';
+
+let currentDevApp: DevApp | null = null;
+
+export function createApp(): BaseApp {
+	const logger = createConsoleLogger(manifest.logLevel);
+	currentDevApp = new DevApp(manifest, true, logger);
+
+	// Listen for route updates via HMR
+	if (import.meta.hot) {
+		import.meta.hot.on('astro:routes-updated', async () => {
+			if (!currentDevApp) return;
+			try {
+				// Re-import the routes module to get fresh routes
+				const { routes: newRoutes } = await import('virtual:astro:routes');
+				const newRoutesList: RoutesList = {
+					routes: newRoutes.map((r: RouteInfo) => r.routeData),
+				};
+				currentDevApp.updateRoutes(newRoutesList);
+			} catch (e: any) {
+				// Log error but don't crash - route updates are non-critical
+				logger.error('router', `Failed to update routes via HMR:\n ${e}`);
+			}
+		});
+	}
+
+	return currentDevApp;
+}

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

@@ -0,0 +1,7 @@
+import { manifest } from 'virtual:astro:manifest';
+import type { BaseApp } from '../base.js';
+import { App } from '../app.js';
+
+export function createApp(): BaseApp {
+	return new App(manifest);
+}

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

@@ -10,6 +10,8 @@ import type {
 	SerializedRouteInfo,
 } from './types.js';
 
+export type { SerializedRouteData } from '../../types/astro.js';
+
 export function deserializeManifest(
 	serializedManifest: SerializedSSRManifest,
 	routesList?: RoutesList,