Extract Pages functions build logic into its own package

.changeset/extract-pages-functions.md

@@ -0,0 +1,17 @@
+---
+"@cloudflare/pages-functions": minor
+---
+
+Add @cloudflare/pages-functions package
+
+Extracts the Pages functions-to-worker compilation logic from wrangler into a standalone package.
+
+This enables converting a Pages functions directory into a deployable worker entrypoint, which is needed for the Autoconfig Pages work where `wrangler deploy` should "just work" for Pages projects.
+
+```ts
+import { compileFunctions } from "@cloudflare/pages-functions";
+
+const result = await compileFunctions("./functions");
+// result.code - generated worker entrypoint
+// result.routesJson - _routes.json for Pages deployment
+```

fixtures/pages-functions-test/README.md

@@ -0,0 +1,35 @@
+# Pages Functions Test Fixture
+
+Test fixture for `@cloudflare/pages-functions` package.
+
+## Usage
+
+From the workers-sdk root:
+
+```bash
+# Build the pages-functions package first
+pnpm --filter @cloudflare/pages-functions build
+
+# Install deps for this fixture
+pnpm --filter pages-functions-test install
+
+# Compile functions -> worker, then bundle, then run dev
+pnpm --filter pages-functions-test dev
+```
+
+## What it does
+
+1. `build.mjs` uses `compileFunctions()` to compile `functions/` into `dist/worker.js`
+2. esbuild bundles `dist/worker.js` (with path-to-regexp) into `dist/bundled.js`
+3. wrangler runs the bundled worker
+
+## Test endpoints
+
+- `GET /` - Index route
+- `GET /api/hello` - Static API route
+- `POST /api/hello` - POST handler
+- `GET /api/:id` - Dynamic route
+- `PUT /api/:id` - Update handler
+- `DELETE /api/:id` - Delete handler
+
+All routes go through the root middleware which adds `X-Middleware: active` header.

fixtures/pages-functions-test/_routes.json

@@ -0,0 +1,6 @@
+{
+	"version": 1,
+	"description": "Generated by @cloudflare/pages-functions",
+	"include": ["/*"],
+	"exclude": []
+}

