Repository navigation
fix(cli): let a static-site build ship a Void backend - #291
Conversation
Bugbot couldn't run - usage limit reachedBugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit. A user or team admin can review and increase usage limits in the Cursor dashboard. (requestId: serverGenReqId_1fa83aa9-5856-4333-bf70-151ad24a00a7) |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 17b20dc5d5
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
An SSG site with API routes could not deploy. Setting `inference.appType`
to "void" (needed so `routes/` is compiled into a worker) routes to
`runFullDeploy`, which hardcoded `vite build` and ignored
`inference.build` -- so a VitePress repo with no root `index.html` died
with `[UNRESOLVED_ENTRY] Cannot resolve entry module index.html`.
Dropping `appType` instead took the static path, which silently deployed
the site with the backend discarded. There was no third option.
Five changes, four of them independently defensible:
1. `runFullDeploy` honors `inference.build`, mirroring `runFrameworkDeploy`.
That makes "two builds, one command" work: the SSG build emits the
site, then `vp build` copies it in via `publicDir` and emits the
worker. One artifact serves both surfaces.
2. Prerender collection is skipped when the app has no prerender sources
at all. This is a security fix, not an optimization.
`collectPrerenderPaths` boots the built worker in Miniflare with only
`wranglerVars + loadEnv('production')`, and the generated handler
validates the env schema at boot -- so a platform-only secret makes it
500 and aborts the deploy. The only workaround was putting the secret
in `.env.production`, and `loadDeployEnv` ships those as plaintext
manifest vars. Note the check is for prerender *sources*, not for a
`pages/` dir: `explicitPrerenderPaths` (routing.prerender) and the SSR
entry are independent sources, and gating on `pages/` alone would
silently stop prerendering for custom-SSR apps.
3. `buildEnv()` prepends the project's local `node_modules/.bin` to PATH.
Configured build commands are exec'd raw; this worked only because the
build container invokes the CLI through `npx`. Also closes the same
latent hole in the framework, static, and drizzle paths.
4. `detectPreset` gains an opt-in `strictBackend` mode, set only on the
unconfigured auto-detect path. An SSG repo with `routes/`,
`middleware/`, `crons/`, `queues/`, or an SSR entry now fails loudly
naming what it found, instead of silently shipping without a worker.
Explicit `appType: "static"` / `--dir` are untouched -- stated intent
still wins.
5. New `routing.notFound` config. The worker-with-assets path infers
`single-page-application`, so an SSG's unknown URLs return index.html
with HTTP 200 and its real 404.html is never served. The default is
unchanged (a SPA needs that fallback for deep links); `"404-page"` is
now available for SSG builds.
Verified end to end on a VitePress site with one API route: the build
emits dist/client (assets resolving at the paths its HTML references,
404.html included) plus dist/ssr with the route handler, and the
generated wrangler.json carries `not_found_handling: "404-page"` with
`run_worker_first` unchanged.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CeZ5KQp2TehVkNMrrABaah
17b20dc to
bf72b73
Compare
Bugbot couldn't run - usage limit reachedBugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit. A user or team admin can review and increase usage limits in the Cursor dashboard. (requestId: serverGenReqId_a1eeff22-12af-4bcb-b277-1fa1ff081f85) |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: bf72b73c9a
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
`routing.notFound` was threaded into the worker-with-assets path only (`resolveAssetConfig`). `buildStaticManifest` had no `notFound` option at all -- it derived `not_found_handling` purely from `appType` via `resolveSpaFallbackChain`, and `runStaticDeploy` never passed the value even though it already receives `routing` and uses it for `mergeRoutingRules`. The option was accepted, validated, and silently dropped. Not a dead field: the manifest's `assetConfig` flows through the API's `buildStaticRoutingJson` into routing KV, and dispatch's `resolveStaticPath` implements all three values for static deploys. The motivating SSG case was already correct -- `SSG_PRESETS` set `appType: "static"`, which yields `404-page`. The harmful combination is `appType: "spa"` + `notFound: "404-page"`. That reads incoherent until you notice `detectPreset` classifies *any* project with vite/vite-plus and no backend files as `spa`, so a plain Vite MPA lands there wrongly and this override is its only escape hatch. The override is applied *inside* `resolveSpaFallbackChain`, before it branches, not patched onto the result. Overriding away from `single-page-application` must also skip the synthetic `/* -> /index.html` fallback the SPA branch appends when `routing.fallbacks` is set -- otherwise the shell is still served, just through a rule instead of the platform switch, and the override is a no-op. Conversely an explicit `single-page-application` now takes the SPA branch whatever the appType. `runStaticDeploy` gets a dedicated trailing `notFound` param rather than relying on `routing`, because the second gap is the "all pages prerendered -> static" redirect in `runFullDeploy`: it merged the routing rules upstream and deliberately passes `routing: undefined`, so a Void app's `routing.notFound` was dropped there too. That call site now hands the value over directly. `runFrameworkDeploy`'s hardcoded `not_found_handling: "none"` is left alone -- the meta-framework's own worker owns HTML. Also reworded `detectNonSpaFallbackWarning`: it fires on the resolved `not_found_handling`, and with an explicit `routing.notFound` the app may well be a SPA, so "appType is not spa" was misleading. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CeZ5KQp2TehVkNMrrABaah
Bugbot couldn't run - usage limit reachedBugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit. A user or team admin can review and increase usage limits in the Cursor dashboard. (requestId: serverGenReqId_f50d601c-dd41-4260-91ea-37a024e5a73f) |
|
Rebased onto Also addressed the Codex finding in
The override is resolved into a single Two corrections to the review, for the record:
The genuinely affected combination is
9 tests added, all verified red without the fix (5 of 7 unit, 2 of 2 integration against the real finalize-POST manifest body). No existing test modified — both test files are pure insertions. The 3 failing test files ( |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: e5c96a20fd
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
…PATH Two follow-ups to the `routing.notFound` work in e5c96a2. 1) `routing.notFound` was inert on worker-first SPA-fallback apps. `resolveAssetRoutingPolicy` set `assetConfig.not_found_handling` and left `workerSpaFallback` alone, but that flag makes the generated `serveWithAssets` answer every unmatched HTML navigation with `/index.html` at status 200 -- before `not_found_handling` is ever consulted. And even with the flag cleared, the helper's `asset.status !== 404` guard threw away CF's `404-page` response, which is a 404. Both halves are load-bearing; either one alone leaves the override observably broken. The reachable shape is `workerFirst && !isSsr && !hasPages`, i.e. a non-SSR app with no `pages/` that owns HTML routing via `middleware/`, a route outside `/api`, a document websocket, or Live. That is exactly the app `docs/guide/app-types.md` recommends `routing.notFound` for (`appType: "void"` + `vitepress build && vite build`) -- add one `middleware/` file and the documented escape hatch stopped working. So: an explicit `notFound` other than `single-page-application` now clears `workerSpaFallback`, and the resolved handling is threaded into `compileAssetFallbackHelper` (and through `compileWorkerEntry` + the Class A trigger wrapper) so `404-page` passes the asset binding's own 404 through. Passing it through rather than fetching `/404.html` by hand is deliberate: CF's `404-page` is directory-aware ("nearest 404.html"), a hardcoded root path is not. Guarded on an HTML content-type, because with no `404.html` anywhere CF answers a bodyless 404 and the worker's own response is the better answer then. Threaded consistently across dev, build, and the Class A wrapper -- the reason the override was applied on the policy inputs in the first place. 2) The `node_modules/.bin` PATH prepend was wider than its purpose. It went into `buildEnv()` itself, but `buildEnv` has five callers and one is `getGitCommit`, which execs bare `git`. A dependency shipping `node_modules/.bin/git` therefore ran during metadata collection -- before the build, with `VOID_TOKEN` in env -- and got to choose the commit/clean-tree metadata. In every mode that runs a build the same dependency executes moments later anyway, so this is low severity; the genuinely new paths are the no-build modes (`void deploy --dir dist`, and `static`/`spa` presets whose `detectPreset` finds no build command), where a `git` shim would be the only child the deploy spawns. `buildEnv()` goes back to being the scrub-only helper it was; the prepend is an explicit opt-in (`{ localBinRoot }`) on the three build execs only. Not a separate `gitEnv()` -- that would make the safe case the special case and let the next `buildEnv()` caller silently re-opt-in. Folds in one adjacent pre-existing gap: `git-metadata.ts` ran its two git children with no `env` at all, so they inherited `process.env` verbatim including the `CF_ACCESS_CLIENT_ID`/`SECRET` pair that `buildEnv` exists to scrub. They now take a `childEnv`, and `void deploy` hands them the scrubbed env -- matching `getGitCommit` right beside it. Tests updated (both new in e5c96a2, both encoding behavior this commit changes): `deploy-asset-config.test.ts`'s "derived flags untouched" assertion is now shape-scoped (its inputs are asset-first, where the flag is false either way) and `deploy-auth.test.ts`'s `buildEnv` suite moves to the opt-in signature plus a new no-opt-in case. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CeZ5KQp2TehVkNMrrABaah
Bugbot couldn't run - usage limit reachedBugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit. A user or team admin can review and increase usage limits in the Cursor dashboard. (requestId: serverGenReqId_2be17f8b-04b0-4f91-9eda-3db1323ac7ef) |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: fbdf44429c
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Follow-up to fbdf444, which regressed every API 404 on the shapes that set `routing.notFound: '404-page'`. That commit added a pass-through branch to `compileAssetFallbackHelper` so CF's nearest-`404.html` response survives the helper's `asset.status !== 404` guard. Its only guard was the ASSET's content-type -- and the asset 404 page is `text/html`, so the guard never fired protectively. Nothing was read off `request`. `serveWithAssets` wraps EVERY app response with no path filtering and engages on any 404, so a GET/HEAD API handler that deliberately returns a JSON 404 had its response replaced by the site's HTML 404 page. Since the response is rebuilt as `new Response(asset.body, asset)`, status, statusText and headers all come from the asset: the handler's content-type is lost and CORS headers a middleware set on the 404 are dropped, so a browser `fetch()` sees a CORS failure rather than a 404. Every shape that resolves `404-page` emitted the ungated branch -- SSG+API, SSG+API+middleware, `pages/`+API, SSR+API. Worst is the asset-first case, which is this branch's own documented recipe: there `404-page` means the asset layer answers document misses itself, so `serveWithAssets` is reached ONLY on `run_worker_first` paths (`/api/*`, `/__void/*`), where the branch has zero upside. So: also gate on the REQUEST's `Accept` including `text/html`, the same guard the SPA-fallback branch immediately beside it already uses, for the same reason. `routing.notFound` is about document navigations. Two alternatives were rejected. Gating on the `X-Void-No-Match` marker is inert twice over: `__voidShouldMarkNoMatch` returns false for `/\/[^/]+\.[^/]+$/`, so a `.html` document URL never carries the marker (and VitePress's default `cleanUrls: false` emits exactly those), and Class A framework apps wrap the framework's own server entry, whose 404s never pass through Void's route table at all. Gating on a body-less worker response is also inert -- `new Response("Not Found", {status:404})` carries both a body and a `text/plain` content-type. Tests: the existing end-to-end cases all sent `accept: text/html` to a document path with a generic worker 404, so nothing covered the API-client axis. Added six cases over the real generated helper -- JSON 404 preserved for `application/json`, `*/*` and a missing `Accept` header; a middleware-set CORS header preserved; and both document shapes (extension-less and `.html`) still getting the generator's 404 page. Five of the six fail without this fix. No existing assertion was changed: `serveUnmatched` keeps its exact contract, its internals just moved into a `serveRaw` that returns the raw `Response` so headers can be asserted. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CeZ5KQp2TehVkNMrrABaah
Bugbot couldn't run - usage limit reachedBugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit. A user or team admin can review and increase usage limits in the Cursor dashboard. (requestId: serverGenReqId_cdc080d1-5ed7-4295-b8c8-7ed7bc30037d) |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: c39d20a513
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
`runFrameworkDeploy` pins `assetConfig: { not_found_handling: 'none' }` and
never reads `routing.notFound`, but nothing told the user. The config
validator accepts the key in every mode, the docs present it
unconditionally, and sibling `routing.*` keys (`headers`, `redirects`) do
work in framework mode — so the option read as supported while doing
nothing.
The pin is correct and stays. Class B/C presets (SvelteKit, Nuxt, Analog,
Astro) emit no `run_worker_first`, so the asset layer answers before the
framework worker and real prerendered files already win; `not_found_handling`
only governs what the framework's own `env.ASSETS.fetch()` delegation
returns. Threading the override there would be a behavior change, not a fix:
`single-page-application` makes an unmatched delegation return
`dist/client/index.html` at 200 (hybrid builds commonly prerender the root,
so real 404s become the home page), and `404-page` steals the 404 from the
framework's own error route.
So: warn, and document the scope. `warnIgnoredNotFoundForFramework` fires
once from `runFrameworkDeploy` (outside the packaging spinner) when the key
is set, naming the framework and the pinned value. Scope is now stated in
`config.md`, the `static-assets.md` inference table (which had no framework
row at all), the frameworks overview field table, and the `schema.json`
description.
Also rewords the `workerSpaFallback` comment in `asset-routing.ts`: the flag
exists because the INFERRED `not_found_handling` on that shape is `'none'`,
not because `run_worker_first: ['/**']` "disables the platform switch".
`run_worker_first` only decides who sees the request first — it skips the
pre-worker asset layer, but `not_found_handling` still applies inside
`env.ASSETS.fetch()`. The old wording invited the false conclusion that an
explicit `notFound` cannot work on the SSR/Pages shapes; a regression guard
in `deploy-asset-config.test.ts` now pins that SSR/Pages +
`notFound: 'single-page-application'` already yields the 200 SPA shell with
`workerSpaFallback` off, because `serveWithAssets` returns any non-404 asset
before the fallback code is reached. No behavior change there.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CeZ5KQp2TehVkNMrrABaah
Bugbot couldn't run - usage limit reachedBugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit. A user or team admin can review and increase usage limits in the Cursor dashboard. (requestId: serverGenReqId_70d941d7-94d5-4139-833e-6a16b07ad2fe) |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 09608e5143
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
The Class A trigger wrapper's `404-page` branch only fires when the asset binding itself answers with an HTML 404 page, which needs `assets.not_found_handling: '404-page'` on the deployed worker. Managed `void deploy` supplies that out-of-band — `runFullDeploy` resolves `manifest.assetConfig`, and that is what the platform applies to the uploaded script — so the option worked there. The built `dist/ssr/wrangler.json` never carried it: the `if (framework)` branch returns before `applyAssetRoutingPolicy` ever runs. Anyone running `wrangler deploy` on that same output therefore got the root wrangler value, normally absent (CF's `none`), and the wrapper fetched a bare 404 it could not use. Configured, documented, inert. `void:framework-build-wrapper` now also writes `not_found_handling` into the worker config. Scoped three ways: only that one field, only when the user set `routing.notFound`, and only on `build`. `binding`, `directory` and `run_worker_first` stay whatever the framework/root config says — Void infers no asset policy for Class A apps — and the Cloudflare plugin `defu`s our partial over the resolved config, so the framework's own keys survive. Build-only matches the wrapper: the dev wrapper has no `serveWithAssets` at all, and flipping the dev asset router would change which layer answers an unmatched navigation under `vite dev`. That makes `mergeBindings`' stale-root-value deletion per FIELD rather than per object. It previously keyed on `workerConfig.assets` existing at all, which was safe only because the default mode always generates BOTH keys. Class A generates one, so the old gate would have deleted a root wrangler `run_worker_first` that Void has no replacement for. Identical behavior in default mode. No supported deploy path changes: `void deploy` reads only `main` out of the built wrangler config and computes `assetConfig` itself, and `--backend cloudflare` refuses Class A SSR outright. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Bugbot couldn't run - usage limit reachedBugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit. A user or team admin can review and increase usage limits in the Cursor dashboard. (requestId: serverGenReqId_fe0731be-e0eb-4148-94c2-804ce6286da0) |
Problem
An SSG site with Void API routes cannot deploy today. There is no configuration that works:
inference.appType"void"/"framework"runFullDeployvite build(hardcoded)UNRESOLVED_ENTRY"static"/"spa"/ unsetrunStaticDeployrunFullDeployhardcoded the build command and ignoredinference.build, whichrunFrameworkDeployhas always honored:A VitePress repo has no root
index.html, so that dies with[UNRESOLVED_ENTRY] Cannot resolve entry module index.html.Changes
1.
runFullDeployhonorsinference.build. Enables "two builds, one command" — the SSG build emits the site, thenvp buildpulls it in viapublicDirand emits the worker:This works because
@cloudflare/vite-pluginneeds a client entry or a non-emptypublicDir; with the latter it takes its fallback build and still emits the assets binding.2. Prerender collection is skipped when the app has no prerender sources. This is a security fix.
collectPrerenderPathsboots the built worker in Miniflare with onlywranglerVars + loadEnv('production', root, ''), and the generated handler validates the env schema at boot — so a platform-only secret makes it HTTP 500 and aborts the deploy. The only workaround was putting the secret in.env.production, andloadDeployEnvreads those and returns them as plaintext manifest vars.Note this checks for prerender sources, not for a
pages/directory.explicitPrerenderPaths(routing.prerender) and the SSR entry are independent sources — gating onpages/alone would silently stop prerendering for custom-SSR apps androuting.prerenderusers. There's a test that fails against the naive version.3.
buildEnv()prepends the project's localnode_modules/.binto PATH. Configured build commands are exec'd raw; this only worked because the build container invokes the CLI throughnpx, which prepends every ancestor.bin. A directly-invokednode_modules/.bin/void deploywould fail to resolve a barevitepress. Also closes the same latent hole in the framework, static, and drizzle-generate paths.4.
detectPresetgains opt-instrictBackend. Step 2 returned a matching SSG preset before step 3'shasBackendFilescheck, so any SSG repo withroutes/,middleware/,crons/,queues/, or an SSR entry deployed as a pure static site with the backend silently discarded — a data-loss-class failure with no diagnostic. It now fails loudly, naming what it found.Set only on the unconfigured auto-detect path. Explicit
appType: "static"and--dirare untouched: stated intent still wins, so this is not a breaking change for anyone who configured what they wanted.5. New
routing.notFoundconfig. The worker-with-assets path infersnot_found_handling: 'single-page-application', so an SSG's unknown URLs returnindex.htmlwith HTTP 200 and its real404.htmlis never served — crawlers see 200 for every URL.The default is deliberately unchanged: a real SPA needs that fallback for deep links, and there's no reliable way to tell an SSG's assets from a SPA's.
"404-page"is now opt-in.Verification
End to end on a VitePress site with one API route, using the built CLI:
Full-repo suite has 5 pre-existing failures in
packages/react/test/integration/react-pages-client.test.ts(Playwright hydration timeouts). Confirmed pre-existing by stashing this branch's changes and re-running on cleanHEAD— byte-identical5 failed | 64 passed (69).No existing test was weakened, rewritten, or deleted. Test files are pure additions (
40/0,81/0,108/0,113/0,204/0); the single deleted line indeploy-project.test.tsis an import statement merged into a combined import from the same module.🤖 Generated with Claude Code
https://claude.ai/code/session_01CeZ5KQp2TehVkNMrrABaah
Note
Medium Risk
Changes deploy routing, 404/SPA behavior, and auto-detect failures across many app shapes; behavior is heavily tested but misconfigured
routing.notFoundcould affect crawlers and deep links.Overview
Fixes the deploy gap where an SSG plus Void
routes/could only ship as static (worker dropped) or fail on hardcodedvite build. Full Void deploys now honorinference.build(e.g.vitepress build && vite build) and readvoid.jsonbefore the build step.Adds
routing.notFound(single-page-application|404-page|none) so generated/SSG sites can serve real404.htmlinstead of SPAindex.htmlat 200. The override flows through asset routing, static manifests, generatedserveWithAssets, and Class A framework wrappers; worker-side SPA fallback is disabled when not requesting SPA behavior. SvelteKit/Nuxt/Analog/Astro ignore the setting with a deploy warning.Auto-detect refuses ambiguous SSG+backend projects unless
inference.appTypeis set. Prerender path collection is skipped when there are no prerender sources, avoiding Miniflare boot failures that pushed secrets into.env.production. Build children optionally prependnode_modules/.binto PATH; git metadata uses scrubbedchildEnvfor hook/credential safety.Reviewed by Cursor Bugbot for commit 3df1ce0. Bugbot is set up for automated code reviews on this repo. Configure here.