Skip to content
Adventive Adventive Engineering

2026-05-08 — Local dev uses `wrangler dev --remote`, not mixed-mode

2026-05-08 — Local dev uses wrangler dev --remote, not mixed-mode

Section titled “2026-05-08 — Local dev uses wrangler dev --remote, not mixed-mode”

Decision

Section titled “Decision”

scripts/dev-up.sh runs wrangler dev --remote --port 8787. The Worker executes on the Cloudflare edge against the dev account’s real DB_CONSOLE, DB_AGGREGATE, and AUTH bindings. The local wrangler dev process is a console + log tail; there is no workerd running on the laptop.

This diverges from the planning project at /Users/jlambert/Documents/Claude/Projects/Adventive Engineering/docs/projects/local-dev-public-api/, which specified mixed-mode (experimental_remote = true per binding). The plan was wrong on a load-bearing detail.

Why mixed-mode doesn’t work

Section titled “Why mixed-mode doesn’t work”

Empirically tested on Wrangler 4.84.1 (the version pinned in package.json) and Wrangler 4.90.0 (the latest at the time of writing):

  • experimental_remote = true and remote = true are both flagged as “unexpected fields” on [[hyperdrive]] bindings. Wrangler silently drops the field.
  • With the field dropped, wrangler dev falls through to its local-emulation path, which for Hyperdrive demands a Postgres localConnectionString. Adventive’s Hyperdrive bindings are MySQL.
  • wrangler dev --help on 4.90.0 lists only two mode flags: --remote (everything remote) and --local (everything local). There is no per-binding mixed-mode flag in the CLI either.

Cloudflare may yet add this feature; if/when they do, this decision should be revisited and the toolkit can switch back to mixed-mode for the iteration-speed gains it would bring.

Trade-offs we are accepting

Section titled “Trade-offs we are accepting”
  • Slower iteration. Each wrangler dev startup pushes the Worker to the edge (~30 s on a good network). Hot-reload after a save is also slower than local workerd would be.
  • No native debugger. The Worker runs at the edge, so node/V8 debugger attach does not apply. Engineers debug via console.log and the wrangler dev log tail.
  • Network-dependent. Offline development is not possible.
  • One Worker instance per engineer for the daily loop. Concurrent wrangler dev --remote sessions can run, but they share the same dev account quota.

Trade-offs we are not affected by

Section titled “Trade-offs we are not affected by”
  • OTel emission: still gated by OTEL_ENABLED=false in .dev.vars (see decisions/2026-05-08-otel-off-on-laptops.md). Fully-remote mode does not change this — .dev.vars is still passed through to the edge-side preview.
  • Per-engineer Worker (dev-deploy.sh) flow: unaffected. The [env.personal] block stays exactly as designed.

Plan reconciliation

Section titled “Plan reconciliation”

Source-of-truth files at docs/projects/local-dev-public-api/ retain the mixed-mode design. Future re-implementations (or a sync of the plan to reality) should:

  1. Update 02-code-updates.md to drop the experimental_remote = true claim and switch the spec to wrangler dev --remote.
  2. Update 04-runbook.md so --remote is the documented daily-loop mode, not labeled “rare”.
  3. Note that the Wrangler version is not the constraint — the feature simply does not exist for Hyperdrive bindings at this time.

The implementation in this repo is the source of truth until the plan is reconciled.