Skip to content

[wrangler] Support forwarded dev options in cf-wrangler - #16760

Merged
petebacondarwin merged 4 commits into
mainfrom
codex/cf-wrangler-dev-args
Nov 9, 2026
Merged

petebacondarwin merged 4 commits into
mainfrom
codex/cf-wrangler-dev-args

Conversation

@petebacondarwin

@petebacondarwin petebacondarwin commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

cf dev --inspector-port 9229 currently fails in the fallback Wrangler delegate with an unknown-option error. Reuse Wrangler's dev option definitions and validation, and pass the parsed options directly from the binary into startDev, so forwarded server parameters reach the running development server. Invalid option combinations are validated during parsing and produce a single-line usage error with exit code 2; runtime startup failures retain exit code 1. The exported development runner also validates options for direct callers before starting the runtime.

Related to cloudflare/cf#286. That PR defines transport of server arguments; this change accepts legitimate Wrangler options such as inspector settings, bindings, assets, TLS, and persistence. It preserves string values, repeated options, aliases, and both --flag value and --flag=value forms.

The experimental delegate continues to discover project config, map --mode to the named environment, use local development with optional remote bindings, disable provisioning, and default state to .cloudflare/state. Config/script overrides, --env, whole-worker remote dev, --no-local, and Wrangler global options remain unsupported. Server options that collide with cf globals need the separator, for example cf dev -- --local --persist-to "custom state". The delegate README documents these differences; build keeps its existing argument contract.

Companion PR #16759 removes the legacy cf-vite delegate and its requirement to share option names. That removal should land first. Native framework commands validate their own server options.

This is an argument adapter change in Wrangler. It uses the existing shared development runtime; Miniflare, the Vite plugin, and the Vitest plugin need no behavior changes. The delegate still dispatches in-process with the existing signal and exit handling, without introducing shell quoting or another spawn.

Validation (Node 22.22.1, pnpm 10.33.0):

  • Wrangler build and dependency builds passed.
  • 229 tests passed across the delegate, Wrangler dev, and start-dev suites, including direct-runner validation and parser/binary regressions for single-line usage errors and exit code 2. The new regression cases were confirmed to fail before the fix.
  • Built-export smoke tests confirmed direct calls reject all four invalid combinations. Built-binary smoke tests retained exit code 2 and single-line stderr for --node-compat and conflicting tunnel options in both separate-value and equals forms.
  • Wrangler source, template, unit-test, and E2E type checks passed.
  • Repository-wide type-aware lint and formatting checks passed.
  • Built-binary local smoke test verified the Worker response 000123|hello world|a=b c, the explicitly configured inspector endpoint, project discovery in a path containing spaces, and SIGINT exit code 130.

  • 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: this experimental delegate's forwarding contract and intentional differences are documented in its package README and changeset; the server options reuse the existing Wrangler dev interface.

A picture of a cute animal (not mandatory, but encouraged)

@changeset-bot

changeset-bot Bot commented Nov 6, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 55439ed

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages
Name Type
wrangler Minor
@cloudflare/vitest-plugin Patch

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

ask-bonk[bot]

This comment was marked as resolved.

@ask-bonk

ask-bonk Bot commented Nov 6, 2026

Copy link
Copy Markdown
Contributor

I'm Bonk, and I've done a quick review of your PR.

Expands cf-wrangler dev forwarding with Wrangler’s shared option definitions.

  1. Posted 1 P1 inline finding.

github run

@pkg-pr-new

pkg-pr-new Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
@cloudflare/autoconfig

npm i https://pkg.pr.new/@cloudflare/autoconfig@16760

@cloudflare/build-output-utils

npm i https://pkg.pr.new/@cloudflare/build-output-utils@16760

@cloudflare/codemods

npm i https://pkg.pr.new/@cloudflare/codemods@16760

@cloudflare/config

npm i https://pkg.pr.new/@cloudflare/config@16760

@cloudflare/containers-shared

npm i https://pkg.pr.new/@cloudflare/containers-shared@16760

create-cloudflare

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

@cloudflare/deploy-helpers

npm i https://pkg.pr.new/@cloudflare/deploy-helpers@16760

@cloudflare/kv-asset-handler

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

