Extract Pages functions build logic into its own package #12027

ascorbic · 2026-01-21T11:59:28Z

Fixes https://jira.cfdata.org/browse/DEVX-2407

Extracts the Pages functions-to-worker compilation logic from wrangler into a standalone @cloudflare/pages-functions package.

This is part of the Autoconfig Pages work (RM-26054). The goal is to enable converting Pages projects with a functions directory into Workers projects that can be deployed with the standard wrangler deploy flow.

What this package does

Takes a functions directory:

functions/
├── _middleware.ts
├── index.ts
└── api/
    └── [id].ts

And compiles it to a worker entrypoint that can be bundled and deployed like any regular worker:

import { compileFunctions } from "@cloudflare/pages-functions";

const result = await compileFunctions("./functions");
// result.code - generated worker entrypoint
// result.routes - parsed route configuration
// result.routesJson - _routes.json for Pages deployment

What's extracted

Filepath routing (scanning functions dir, extracting exports)
Route configuration and sorting
Routes transformation (_routes.json generation)
Routes consolidation and optimization
Runtime code (route matching, middleware chain execution)
Code generation (produces a bundleable worker entrypoint)

What stays in wrangler

Bundling (esbuild integration via bundleWorker)
The assets: import plugin
CLI commands (pages functions build, etc.)
Deployment logic

Test coverage

71 unit tests covering filepath routing, codegen, route transformation
9 runtime tests using vitest-pool-workers that test actual request handling in the workers runtime (route matching, middleware execution, 404 handling)

Next steps

A follow-up PR will wire this into wrangler's buildFunctions() to replace the duplicated code.

Tests
- Tests included/updated
- Automated tests not possible - manual testing has been completed as follows:
- Additional testing not necessary because:
Public documentation
- Cloudflare docs PR(s):
- Documentation not necessary because: Internal package, README included

Extracts the Pages functions-to-worker compilation logic from wrangler into a standalone package. This is the first step towards Autoconfig Pages (DEVX-2407).

changeset-bot · 2026-01-21T11:59:32Z

🦋 Changeset detected

Latest commit: 22dfdee

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

- Resolve path-to-regexp path at codegen time using require.resolve() - Wrangler/esbuild bundles it when building the final worker - Remove esbuild dependency (no longer needed for bundling) - Return 404 when no route matches and fallback binding unavailable - Add vitest-pool-workers runtime tests (9 tests covering route matching, middleware execution, and 404 handling)

Manual test fixture for the @cloudflare/pages-functions package. Demonstrates compiling a functions directory and running with wrangler.

devin-ai-integration

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 4 additional flags.

fixtures/pages-functions-test/README.md

packages/pages-functions/src/index.ts

packages/pages-functions/README.md

dario-piotrowicz · 2026-01-21T18:43:45Z

packages/pages-functions/tsconfig.json

+	"extends": "@cloudflare/workers-tsconfig",
+	"compilerOptions": {
+		"module": "NodeNext",
+		"moduleResolution": "NodeNext",


is there any reason why this is NodeNext?
(this seems to me quite inconsistent with the monorepo where Bundler is generally used)

I tried switching to bundler, but had to change back so the CLI would work without bundling.

dario-piotrowicz · 2026-01-21T18:44:44Z

packages/pages-functions/src/routes-transformation.ts

+import {
+	consolidateRoutes,
+	MAX_FUNCTIONS_ROUTES_RULES,
+} from "./routes-consolidation.js";


the .js imports are, I believe, very inconsistent with the monorepo (because NodeNext is used as the moduleResolution) is this intentional?

- Change compileFunctions() to accept project directory instead of functions directory - Add functionsDir option (default: 'functions') - Add pages-functions CLI for command-line compilation - Update README with CLI documentation and accurate API reference - Restructure test fixtures to match project-based API

devin-ai-integration

Devin Review found 1 new potential issue.

View issue and 8 additional flags in Devin Review.

packages/pages-functions/package.json

devin-ai-integration

Devin Review found 1 new potential issue.

View issue and 11 additional flags in Devin Review.

packages/pages-functions/src/cli.ts

devin-ai-integration

Devin Review found 1 new potential issue.

View issue and 12 additional flags in Devin Review.

devin-ai-integration · 2026-01-22T11:51:02Z

packages/pages-functions/src/identifiers.ts

+	"undefined",
+];
+
+const reservedKeywordRegex = new RegExp(`^${RESERVED_KEYWORDS.join("|")}$`);


🟡 Incorrect regex construction causes valid identifiers to be rejected

The reservedKeywordRegex in identifiers.ts is incorrectly constructed using ^${RESERVED_KEYWORDS.join("|")}$ which produces the pattern ^do|if|in|for|...|undefined$. Due to regex operator precedence, the ^ anchor only applies to the first alternative ("do") and the $ anchor only applies to the last alternative ("undefined"). The middle alternatives match anywhere in the string.

This causes identifiers like "doSomething", "forLoop", or "infinity" to incorrectly match as reserved keywords:

const reservedKeywordRegex = new RegExp(`^${RESERVED_KEYWORDS.join("|"))}$`); reservedKeywordRegex.test("doSomething"); // true (should be false) reservedKeywordRegex.test("forLoop"); // true (should be false)

