[wrangler] Add programmatic TypeScript config file support by penalosa · Pull Request #12533 · cloudflare/workers-sdk

penalosa · 2026-02-11T15:11:11Z

WIP — introduces programmatic TypeScript config files (cf.config.ts) as an alternative to static wrangler.toml/wrangler.json.

Changes

Flat bindings refactor — createWorkerUploadForm and provisionBindings use the new flat bindings format
Move core types to @cloudflare/workers-utils — StartDevWorkerInput, Hook, CfAccount, etc. so they can be imported by user config files without pulling in all of wrangler
New WorkerConfig type — user-facing subset of StartDevWorkerInput with env instead of bindings
worker() helper — type-safe identity function for config files: export default worker(() => ({ ... }))
Programmatic config loading — esbuild bundles and executes .ts/.js config files, with watch mode support
Config discovery — now searches for cf.config.ts → cloudflare.config.ts → wrangler.config.ts → wrangler.json → wrangler.toml
New subpath exports — wrangler/config and @cloudflare/workers-utils/programmatic
ConfigController updated to detect and handle programmatic configs

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:

changeset-bot · 2026-02-11T15:11:28Z

⚠️ No Changeset found

Latest commit: 1516480

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

packages/workers-utils/src/config/config-helpers.ts

penalosa · 2026-02-11T15:15:45Z

packages/workers-utils/src/config/index.ts

+		case "programmatic":
+			// Return the actual filename for programmatic configs
+			return configPath
+				? configPath.split("/").pop() ?? "config file"


There's a path API for this that'd be better

penalosa · 2026-02-11T15:16:30Z

packages/workers-utils/src/config/index.ts

+	// For programmatic configs, return empty config - they are handled
+	// separately via loadProgrammaticConfig() in the ConfigController
+	if (isProgrammaticConfigPath(configPath)) {
+		return {
+			rawConfig: {},
+			configPath,
+			userConfigPath,
+			deployConfigPath,
+			redirected,
+		};
+	}


I think we should probably throw in this case instead?

penalosa · 2026-02-11T15:17:55Z

packages/workers-utils/src/config/programmatic.ts