miniflare

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

@cloudflare/pages-functions

npm i https://pkg.pr.new/@cloudflare/pages-functions@16760

@cloudflare/pages-shared

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

@cloudflare/runtime-types

npm i https://pkg.pr.new/@cloudflare/runtime-types@16760

@cloudflare/unenv-preset

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

@cloudflare/vite-plugin

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

@cloudflare/vitest-plugin

npm i https://pkg.pr.new/@cloudflare/vitest-plugin@16760

@cloudflare/workers-auth

npm i https://pkg.pr.new/@cloudflare/workers-auth@16760

@cloudflare/workers-editor-shared

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

@cloudflare/workers-utils

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

wrangler

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

commit: 55439ed

@petebacondarwin
petebacondarwin marked this pull request as ready for review November 6, 2026 17:15
@workers-devprod
workers-devprod requested review from a team and cjol and removed request for a team November 6, 2026 17:16
@workers-devprod

workers-devprod commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Codeowners approval required for this PR:

  • ✅ @cloudflare/wrangler
Show detailed file reviewers

@devin-ai-integration devin-ai-integration Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note

Newer findings are available below. Devin Review posted a newer report on this PR, in addition to the findings presented here.

✅ Devin Review: No Issues Found

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

Devin Review

clanky-the-clanker[bot]

This comment was marked as resolved.

devin-ai-integration[bot]

This comment was marked as resolved.

@clanky-the-clanker clanky-the-clanker Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Superseded by the review of 38c030ae.

This review, of 497a1ebd

✅ Approved — The earlier exit-code note is fixed and covered by a binary test, and no new issues were found in the changed code.

The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.


✅ All checks passed

🔒 Security: ✅ LGTM

Forwarded options are parsed by yargs in strict mode, so unknown flags and positional arguments are rejected. The parser forces remote: false and nulls out the config, script, cwd and env-file overrides. Dispatch stays in-process, with no shell or spawn.


📖 AGENTS.md: ✅ LGTM

The packages/wrangler/AGENTS.md updates match the new file layout.


📋 Code Quality: ✅ LGTM

parseDevArgs now calls validateDevArgs inside its try block (packages/wrangler/src/cf-wrangler/args.ts). Validation failures are rethrown as ArgParseError, so they get the binary's exit-2 single-line usage error. dev.test.ts adds a test that checks exit code 2, single-line stderr, and that startDev is never called. No new issues found.


⚡ Performance: ✅ LGTM

Arguments are parsed once at startup. Nothing in this change runs on a hot path.


📝 Documentation: ✅ LGTM

The README and changeset describe the forwarding contract and the intentional differences from Wrangler.


Reviewed commit: 497a1ebd

@clanky-the-clanker clanky-the-clanker Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Superseded by the review of 55439ede.

This review, of 38c030ae

✅ Approved — The new check in the direct development runner is correct and tested, and no issues were found in the changed code.

The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.


✅ All checks passed

🔒 Security: ✅ LGTM

Forwarded options are parsed by yargs in strict mode. The parser forces remote: false and clears the config, script, cwd and env-file overrides. Dispatch stays in-process, with no shell or spawn. The shared validator keeps the --tunnel conflict checks.


📖 AGENTS.md: ✅ LGTM

The packages/wrangler/AGENTS.md updates match the new file layout.


📋 Code Quality: ✅ LGTM

runCfWranglerDev calls validateDevArgs before it resolves the profile or calls startDev, so a direct caller with an invalid option combination gets a UserError before anything starts. On the binary path the check also runs during parsing, so it runs twice, which is harmless. The tests cover all four conflicts on the direct path, exit code 2 with single-line stderr for usage errors, and exit code 1 for startup failures.


⚡ Performance: ✅ LGTM

Arguments are parsed and validated once at startup. Nothing in this change runs on a hot path.


📝 Documentation: ✅ LGTM

The README and changeset describe the forwarding contract and the intentional differences from Wrangler.


Reviewed commit: 38c030ae

@petebacondarwin
petebacondarwin removed the request for review from cjol November 9, 2026 15:36

@workers-devprod workers-devprod left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Codeowners reviews satisfied

