feat: add support for redirecting Wrangler to a generated config when running deploy commands

[petebacondarwin]

Fixes #5579

This feature is designed for build tools and frameworks to provide a deploy-specific configuration, which Wrangler can use instead of user configuration when running deploy commands.
It is not expected that developers of Workers will need to use this feature directly.

Affected commands

The commands that use this feature are:

• wrangler deploy
• wrangler dev
• wrangler versions upload
• wrangler versions deploy

Config redirect file

When running these commands, Wrangler will look up the directory tree from the current working directory for a file at the path .wrangler/deploy/config.json. This file must contain only a single JSON object of the form:

{ "configPath": "../../path/to/wrangler.json" }

When this file exists Wrangler will use the configPath (relative to the config.json file) to find an alternative Wrangler configuration file to load and use as part of this command.

When this happens Wrangler will display a warning to the user to indicate that the configuration has been redirected to a different file than the user's configuration file.

Custom build tool example

A common approach that a build tool might choose to implement.

• The user writes code that uses Cloudflare Workers resources, configured via a user wrangler.toml file.

  name = "my-worker"
  main = "src/index.ts"
  [[kv_namespaces]]
  binding = "<BINDING_NAME1>"
  id = "<NAMESPACE_ID1>"

  Note that this configuration points main at user code entry-point.

• The user runs a custom build, which might read the wrangler.toml to find the entry-point:

  > my-tool build

• This tool generates a dist directory that contains both compiled code and a new deployment configuration file, but also a .wrangler/deploy/config.json file that redirects Wrangler to this new deployment configuration file:

  - dist
    - index.js
  	- wrangler.json
  - .wrangler
    - deploy
  	  - config.json
  

  The dist/wrangler.json will contain:

  {
  	"name": "my-worker",
  	"main": "./index.js",
  	"kv_namespaces": [{ "binding": "<BINDING_NAME1>", "id": "<NAMESPACE_ID1>" }]
  }

  And the .wrangler/deploy/config.json will contain:

  {
  	"configPath": "../../dist/wrangler.json"
  }

---

• Tests
  • TODO (before merge)
  • Tests included
  • Tests not necessary because:
• E2E Tests CI Job required? (Use "e2e" label or ask maintainer to run separately)
  • I don't know
  • Required
  • Not required because:
• Public documentation
  • TODO (before merge)
  • Cloudflare docs PR(s):
  • Documentation not necessary because:

[changeset-bot]

🦋 Changeset detected

Latest commit: 3756ab2

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-pool-workers	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

[github-actions]

A wrangler prerelease is available for testing. You can install this latest build in your project with:

npm install --save-dev https://prerelease-registry.devprod.cloudflare.dev/workers-sdk/runs/12296073930/npm-package-wrangler-7442

You can reference the automatically updated head of this PR with:

npm install --save-dev https://prerelease-registry.devprod.cloudflare.dev/workers-sdk/prs/7442/npm-package-wrangler-7442

Or you can use npx with this latest build directly:

npx https://prerelease-registry.devprod.cloudflare.dev/workers-sdk/runs/12296073930/npm-package-wrangler-7442 dev path/to/script.js

Additional artifacts:

npx https://prerelease-registry.devprod.cloudflare.dev/workers-sdk/runs/12296073930/npm-package-create-cloudflare-7442 --no-auto-update

npm install https://prerelease-registry.devprod.cloudflare.dev/workers-sdk/runs/12296073930/npm-package-cloudflare-kv-asset-handler-7442

npm install https://prerelease-registry.devprod.cloudflare.dev/workers-sdk/runs/12296073930/npm-package-miniflare-7442

npm install https://prerelease-registry.devprod.cloudflare.dev/workers-sdk/runs/12296073930/npm-package-cloudflare-pages-shared-7442

npm install https://prerelease-registry.devprod.cloudflare.dev/workers-sdk/runs/12296073930/npm-package-cloudflare-vitest-pool-workers-7442

npm install https://prerelease-registry.devprod.cloudflare.dev/workers-sdk/runs/12296073930/npm-package-cloudflare-workers-editor-shared-7442

npm install https://prerelease-registry.devprod.cloudflare.dev/workers-sdk/runs/12296073930/npm-package-cloudflare-workers-shared-7442

npm install https://prerelease-registry.devprod.cloudflare.dev/workers-sdk/runs/12296073930/npm-package-cloudflare-workflows-shared-7442

Note that these links will no longer work once the GitHub Actions artifact expires.

---

[email protected] includes the following runtime dependencies:

Package	Constraint	Resolved
miniflare	workspace:*	3.20241205.0
workerd	1.20241205.0	1.20241205.0
workerd --version	1.20241205.0	2024-12-05

Please ensure constraints are pinned, and miniflare/workerd minor versions match.