+/**
+ * Helper function to define a worker configuration with type safety.
+ */
+export function worker(fn: WorkerConfigFn): WorkerConfigFn {


I think we actually want this user facing function to be called defineConfig()

packages/workers-utils/src/config/programmatic.ts

penalosa · 2026-02-11T15:18:59Z

packages/workers-utils/src/config/programmatic.ts

+	const wranglerDir = path.join(configDir, ".wrangler", "tmp");
+	await fs.promises.mkdir(wranglerDir, { recursive: true });


Don't we have helpers for finding Wrangler's temp dir?

penalosa · 2026-02-11T15:21:31Z

packages/workers-utils/src/config/programmatic.ts

+	const tsconfigPath = findTsConfig(configDir);
+
+	// Create a unique temp file path in .wrangler directory
+	const wranglerDir = path.join(configDir, ".wrangler", "tmp");


Don't we have helpers for this?

penalosa · 2026-02-11T15:23:23Z

packages/workers-utils/package.json

+	"dependencies": {
+		"esbuild": "catalog:default"
+	},


Move this to devDeps along with everything else

penalosa · 2026-02-11T15:24:42Z

packages/wrangler/src/api/startDevWorker/ConfigController.ts

+			this.#programmaticWatcher = await watchProgrammaticConfig({
+				configPath,
+				env: this.latestInput?.env,
+				onChange: (_result: LoadProgrammaticConfigResult) => {


Why isn't this result being used?

…emp dir helpers, fix misc

pkg-pr-new · 2026-02-11T22:46:37Z

create-cloudflare

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

@cloudflare/kv-asset-handler

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

miniflare

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

@cloudflare/pages-shared

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

@cloudflare/unenv-preset

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

@cloudflare/vite-plugin

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

@cloudflare/vitest-pool-workers

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

@cloudflare/workers-editor-shared

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

@cloudflare/workers-utils

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

wrangler

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

commit: 1516480

- Add missing curly braces for single-line if statements (config-helpers, programmatic) - Replace non-null assertions with proper narrowing guards (ConfigController, register-yargs-command, worker-config-to-config) - Remove unused type imports (startDevWorker/types) - Use const for single-assignment variable (programmatic.ts ctx) - Remove unused BuildContext import

penalosa · 2026-02-13T14:59:56Z

packages/wrangler/src/config/worker-config-to-config.ts

This file is so much messier than I wanted it to be. Turns out that even after the CfWorkerInit["bindings"] refactor we had a lot of places accessing bindings directly from the Config type (which had a similar shape). More refactoring to come to make this simpler!

penalosa · 2026-02-13T15:49:06Z

packages/workers-utils/src/config/config.ts

+	/**
+	 * Pre-flattened bindings from programmatic config.
+	 * When set, deploy can use these directly instead of calling getBindings(config)
+	 * which would unflatten→reflatten. TOML configs leave this undefined.
+	 *
+	 * Typed as `Record<string, unknown>` to avoid cross-module type dependency in
+	 * the DTS bundle. Consumers should cast to `Record<string, Binding>`.
+	 */
+	flatBindings?: Record<string, unknown>;


This is messy, and there's more refactoring to do to make this not necessary

penalosa added the no-changeset-required label Feb 11, 2026

penalosa commented Feb 11, 2026

View reviewed changes

packages/workers-utils/src/config/config-helpers.ts Show resolved Hide resolved

penalosa commented Feb 11, 2026

View reviewed changes

packages/workers-utils/src/config/programmatic.ts Show resolved Hide resolved

penalosa commented Feb 11, 2026

View reviewed changes

penalosa added 4 commits February 11, 2026 21:59

Add programmatic TypeScript config file support (cf.config.ts)

42cdc22

Address PR feedback: rename to defineConfig, trim config names, use t…

f5e7791

…emp dir helpers, fix misc

Update lockfile

1a4f745

Avoid double-loading programmatic config on file change

ba60297

penalosa force-pushed the penalosa/cf-ts branch from d77f7d7 to b39637e Compare February 11, 2026 22:00

workers-devprod added this to workers-sdk Feb 11, 2026

github-project-automation bot moved this to Untriaged in workers-sdk Feb 11, 2026

penalosa force-pushed the penalosa/cf-ts branch from e5c5df5 to ba60297 Compare February 12, 2026 15:51

penalosa added 5 commits February 12, 2026 16:08

fix

16a44ec

fix object

6c82ac5

config-diff more options

2381e62

more vibe coding

f299471

penalosa commented Feb 13, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[wrangler] Add programmatic TypeScript config file support#12533

[wrangler] Add programmatic TypeScript config file support#12533
penalosa wants to merge 9 commits intomainfrom
penalosa/cf-ts

penalosa commented Feb 11, 2026

Uh oh!

changeset-bot bot commented Feb 11, 2026 •

edited

Loading

Uh oh!

Uh oh!

penalosa Feb 11, 2026

Uh oh!

penalosa Feb 11, 2026

Uh oh!

penalosa Feb 11, 2026

Uh oh!

Uh oh!

penalosa Feb 11, 2026

Uh oh!

penalosa Feb 11, 2026

Uh oh!

penalosa Feb 11, 2026

Uh oh!

penalosa Feb 11, 2026

Uh oh!

pkg-pr-new bot commented Feb 11, 2026 •

edited

Loading

Uh oh!

penalosa Feb 13, 2026

Uh oh!

penalosa Feb 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Comments

		const wranglerDir = path.join(configDir, ".wrangler", "tmp");
		await fs.promises.mkdir(wranglerDir, { recursive: true });

Conversation

penalosa commented Feb 11, 2026

Changes

Uh oh!

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

Uh oh!

⚠️ No Changeset found

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!

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!

pkg-pr-new bot commented Feb 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Comments

changeset-bot bot commented Feb 11, 2026 •

edited

Loading

pkg-pr-new bot commented Feb 11, 2026 •

edited

Loading