The fix should wrap the alternation in a group: `^(${RESERVED_KEYWORDS.join("|")})

While this bug is copied from the existing wrangler code (packages/wrangler/src/pages/functions/identifiers.ts:55), it's being added as new code in this package. In practice, the bug has limited impact because the code only processes exports matching onRequest* pattern, which don't start with reserved keywords. However, any future use of isValidIdentifier() with identifiers starting with short reserved keywords would fail incorrectly.

Recommendation: Change line 59 to: const reservedKeywordRegex = new RegExp(\^(${RESERVED_KEYWORDS.join("|")})$`);` to properly group the alternation.

Was this helpful? React with 👍 or 👎 to provide feedback.

[pages-functions] Add @cloudflare/pages-functions package

31442b8

Extracts the Pages functions-to-worker compilation logic from wrangler into a standalone package. This is the first step towards Autoconfig Pages (DEVX-2407).

workers-devprod added this to workers-sdk Jan 21, 2026

github-project-automation bot moved this to Untriaged in workers-sdk Jan 21, 2026

ascorbic added 3 commits January 21, 2026 12:07

Add scripts/deps.ts for external dependencies

eebf5c1

Add @cloudflare/pages-functions to validate-changesets test

3ea65c8

ascorbic force-pushed the pages-functions-package branch from 5b356a3 to 99322a1 Compare January 21, 2026 15:04

Add pages-functions-test fixture

e437fac

Manual test fixture for the @cloudflare/pages-functions package. Demonstrates compiling a functions directory and running with wrangler.

ascorbic force-pushed the pages-functions-package branch from 99322a1 to e437fac Compare January 21, 2026 15:13

ascorbic added 2 commits January 21, 2026 15:31

Fix CI checks: add turbo.json, exclude runtime tests from lint/type

c296541

Format _routes.json with tabs

32327d7

ascorbic changed the title ~~[pages-functions] Extract Pages functions build logic into its own package~~ Extract Pages functions build logic into its own package Jan 21, 2026

ascorbic marked this pull request as ready for review January 21, 2026 16:12

ascorbic requested a review from a team as a code owner January 21, 2026 16:12

devin-ai-integration bot reviewed Jan 21, 2026

View reviewed changes

Merge branch 'main' into pages-functions-package

066101c

dario-piotrowicz reviewed Jan 21, 2026

View reviewed changes

devin-ai-integration bot reviewed Jan 22, 2026

View reviewed changes

packages/pages-functions/package.json Show resolved Hide resolved

ascorbic added 3 commits January 22, 2026 11:14

Fix fixture to use direct node invocation for CLI

4ba0a87

Update lockfile

b9b5e30

Format _routes.json

36fee8d

devin-ai-integration bot reviewed Jan 22, 2026

View reviewed changes

packages/pages-functions/src/cli.ts Outdated Show resolved Hide resolved

ascorbic added 4 commits January 22, 2026 11:22

Gitignore generated files in fixture

a9f328b

Use node:util parseArgs for CLI argument parsing

0ec790b

Add esbuild to dependencies

430704c

Remove functionsDir option - directory is always 'functions'

7dc9eb5

devin-ai-integration bot reviewed Jan 22, 2026

View reviewed changes

Remove outdated fixture README

4b203f8

ascorbic and others added 12 commits January 22, 2026 11:58

Use bare import for path-to-regexp instead of absolute path

9bb2109

Update README to clarify path-to-regexp dependency

cc8dc03

Remove path-to-regexp dep, document it as user requirement

5b930e5

Remove unused deps script

cd3f55b

Add path-to-regexp to devDependencies for tests

8a569e9

Switch to bundler moduleResolution, remove .js extensions

f304d4c

Revert to NodeNext moduleResolution for Node ESM compatibility

a394015

Add deps.ts for external dependency check

b7f1f77

Merge branch 'main' into pages-functions-package

74ba005

Fix reserved keyword regex to properly group alternation

1643b04

Merge branch 'main' into pages-functions-package

b2f66b2

Lock

22dfdee

ascorbic requested a review from dario-piotrowicz January 23, 2026 11:51

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Extract Pages functions build logic into its own package #12027

Extract Pages functions build logic into its own package #12027

ascorbic commented Jan 21, 2026 •

edited by devin-ai-integration bot

Loading

Uh oh!

changeset-bot bot commented Jan 21, 2026 •

edited

Loading

Uh oh!

devin-ai-integration bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dario-piotrowicz Jan 21, 2026

Uh oh!

ascorbic Jan 23, 2026 •

edited

Loading

Uh oh!

dario-piotrowicz Jan 21, 2026

Uh oh!

devin-ai-integration bot left a comment

Uh oh!

Uh oh!

devin-ai-integration bot left a comment

Uh oh!

Uh oh!

devin-ai-integration bot left a comment

Uh oh!

devin-ai-integration bot Jan 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Extract Pages functions build logic into its own package #12027

Are you sure you want to change the base?

Extract Pages functions build logic into its own package #12027

Conversation

ascorbic commented Jan 21, 2026 • edited by devin-ai-integration bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What this package does

What's extracted

What stays in wrangler

Test coverage

Next steps

Uh oh!

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

Uh oh!

🦋 Changeset detected

Uh oh!

devin-ai-integration bot left a comment

Choose a reason for hiding this comment

✅ Devin Review: No Issues Found

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dario-piotrowicz Jan 21, 2026

Choose a reason for hiding this comment

Uh oh!

ascorbic Jan 23, 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!

dario-piotrowicz Jan 21, 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!

devin-ai-integration bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

devin-ai-integration bot left a comment

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration bot Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

ascorbic commented Jan 21, 2026 •

edited by devin-ai-integration bot

Loading

changeset-bot bot commented Jan 21, 2026 •

edited

Loading

ascorbic Jan 23, 2026 •

edited

Loading