Refactor internals to remove usage of CfWorkerInit["bindings"] in favour of the StartDevWorkerInput["bindings"] type

[penalosa]

Part 1 of my crusade to simplify data passing in Wrangler by removing the CfWorkerInit type.

This PR simplifies Wrangler's internals by using the StartDevWorkerInput["bindings"] format for bindings across both dev and deploy flows, building on the StartDevWorker work (#4413).

What changed:

• Hopefully nothing for users! This is entirely an internal refactor that should have ~mostly no user facing change (one change to the printBindings() output is mentioned in the review comments)
• Removed convertBindingsToCfWorkerInitBindings 🎉 since we no longer need to convert between these binding types.

This work is important because it aligns the internals of Wrangler with the API structure, and means that we no longer have two internal representations for bindings. It also unlocks some new super-secret stuff that's coming soon 🙈

---

• Tests
  • Tests included/updated
  • Automated tests not possible - manual testing has been completed as follows:
  • Additional testing not necessary because: this has effectively no user facing change, and so existing tests should be sufficient coverage.
• Public documentation
  • Cloudflare docs PR(s):
  • Documentation not necessary because: internal refactor

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

---

[changeset-bot]

⚠️ No Changeset found

Latest commit: c1133ed

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

[pkg-pr-new]

create-cloudflare

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

@cloudflare/kv-asset-handler

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

miniflare

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

@cloudflare/pages-shared

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

@cloudflare/unenv-preset

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

@cloudflare/vite-plugin

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

@cloudflare/vitest-pool-workers

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

@cloudflare/workers-editor-shared

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

@cloudflare/workers-utils

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

wrangler

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

commit: c1133ed

[penalosa]

This is messy, but I don't want to further bloat the diff size of this PR by moving the Binding type. I'll move it in a future PR

[penalosa]

I spent a lot of time trying to get this to match the order, but ultimately it made everything more complicated. The order of the metadata bindings array shouldn't have any impact.

[penalosa]

This is just array ordering in the bindings key

[penalosa]

This is fixing an unrelated bug where unsafe metadata would show up as env.key, when they aren't actually accessible on the env

[penalosa]

We no longer need to mask vars, since .env vars and CLI flags are now properly marked as secret_text

[penalosa]

I've maintained the existing preview ID validation, but in a future PR I think we should remove it. Preview IDs are not very useful in practice, and we intend to remove them in the next Wrangler major anyway.

[devin-ai-integration]

Devin Review found 2 potential issues.

View 8 additional findings in Devin Review.

[devin-ai-integration]

🔴 CLI --var overrides are uploaded as secret_text bindings (changes runtime semantics)

Wrangler deploy/version upload now converts user-provided vars overrides into secret_text bindings. That changes the binding type sent to the Workers API from a normal variable (plain_text) to a secret (secret_text).

Actual vs expected:

• Expected: --var FOO=bar should behave like a regular variable binding and be uploaded as plain_text (like config vars).
• Actual: it becomes a secret binding, which is treated differently by the platform (and can affect keep_bindings, secret management, and potentially value visibility/constraints).

Root Cause

In deploy.ts, overrides in props.vars are injected into the flat bindings map as secret_text:

• packages/wrangler/src/deploy/deploy.ts:801-808

for (const [key, value] of Object.entries(props.vars ?? [])) {
  bindings[key] = { type: "secret_text", value };
}

In versions/upload.ts, the code similarly rewrites plain_text into secret_text for keys present in props.vars, but then uses that mutated bindings when creating the upload form, so it is not “display-only”:

• packages/wrangler/src/versions/upload.ts:585-599

if (binding && binding.type === "plain_text") {
  bindings[key] = { type: "secret_text", value: binding.value };
}

createWorkerUploadForm() serializes secret_text bindings into Worker metadata:

• packages/wrangler/src/deployment-bundle/create-worker-upload-form.ts:120-126

case "secret_text": {
  metadataBindings.push({ name: binding, type: "secret_text", text: config.value });
}

Impact: Deploys (and versions uploads) that use CLI var overrides will silently change the binding type in the uploaded worker, potentially breaking expectations and changing how bindings are persisted/inherited.

Prompt for agents

Fix CLI var overrides so they remain normal vars (plain_text/json) when uploaded.

1) In packages/wrangler/src/deploy/deploy.ts around lines 801-808, stop creating { type: "secret_text" } bindings for props.vars. Instead, set { type: "plain_text", value } (and keep the masking behavior in printBindings separately if needed).

2) In packages/wrangler/src/versions/upload.ts around lines 585-599, do not mutate the bindings map used for createWorkerUploadForm. If you need to hide values in logs, pass a separate copy of bindings to printBindings where values are masked/converted for display only, but keep the upload bindings as plain_text.

3) Add/adjust tests that verify using CLI vars does not produce secret_text bindings in the uploaded metadata (assert on metadata.bindings types in mock-upload-worker helpers).

---

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

[devin-ai-integration]

🟡 Object.entries(props.vars ?? []) drops/incorrectly iterates deploy var overrides when props.vars is undefined

The deploy flow iterates CLI var overrides using Object.entries(props.vars ?? []). When props.vars is undefined, it falls back to an array instead of an empty object.

Actual vs expected:

• Expected: If no CLI vars are provided, the loop should be a no-op.
• Actual: It relies on [] as a fallback. While this happens to no-op at runtime, it is the wrong shape and is easy to accidentally break (and it obscures intent).

Root Cause

In deploy.ts:

• packages/wrangler/src/deploy/deploy.ts:803

for (const [key, value] of Object.entries(props.vars ?? [])) {

This should fall back to {} rather than [].

Impact: Today it likely no-ops, but it’s a real logic bug (wrong default type) and can lead to subtle issues if the code inside the loop changes (e.g. assumes string keys or uses object-specific behavior).

Suggested change

	for (const [key, value] of Object.entries(props.vars ?? [])) {
	for (const [key, value] of Object.entries(props.vars ?? {})) {

---

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