fixtures/pages-functions-test/build.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+/**
+ * Build script that uses @cloudflare/pages-functions to compile
+ * the functions directory into a worker entrypoint.
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { compileFunctions } from "@cloudflare/pages-functions";
+
+// Ensure dist directory exists
+mkdirSync("./dist", { recursive: true });
+
+// Compile the functions directory
+const result = await compileFunctions("./functions");
+
+// Write the generated worker entrypoint
+writeFileSync("./dist/worker.js", result.code);
+console.log("✓ Generated dist/worker.js");
+
+// Write _routes.json
+writeFileSync("./_routes.json", JSON.stringify(result.routesJson, null, 2));
+console.log("✓ Generated _routes.json");
+
+console.log("\nRoutes:");
+for (const route of result.routes) {
+	const method = route.method || "ALL";
+	console.log(`  ${method.padEnd(6)} ${route.routePath}`);
+}

fixtures/pages-functions-test/functions/_middleware.ts

@@ -0,0 +1,5 @@
+export const onRequest = async (context) => {
+	const response = await context.next();
+	response.headers.set("X-Middleware", "active");
+	return response;
+};

fixtures/pages-functions-test/functions/api/[id].ts

@@ -0,0 +1,15 @@
+export const onRequestGet = (context) => {
+	const { id } = context.params;
+	return Response.json({ message: `Getting item ${id}` });
+};
+
+export const onRequestPut = async (context) => {
+	const { id } = context.params;
+	const body = await context.request.json();
+	return Response.json({ message: `Updating item ${id}`, data: body });
+};
+
+export const onRequestDelete = (context) => {
+	const { id } = context.params;
+	return Response.json({ message: `Deleted item ${id}` });
+};

fixtures/pages-functions-test/functions/api/hello.ts

@@ -0,0 +1,11 @@
+export const onRequestGet = () => {
+	return Response.json({ message: "Hello from GET /api/hello" });
+};
+
+export const onRequestPost = async (context) => {
+	const body = await context.request.json();
+	return Response.json({
+		message: "Hello from POST /api/hello",
+		received: body,
+	});
+};

fixtures/pages-functions-test/functions/index.ts

@@ -0,0 +1,3 @@
+export const onRequest = () => {
+	return new Response("Hello from the index!");
+};

fixtures/pages-functions-test/package.json

@@ -0,0 +1,14 @@
+{
+	"name": "@fixture/pages-functions-test",
+	"private": true,
+	"scripts": {
+		"build": "node build.mjs",
+		"dev": "node build.mjs && wrangler dev"
+	},
+	"dependencies": {
+		"@cloudflare/pages-functions": "workspace:*"
+	},
+	"devDependencies": {
+		"wrangler": "workspace:*"
+	}
+}

fixtures/pages-functions-test/turbo.json

@@ -0,0 +1,10 @@
+{
+	"$schema": "http://turbo.build/schema.json",
+	"extends": ["//"],
+	"tasks": {
+		"build": {
+			"dependsOn": ["@cloudflare/pages-functions#build"],
+			"outputs": ["dist/**"]
+		}
+	}
+}

fixtures/pages-functions-test/wrangler.jsonc

@@ -0,0 +1,5 @@
+{
+	"name": "pages-functions-test",
+	"main": "dist/worker.js",
+	"compatibility_date": "2026-01-20",
+}

packages/pages-functions/README.md

@@ -0,0 +1,94 @@
+# @cloudflare/pages-functions
+
+Compile a Pages functions directory into a deployable worker entrypoint.
+
+## Installation
+
+```bash
+npm install @cloudflare/pages-functions
+```
+
+## Usage
+
+```typescript
+import * as fs from "node:fs/promises";
+import { compileFunctions } from "@cloudflare/pages-functions";
+
+const result = await compileFunctions("./functions", {
+	fallbackService: "ASSETS",
+});
+
+// Write the generated worker entrypoint
+await fs.writeFile("worker.js", result.code);
+
+// Write _routes.json for Pages deployment
+await fs.writeFile("_routes.json", JSON.stringify(result.routesJson, null, 2));
+```
+
+## API
+
+### `compileFunctions(functionsDirectory, options?)`
+
+Compiles a Pages functions directory into a worker entrypoint.
+
+#### Parameters
+
+- `functionsDirectory` (string): Path to the functions directory
+- `options` (object, optional):
+  - `baseURL` (string): Base URL prefix for all routes. Default: `"/"`
+  - `fallbackService` (string): Fallback service binding name. Default: `"ASSETS"`
+
+#### Returns
+
+A `Promise<CompileResult>` with:
+
+- `code` (string): Generated JavaScript worker entrypoint
+- `routes` (RouteConfig[]): Parsed route configuration
+- `routesJson` (RoutesJSONSpec): `_routes.json` content for Pages deployment
+
+## Functions Directory Structure
+
+The functions directory uses file-based routing:
+
+```
+functions/
+├── index.ts              # Handles /
+├── _middleware.ts        # Middleware for all routes
+├── api/
+│   ├── index.ts          # Handles /api
+│   ├── [id].ts           # Handles /api/:id
+│   └── [[catchall]].ts   # Handles /api/*
+```
+
+### Route Parameters
+
+- `[param]` - Dynamic parameter (e.g., `[id].ts` → `/api/:id`)
+- `[[catchall]]` - Catch-all parameter (e.g., `[[path]].ts` → `/api/:path*`)
+
+### Exports
+
+Export handlers from your function files:
+
+```typescript
+// Handle all methods
+export const onRequest = (context) => new Response("Hello");
+
+// Handle specific methods
+export const onRequestGet = (context) => new Response("GET");
+export const onRequestPost = (context) => new Response("POST");
+```
+
+## Generated Output
+
+The generated code:
+
+1. Imports all function handlers
+2. Creates a route configuration array
+3. Includes the Pages Functions runtime (inlined)
+4. Exports a default handler that routes requests
+
+The output requires `path-to-regexp` as a runtime dependency (resolved during bundling).
+
+## License
+
+MIT OR Apache-2.0

packages/pages-functions/__tests__/codegen.test.ts

@@ -0,0 +1,93 @@
+import { describe, expect, it } from "vitest";
+import { generateWorkerEntrypoint } from "../src/codegen.js";
+import type { RouteConfig } from "../src/types.js";
+
+describe("codegen", () => {
+	describe("generateWorkerEntrypoint", () => {
+		it("generates imports and routes array", () => {
+			const routes: RouteConfig[] = [
+				{
+					routePath: "/api/:id",
+					mountPath: "/api",
+					method: "GET",
+					module: ["api/[id].ts:onRequestGet"],
+				},
+			];
+
+			const code = generateWorkerEntrypoint(routes, {
+				functionsDirectory: "/project/functions",
+				fallbackService: "ASSETS",
+			});
+
+			// path-to-regexp is imported from its resolved absolute path
+			expect(code).toMatch(/import \{ match \} from ".*path-to-regexp.*"/);
+			expect(code).toContain("import { onRequestGet as");
+			expect(code).toContain('routePath: "/api/:id"');
+			expect(code).toContain('mountPath: "/api"');
+			expect(code).toContain('method: "GET"');
+			expect(code).toContain(
+				"createPagesHandler(routes, __FALLBACK_SERVICE__)"
+			);
+		});
+
+		it("handles middleware routes", () => {
+			const routes: RouteConfig[] = [
+				{
+					routePath: "/",
+					mountPath: "/",
+					middleware: ["_middleware.ts:onRequest"],
+					module: ["index.ts:onRequest"],
+				},
+			];
+
+			const code = generateWorkerEntrypoint(routes, {
+				functionsDirectory: "/project/functions",
+			});
+
+			expect(code).toContain("middlewares: [");
+			expect(code).toContain("modules: [");
+		});
+
+		it("generates unique identifiers for duplicate export names", () => {
+			const routes: RouteConfig[] = [
+				{
+					routePath: "/a",
+					mountPath: "/a",
+					module: ["a.ts:onRequest"],
+				},
+				{
+					routePath: "/b",
+					mountPath: "/b",
+					module: ["b.ts:onRequest"],
+				},
+			];
+
+			const code = generateWorkerEntrypoint(routes, {
+				functionsDirectory: "/project/functions",
+			});
+
+			// Should have two different identifiers
+			const matches = code.match(/import \{ onRequest as (\w+) \}/g);
+			expect(matches).toHaveLength(2);
+		});
+
+		it("includes runtime code", () => {
+			const routes: RouteConfig[] = [
+				{
+					routePath: "/",
+					mountPath: "/",
+					module: ["index.ts:onRequest"],
+				},
+			];
+
+			const code = generateWorkerEntrypoint(routes, {
+				functionsDirectory: "/project/functions",
+			});
+
+			// Runtime code should be inlined
+			expect(code).toContain("function* executeRequest");
+			expect(code).toContain("function createPagesHandler");
+			expect(code).toContain("cloneResponse");
+		});
+	});
+});