Skip to content

fix(cli): let a static-site build ship a Void backend - #291

Merged
Brooooooklyn merged 6 commits into
mainfrom
fix/ssg-plus-api-deploy
Aug 9, 2026
Merged

Brooooooklyn merged 6 commits into
mainfrom
fix/ssg-plus-api-deploy

Conversation

@Brooooooklyn

@Brooooooklyn Brooooooklyn commented Aug 7, 2026 •

Copy link
Copy Markdown
Member

Problem

An SSG site with Void API routes cannot deploy today. There is no configuration that works:

inference.appType Path Build actually run Backend deployed? Result
"void" / "framework" runFullDeploy vite build (hardcoded) — UNRESOLVED_ENTRY
"static" / "spa" / unset runStaticDeploy the SSG's build ✅ No site ships, worker silently dropped

runFullDeploy hardcoded the build command and ignored inference.build, which runFrameworkDeploy has always honored:

// before — deploy.ts
const buildCmd = formatProjectCommand(root, 'vite build');
execSync(resolveProjectCommand(root, 'vite build'), { ... });

A VitePress repo has no root index.html, so that dies with [UNRESOLVED_ENTRY] Cannot resolve entry module index.html.

Changes

1. runFullDeploy honors inference.build. Enables "two builds, one command" — the SSG build emits the site, then vp build pulls it in via publicDir and emits the worker:

vitepress build  ──►  .vitepress/dist/**      (site)
                            │  publicDir
                            ▼
vp build (voidPlugin) ──►  dist/client/**     (site, copied verbatim)
                      └──►  dist/ssr/index.js  (worker + routes/)

This works because @cloudflare/vite-plugin needs a client entry or a non-empty publicDir; 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. collectPrerenderPaths boots the built worker in Miniflare with only wranglerVars + 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, and loadDeployEnv reads 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 on pages/ alone would silently stop prerendering for custom-SSR apps and routing.prerender users. There's a test that fails against the naive version.

3. buildEnv() prepends the project's local node_modules/.bin to PATH. Configured build commands are exec'd raw; this only worked because the build container invokes the CLI through npx, which prepends every ancestor .bin. A directly-invoked node_modules/.bin/void deploy would fail to resolve a bare vitepress. Also closes the same latent hole in the framework, static, and drizzle-generate paths.

4. detectPreset gains opt-in strictBackend. Step 2 returned a matching SSG preset before step 3's hasBackendFiles check, so any SSG repo with routes/, 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 --dir are untouched: stated intent still wins, so this is not a breaking change for anyone who configured what they wanted.

5. New routing.notFound config. The worker-with-assets path infers not_found_handling: 'single-page-application', so an SSG's unknown URLs return index.html with HTTP 200 and its real 404.html is 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:

dist/client/index.html → /assets/app.CySZbPW6.js   ✅ resolves
dist/client/404.html                                ✅ shipped
dist/ssr/{index.js, wrangler.json}                  ✅
dist/ssr/assets/newsletter-*.js                     ✅ real handler
wrangler.json → not_found_handling "404-page", run_worker_first unchanged
vp run check       → 16/16 packages, no errors
vp fmt --check     → All matched files use the correct format. (1039 files)
vp lint            → clean
vp test run packages/void
  Test Files  200 passed | 2 skipped (202)
       Tests  3727 passed | 14 skipped (3741)

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 clean HEAD — byte-identical 5 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 in deploy-project.test.ts is 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.notFound could 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 hardcoded vite build. Full Void deploys now honor inference.build (e.g. vitepress build && vite build) and read void.json before the build step.

Adds routing.notFound (single-page-application | 404-page | none) so generated/SSG sites can serve real 404.html instead of SPA index.html at 200. The override flows through asset routing, static manifests, generated serveWithAssets, 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.appType is 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 prepend node_modules/.bin to PATH; git metadata uses scrubbed childEnv for hook/credential safety.

Reviewed by Cursor Bugbot for commit 3df1ce0. Bugbot is set up for automated code reviews on this repo. Configure here.

@cursor

cursor Bot commented Aug 7, 2026

Copy link
Copy Markdown

Bugbot couldn't run - usage limit reached

Bugbot 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)

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 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".

Comment thread packages/void/src/config.ts Resolved
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
@Brooooooklyn
Brooooooklyn force-pushed the fix/ssg-plus-api-deploy branch from 17b20dc to bf72b73 Compare August 8, 2026 09:20
@cursor

cursor Bot commented Aug 8, 2026

Copy link
Copy Markdown

Bugbot couldn't run - usage limit reached

Bugbot 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)

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 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".

Comment thread packages/void/src/asset-routing.ts Resolved
`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
@cursor

cursor Bot commented Aug 8, 2026

Copy link
Copy Markdown

Bugbot couldn't run - usage limit reached

Bugbot 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)

@Brooooooklyn

Copy link
Copy Markdown
Member Author

Rebased onto 3ebea50a (was 4 commits behind — the PR was conflicting, which is also why GitHub never built a merge ref and CI never ran). One conflict, pathe → pathslash from #288, resolved.

Also addressed the Codex finding in e5c96a20: routing.notFound is now threaded through the static deploy path, not just the worker path.

buildStaticManifest had no notFound parameter at all — it derived everything from appType via resolveSpaFallbackChain, so the option was accepted, validated, and silently ignored on static/spa deploys. It is observable end to end (manifest assetConfig → routing KV → dispatch resolveStaticPath, which implements all three values), so this was a real hole rather than a dead field.

The override is resolved into a single handling value before the branch, so notFound overriding away from SPA correctly skips the synthetic /* → /index.html rule, and notFound: 'single-page-application' takes the SPA branch whatever the appType. The deploy.ts:6088 "all pages prerendered → static" redirect — a second site with the same silent-ignore shape that the review didn't mention — now carries it too.

Two corrections to the review, for the record:

  • "including an auto-detected pure SSG" is not the case. SSG_PRESETS set appType: 'static', which already resolved to 404-page. The PR's motivating case was correct on the static path all along.
  • SPA does not always hardcode single-page-application — with routing.fallbacks present it returns 'none' plus a synthetic rule, so the fix had to route through that branch too.

The genuinely affected combination is appType: "spa" + an explicit notFound. That is incoherent for a real SPA, but detectPreset classifies any project with vite/vite-plus and no backend files as spa, so a Vite MPA lands there wrongly and this is exactly the right escape hatch.

runFrameworkDeploy's hardcoded 'none' is left alone — the meta-framework's worker owns HTML routing there.

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.

vp test run packages/void  →  3713 passed, 0 failed
vp run check / fmt --check / lint  →  clean

The 3 failing test files (full-deploy-manifest, named-layouts, node-static) are pre-existing on this base — confirmed by checking out clean origin/main and re-running to byte-identical results. node-static's cause is visible in its log: a stale playground/node-static/.void/prerender-runner.mjs still importing pathe after the #288 rename.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 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".

Comment thread packages/void/src/cli/deploy.ts Resolved
…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
@cursor

cursor Bot commented Aug 8, 2026

Copy link
Copy Markdown

Bugbot couldn't run - usage limit reached

Bugbot 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)

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 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".

Comment thread packages/void/src/router/compile.ts Resolved
Comment thread packages/void/src/config.ts Resolved
Comment thread packages/void/src/asset-routing.ts Resolved
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
@cursor

cursor Bot commented Aug 8, 2026

Copy link
Copy Markdown

Bugbot couldn't run - usage limit reached

Bugbot 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)

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 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".

Comment thread docs/guide/app-types.md Resolved
`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
@cursor

cursor Bot commented Aug 8, 2026

Copy link
Copy Markdown

Bugbot couldn't run - usage limit reached

Bugbot 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)

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 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".

Comment thread packages/void/src/index.ts Resolved
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>
@cursor

cursor Bot commented Aug 9, 2026

Copy link
Copy Markdown

Bugbot couldn't run - usage limit reached

Bugbot 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)

@Brooooooklyn
Brooooooklyn merged commit 462d99e into main Aug 9, 2026
9 checks passed
@Brooooooklyn
Brooooooklyn deleted the fix/ssg-plus-api-deploy branch August 9, 2026 02:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant