Cloudflare dashboard deploy: split build + `wrangler deploy` conflicts with vinext — must skip build and use `vinext deploy`

[hyf0]

Experience feedback: deploying via the Cloudflare dashboard (Workers Builds)

When deploying a vinext app to Cloudflare Workers through Cloudflare's web dashboard Git integration ("Create Worker → connect repo" / Workers Builds), the UI splits the pipeline into two fields — a Build command and a Deploy command (where the deploy step is wrangler deploy). This split model fights vinext's all-in-one vinext deploy.

What goes wrong

Approach A — Build = vinext build (or a build:vinext script), Deploy = npx wrangler deploy:
wrangler deploy needs a wrangler.jsonc + worker entry, which don't exist in the repo until vinext generates them. So it either fails or forces you to hand-commit the config.

Approach B — let the dashboard auto-configure the framework:
It detects next and applies @opennextjs/cloudflare (OpenNext) instead of vinext, running @opennextjs/cloudflare migrate — which then fails on yarn 1.x because migrate internally calls yarn dlx (not a yarn-classic command):

🛠️  Configuring project for Next.js with OpenNext by running `@opennextjs/cloudflare migrate`
? Proceed with setup? 🤖 Using fallback value in non-interactive context: yes
yarn run v1.22.22
error Command "dlx" not found.
✘ [ERROR]
Failed: error occurred while running deploy command

What actually works

In the dashboard, leave the Build command empty (it's marked optional) and set the Deploy command to npx vinext deploy. vinext's one-command deploy then generates its own config, builds, and deploys — no OpenNext, no missing-config error.

Caveats hit along the way

• vinext deploy runs vinext build internally, which does not run any custom prebuild step. If your real build does extra work (e.g. node scripts/downloadFonts.mjs for self-hosted fonts), it's silently skipped — you must replicate it in the optional Build command.
• vinext deploy --skip-build exists to bridge "build separately, then deploy", but it's confusing in the dashboard context: it only makes sense because vinext deploy is an all-in-one command shoehorned into a deploy-only slot.

Suggestions

• Document the Cloudflare dashboard deploy path explicitly (current guidance assumes the CLI). Recommend: empty Build command + vinext deploy as the Deploy command.
• Detect/avoid Cloudflare's OpenNext auto-setup, or at least note the conflict.
• Consider a documented build/deploy split story (when to commit the generated wrangler.jsonc + use wrangler deploy, vs. one-shot vinext deploy).

Environment: vinext 0.1.8 · yarn 1.22.22 · Cloudflare Workers Builds (dashboard Git integration).

[hyf0]

🔎 Triage — Next.js behavior vs vinext behavior

Method: grounded in the installed Next.js 15.1.12 source (node_modules/next/dist) and the exact vinext 0.1.8 dist (node_modules/vinext/dist) this issue was filed against; each conclusion independently re-checked by an adversarial second pass. vinext targets the Next.js 16 API surface, so a possible version difference was tested explicitly.

Verdict: 🛠️ tooling / UX gap + not vinext’s responsibility · should vinext fix: partial · scope: deploy-tooling · confidence: high

Next.js behavior

N/A as runtime parity — Next.js has no vinext deploy equivalent. The closest analog is next build plus a Cloudflare adapter (@opennextjs/cloudflare). The Cloudflare dashboard's framework auto-detection of next -> applying @opennextjs/cloudflare and running @opennextjs/cloudflare migrate (which calls yarn dlx, unsupported on yarn-classic 1.x) is Cloudflare dashboard + OpenNext behavior, not Next.js core. Standard next build likewise does not run arbitrary custom prebuild scripts unless they are wired as npm lifecycle hooks (e.g. a prebuild script) on the command actually invoked.

_{Evidence: https://opennext.js.org/cloudflare/get-started — OpenNext Cloudflare adapter & migrate are an OpenNext/Cloudflare integration, separate from Next core · node_modules/vinext/README.md:133 — README itself describes OpenNext as adapting next build output, confirming it is a separate adapter not Next core}

vinext behavior

vinext models deployment as a single all-in-one command: deploy() detects the router, scaffolds missing config (wrangler.jsonc, worker/index.ts, vite.config.ts), installs missing deps, runs the Vite build, then runs wrangler deploy (deploy.js:947-1038). The config files are only generated by the deploy path's getFilesToGenerate (deploy.js:788-812); vinext build / vinext init do NOT emit wrangler.jsonc or worker/index.ts (cli.js:492-511 build help only runs the Vite build; init.js only writes vite.config.ts at init.js:222-226). So in the dashboard's split model (Build=vinext build, Deploy=wrangler deploy), wrangler deploy finds no wrangler.jsonc/worker entry because nothing committed them — Approach A (sub-problem A) is a real consequence of this design. The build invoked by deploy is Vite's programmatic builder (runBuild -> createBuilder().buildApp(), deploy.js:845-857, called at deploy.js:1005), NOT npm run build, so npm prebuild/custom build scripts (e.g. scripts/downloadFonts.mjs) are silently skipped — sub-problem C is confirmed. --skip-build exists to bridge build-then-deploy (deploy.js:46-49, 1005-1006). vinext has no hook into Cloudflare's framework auto-detection, so it cannot prevent the dashboard from picking OpenNext — sub-problem B is outside vinext. The README deployment section documents only the CLI path (wrangler login/account id/vinext deploy) and never mentions the Cloudflare dashboard / Workers Builds split-field flow (README.md:181-269) — a docs gap.

_{Evidence: node_modules/vinext/dist/deploy.js:947-1038 — deploy() all-in-one: scaffold + install + build + wrangler deploy · node_modules/vinext/dist/deploy.js:788-812 — getFilesToGenerate writes wrangler.jsonc/worker/index.ts/vite.config.ts only inside the deploy flow · node_modules/vinext/dist/deploy.js:845-857 — runBuild uses Vite createBuilder().buildApp(), not npm run build, so prebuild scripts are skipped · node_modules/vinext/dist/deploy.js:46-49,1005-1006 — --skip-build flag bridges build-then-deploy · node_modules/vinext/dist/cli.js:492-511 — vinext build only runs the Vite build; no wrangler/worker config generation · node_modules/vinext/dist/init.js:222-226 — vinext init generates only vite.config.ts, not wrangler.jsonc/worker entry · node_modules/vinext/README.md:181-269 — Deployment docs cover only the vinext deploy CLI path; no Cloudflare dashboard / Workers Builds split-field guidance}

Is it a version difference (vinext → Next 16 vs react.dev → Next 15)?

No. Nothing here depends on Next.js 15 vs 16 behavior. All three sub-problems are about deploy ergonomics: vinext's all-in-one vinext deploy vs the Cloudflare dashboard's split Build/Deploy fields (A), Cloudflare's framework auto-detection choosing OpenNext whose migrate calls yarn dlx and fails on yarn-classic (B), and vinext deploy invoking Vite's programmatic build instead of npm run build so custom prebuild scripts are skipped (C). None of these are Next runtime semantics, so the Next 16 target is irrelevant.

Fix

Docs: README.md Deployment section (add a Cloudflare dashboard / Workers Builds path: empty Build command + npx vinext deploy as Deploy command, and the OpenNext auto-detect conflict note). Optional code: dist/deploy.js runBuild — run the project's prebuild/custom build lifecycle (or document --skip-build after a separate Build step) so custom prebuild work (e.g. downloadFonts.mjs) isn't silently skipped.

---

_{🤖 Triaged with Claude Code (Opus 4.8) — read-only analysis against installed Next 15.1.12 + vinext 0.1.8 sources, adversarially verified.}