Co-authored-by: Christopher Little-Savage <clittle-savage@cloudflare.com>

@clanky-the-clanker clanky-the-clanker Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ Approved — The only change since the last review is the README wording suggested in the discussion, which removes the stale PR-number reference. No issues found.

The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.


✅ All checks passed

🔒 Security: ✅ LGTM

Forwarded options are still parsed by yargs in strict mode. remote is forced to false, and the config, script, cwd and env-file overrides are cleared. Dispatch stays in-process, with no shell or spawn.


📖 AGENTS.md: ✅ LGTM

The packages/wrangler/AGENTS.md updates match the new file layout (src/dev/args.ts).


📋 Code Quality: ✅ LGTM

The only change since the last review is in the delegate README, so the code is the same as before. runCfWranglerDev still calls validateDevArgs before it starts the runtime. The binary path still validates during parsing, so usage errors exit with code 2 and startup failures exit with code 1.


⚡ Performance: ✅ LGTM

Arguments are parsed and validated once, at startup. Nothing in this change runs on a hot path.


📝 Documentation: ✅ LGTM

The README now describes how server arguments are forwarded without pointing to a specific PR number, which settles the README discussion thread. The README and changeset still describe the intentional differences from Wrangler accurately.


Reviewed commit: 55439ede

@petebacondarwin
petebacondarwin merged commit cb9534f into main Nov 9, 2026
84 checks passed
@petebacondarwin
petebacondarwin deleted the codex/cf-wrangler-dev-args branch November 9, 2026 19:03
@github-project-automation github-project-automation Bot moved this from Untriaged to Done in workers-sdk Nov 9, 2026
brandhaug added a commit to brandhaug/b2b-saas-starter that referenced this pull request Nov 13, 2026
## pnpm-workspace.yaml (default)

## Dependency Updates

| Package | From | To | Type |
| --- | --- | --- | --- |
| `@cloudflare/vitest-plugin` | 1.6.1 | 1.7.0 | minor |
| `@cloudflare/workers-types` | 5.20261109.1 | 5.20261110.1 | minor |
| `miniflare` | 5.20261109.0-beta | 5.20261110.0-beta | minor |
| `wrangler` | 4.159.0 | 4.160.0 | minor |

## Release Notes

<details>
<summary><b>@<!---->cloudflare/vitest-plugin</b> (1.6.1 →
1.7.0)</summary>

### Minor Changes

- [#15695](cloudflare/workers-sdk#15695)
[`d437be3`](cloudflare/workers-sdk@d437be3)
Thanks [@<!---->ghostwriternr](https://github.com/ghostwriternr)! - Run
the Containers that the Wrangler configuration attaches to Durable
Objects

Previously, the plugin disabled Containers, so those Durable Objects ran
without `ctx.container`. The plugin now builds or pulls the Containers'
images before each project's tests run and gives the Durable Objects a
real `ctx.container`, so these projects now need Docker. To keep running
their tests without Docker, set `dev.enable_containers` to `false` in
the Wrangler configuration, which disables the Containers.
Cloudflare-managed registry images are not supported yet.

### Patch Changes

- [#16810](cloudflare/workers-sdk#16810)
[`cdc970b`](cloudflare/workers-sdk@cdc970b)
Thanks [@<!---->dependabot](https://github.com/apps/dependabot)! -
Update `DEFAULT_COMPAT_DATE` to 2026-11-10

Use the bundled workerd release's compatibility date by default when
scaffolding new projects or when no compatibility date is configured.

- Updated dependencies
[[`cb9534f`](cloudflare/workers-sdk@cb9534f),
[`6af492e`](cloudflare/workers-sdk@6af492e),
[`cdc970b`](cloudflare/workers-sdk@cdc970b),
[`cdc970b`](cloudflare/workers-sdk@cdc970b),
[`4e7e9f1`](cloudflare/workers-sdk@4e7e9f1),
[`267dadb`](cloudflare/workers-sdk@267dadb),
[`022ee9d`](cloudflare/workers-sdk@022ee9d),
[`44b39b

…[full
notes](https://github.com/cloudflare/workers-sdk/releases/tag/%40cloudflare/vitest-plugin%401.7.0)

</details>

<details>
<summary><b>miniflare</b> (5.20261109.0-beta →
5.20261110.0-beta)</summary>

### Patch Changes

- [#16810](cloudflare/workers-sdk#16810)
[`cdc970b`](cloudflare/workers-sdk@cdc970b)
Thanks [@<!---->dependabot](https://github.com/apps/dependabot)! -
Update `DEFAULT_COMPAT_DATE` to 2026-11-10

Use the bundled workerd release's compatibility date by default when
scaffolding new projects or when no compatibility date is configured.

- [#16810](cloudflare/workers-sdk#16810)
[`cdc970b`](cloudflare/workers-sdk@cdc970b)
Thanks [@<!---->dependabot](https://github.com/apps/dependabot)! -
Update dependencies of "miniflare", "wrangler"

  The following dependency versions have been updated:

  | Dependency                | From          | To            |
  | ------------------------- | ------------- | ------------- |
  | @<!---->cloudflare/workers-types | ^5.20261109.1 | ^5.20261110.1 |
  | workerd                   | 1.20261109.1  | 1.20261110.1  |

- [#16807](cloudflare/workers-sdk#16807)
[`4e7e9f1`](cloudflare/workers-sdk@4e7e9f1)
Thanks [@<!---->brady-eaiti](https://github.com/brady-eaiti)! - Remove
the empty placeholder directory Miniflare creates when
`assets.directory` doesn't exist yet

Previously each process left an empty `miniflare-assets-*` directory in
the system temp directory, which built up over many runs from fresh
checkouts or before a first build. The placeholder now lives inside the
instance's own temporary directory, so `dispose()` and process exit
remove it.

- [#16612](cloudflare/workers-sdk#16612)
[`267dadb`](cloudflare/workers-sdk@267dadb)
Thanks [@<!---->petebacondarwin](https://github.com/petebacondarwin)! -
Limit the environment passed to local Browser Rendering and ensure a
usable home directory

  Chrome now receives only the hos

…[full
notes](https://github.com/cloudflare/workers-sdk/releases/tag/miniflare%405.20261110.0-beta)

</details>

<details>
<summary><b>wrangler</b> (4.159.0 → 4.160.0)</summary>

### Minor Changes

- [#16760](cloudflare/workers-sdk#16760)
[`cb9534f`](cloudflare/workers-sdk@cb9534f)
Thanks [@<!---->petebacondarwin](https://github.com/petebacondarwin)! -
Support forwarded Wrangler development server options in the
experimental `cf-wrangler` delegate

`cf dev` can now forward options such as `--inspector-port 9229`,
`--ip`, `--var`, and `--persist-to` to the Wrangler development runtime.
The delegate reuses Wrangler's dev option definitions and validation
while retaining project config discovery, `--mode` environment
selection, local development, and its `.cloudflare/state` default.
Invalid option combinations produce a single-line usage error and exit
code 2 before starting the server.

Place server options that overlap cf's global options after `--`, for
example `cf dev -- --local --persist-to "custom state"`. Config and
script overrides, whole-worker remote development, and Wrangler's global
options remain unsupported.

- [#16739](cloudflare/workers-sdk#16739)
[`6af492e`](cloudflare/workers-sdk@6af492e)
Thanks [@<!---->GregBrimble](https://github.com/GregBrimble)! - Add
custom Cloudflare API headers through `CLOUDFLARE_API_HEADERS`

Set `CLOUDFLARE_API_HEADERS` to a JSON object such as
`{"X-Custom-Header":"value"}` to add headers to Cloudflare API requests.
Custom headers override existing unprotected request headers, body and
transport headers are protected, and header values outside the
diagnostic allowlist remain redacted regardless of log sanitization
settings.

### Patch Changes

- [#16810](cloudflare/workers-sdk#16810)
[`cdc970b`](cloudflare/workers-sdk@cdc970b)
Thanks [@<!---->dependabot](https://github.com/apps/dependabot)! -
Update `DEFAULT_COMPAT_DATE` to 2026-11-10

  Use the bundled workerd release's

…[full
notes](https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.160.0)

</details>

---
*This PR was auto-generated by
[catalog-update-action](https://github.com/brandhaug/catalog-update-action).*

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

3 participants