Title: Node target: production build keeps installed void external, API-only build crashes, and the CF-only guard misses dependencies · Issue #416 · voidzero-dev/void · GitHub
Open Graph Title: Node target: production build keeps installed void external, API-only build crashes, and the CF-only guard misses dependencies · Issue #416 · voidzero-dev/void
X Title: Node target: production build keeps installed void external, API-only build crashes, and the CF-only guard misses dependencies · Issue #416 · voidzero-dev/void
Description: Problem Four problems with target: 'node': What the user does What happens a Installs void from npm, builds a pages app, runs vp preview A ValidationError thrown in an action gives 500 b Builds an app with no pages/ folder vp build crash...
Open Graph Description: Problem Four problems with target: 'node': What the user does What happens a Installs void from npm, builds a pages app, runs vp preview A ValidationError thrown in an action gives 500 b Builds an ...
X Description: Problem Four problems with target: 'node': What the user does What happens a Installs void from npm, builds a pages app, runs vp preview A ValidationError thrown in an action gives 500 b Bu...
Opengraph URL: https://github.com/voidzero-dev/void/issues/416
X: @github
Domain: github.com
{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Node target: production build keeps installed void external, API-only build crashes, and the CF-only guard misses dependencies","articleBody":"## Problem\n\nFour problems with `target: 'node'`:\n\n| | What the user does | What happens |\n| --- | --- | --- |\n| a | Installs `void` from npm, builds a pages app, runs `vp preview` | A `ValidationError` thrown in an action gives 500 |\n| b | Builds an app with no `pages/` folder | `vp build` crashes |\n| c | Uses a package that imports `void/kv` | No guard error; the request fails later |\n| d | Reads `packages/void/AGENTS.md` | The CF-only list does not match the code |\n\n### a. The production build keeps an installed `void` external\n\nA Node-target React pages app has an action that throws `ValidationError` from `void/handler`. With `void` installed (npm or pnpm), `vp build` then `vp preview` returns `Internal Server Error` for the form POST. The log shows the error was not handled:\n\n```\nValidationError: Validation failed\n at .../dist/ssr/assets/form.server-*.js:5:8\n at handlePageMutation (.../dist/ssr/assets/app-*.js)\n ...\n at async .../node_modules/void/dist/index.mjs {\n errors: { email: 'Email already taken' }\n}\n```\n\nThe same app returns 200 in `vp dev` (after #413) and with a workspace-linked `void`. The built `dist/ssr` imports `void/handler`, `void/sse`, `void/_env` and `@void/react` at runtime. So the user code's `ValidationError` class is a different copy from the one Void checks with `instanceof`. Production also needs these dev dependencies: started with only `hono`, `react` and `@hono/node-server` present, it fails with `ERR_MODULE_NOT_FOUND '@void/react'`.\n\n### b. An API-only build crashes\n\n```\ndist/ssr/app.js 84.65 kB │ gzip: 23.52 kB\n✓ built in 21ms\nerror during build:\nTypeError: Cannot destructure property 'logger' of 'environment' as it is undefined.\n at buildEnvironment (.../vite/node/chunks/node.js)\n at Object.build (.../vite/node/chunks/node.js)\n at BasicMinimalPluginContext.buildApp (.../void/dist/index.mjs)\n```\n\nThe `ssr` output is written, then the build fails. This happens with a workspace link too.\n\n### c. A dependency that imports `void/kv` skips the guard\n\nThe guard turns `import 'void/kv'` in app code into a clear error. A package in `node_modules` that imports `void/kv` stays external, and Node loads it without going through Vite. With a workspace link:\n\n- dev: the app's own `void/kv` route fails with `target: 'void/kv' is not available with target 'node'`. The package's route returns `env: Cloudflare env is unavailable. Use void runtime bindings inside Nuxt/SvelteKit/Analog server request handlers or Worker handlers.`\n- build: no guard error; `dist/ssr` keeps `import ... from \"xa-lib\"`.\n\n### d. `AGENTS.md` lists the wrong imports\n\n`packages/void/AGENTS.md:40` says non-CF targets block `void/ws`. The code does not block it, and `docs/reference/config.md:269` says it is not blocked on purpose. The code blocks `void/sandbox`, which the list leaves out.\n\n## Repro\n\na. Node-target pages app with `void` and `@void/react` installed from npm; a page action that throws `new ValidationError({ email: 'Email already taken' })`; `vp build && vp preview`; POST the form.\n\nb.\n```ts\n// void.config.ts\nimport { defineConfig } from 'void/config';\nexport default defineConfig({ target: 'node' });\n\n// routes/api/ping.ts (no pages/ folder)\nimport { defineHandler } from 'void';\nexport const GET = defineHandler(() => ({ ok: true }));\n```\nRun `vp build`.\n\nc. Add a package `xa-lib` in `node_modules` whose `index.js` imports `{ kv } from 'void/kv'` and calls `kv.put`. Import it from a route. Run `vp dev` and request the route; run `vp build`.\n\n## Cause\n\n- a. `packages/void/src/plugin-node-target.ts:144-151` inlines `void` (`ssr.noExternal`) only when the command is not `build`. In the build, Vite externalizes a bare import that resolves into `node_modules`. Void's generated code imports runtime files by path, so it gets a second copy. On main (`:144-147`) neither dev nor build inlines it. Note: adding `noExternal: ['void', /^@void\\//]` to the build alone fails, because Rolldown cannot resolve `cloudflare:workers` from `env-raw`.\n- b. `plugin-node-target.ts:180-185` returns `build.ssr: true` and no `builder` for API-only apps. Vite's CLI then uses the legacy builder, which creates only an `ssr` environment. `buildApp` (`:191-196`) still runs: the `ssr` build works, then `builder.build(builder.environments.client)` (`:195`) gets `undefined`. The comment at `:188-190` says the hook does not run for API-only apps; that is no longer true. Same code on main (`:187-192`).\n- c. The guard is a `resolveId` hook (`plugin-node-target.ts:118-126`). Imports inside an external package never reach it.\n- d. `CF_ONLY_IMPORTS` at `plugin-node-target.ts:9-17` against `packages/void/AGENTS.md:40`.\n\n## Suggested fix\n\n- a. Bundle `void` and `@void/*` into the Node-target production build, and give Node a resolution for `cloudflare:workers` in `env-raw` (a stub or alias). Add a packed-consumer check for a Node-target build with an installed `void`.\n- b. In `buildApp`, build only the environments that exist (skip `client` when it is missing), and fix the comment. Add a test that builds an API-only Node-target app.\n- c. Make the CF-only runtime modules throw the same \"not available with target 'node'\" error on first use under Node, or scan the build's dependencies for these imports.\n- d. Make the `AGENTS.md` list match `CF_ONLY_IMPORTS`.\n\n## Evidence\n\n- a. Runs with npm and pnpm installs of the packed `void`, before and after #413's installed-void change: preview 500 both times; dev 500 before and 200 after; workspace link 200 in dev and preview.\n- b. Reproduced with the head of #413 and a workspace link (Vite+ 1.1.0). The code is the same on main.\n- c. Reproduced with the head of #413 and a workspace link, in dev and build.\n- d. Code read.\n- #413 makes dev inline `void` (part of a). It does not change b, c or d.\n\n🤖 Generated with [Claude Code](https://claude.com/claude-code)\n\nhttps://claude.ai/code/session_0123r5HnanmW2VUrZ7VWDufH\n","author":{"url":"https://github.com/Brooooooklyn","@type":"Person","name":"Brooooooklyn"},"datePublished":"2026-10-14T04:05:27Z","url":"https://github.com/voidzero-dev/void/issues/416"}
| react-profiling | 0 |
| react-import-map | react,react-dom,react-dom/client,react-dom/profiling,react-is,react-reconciler,react/compiler-runtime,react/jsx-dev-runtime,react/jsx-runtime,scheduler@d5750093facf |
| route-pattern | /_view_fragments/issues/show/:user_id/:repository/:id/issue_layout(.:format) |
| route-controller | voltron_issues_fragments |
| route-action | issue_layout |
| fetch-nonce | v2:9276ef81-4363-f4bf-5f66-2243b00e9356 |
| current-catalog-service-hash | 81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114 |
| request-id | 98A8:277BD5:1CAF774:26E1BD5:6AFB96FB |
| html-safe-nonce | 2a2d90ba17caaa81818de9ac2dc19f60ef9650bbaff19ee4845026a674e8ed79 |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiI5OEE4OjI3N0JENToxQ0FGNzc0OjI2RTFCRDU6NkFGQjk2RkIiLCJ2aXNpdG9yX2lkIjoiODYzMTMyNzY3MTgyMjU1NDg3NSIsInJlZ2lvbl9lZGdlIjoiaWFkIiwicmVnaW9uX3JlbmRlciI6ImlhZCJ9 |
| visitor-hmac | c5ab11312ab42c3fef8868d1569c375c859cb6de5f6b637984ac0ecdb6839dcf |
| hovercard-subject-tag | issue:5841737981 |
| github-keyboard-shortcuts | repository,issues,copilot |
| google-site-verification | Apib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I |
| octolytics-url | https://collector.github.com/github/collect |
| analytics-location | / |
| fb:app_id | 1401488693436528 |
| apple-itunes-app | app-id=1477376905, app-argument=https://github.com/_view_fragments/issues/show/voidzero-dev/void/416/issue_layout |
| twitter:image | https://opengraph.githubassets.com/0dab5a5267805ae0bb7dcf72222e2b93b6499ecd431644156abed7084fa19109/voidzero-dev/void/issues/416 |
| twitter:card | summary_large_image |
| og:image | https://opengraph.githubassets.com/0dab5a5267805ae0bb7dcf72222e2b93b6499ecd431644156abed7084fa19109/voidzero-dev/void/issues/416 |
| og:image:alt | Problem Four problems with target: 'node': What the user does What happens a Installs void from npm, builds a pages app, runs vp preview A ValidationError thrown in an action gives 500 b Builds an ... |
| og:image:width | 1200 |
| og:image:height | 600 |
| og:site_name | GitHub |
| og:type | object |
| og:author:username | Brooooooklyn |
| hostname | github.com |
| expected-hostname | github.com |
| None | 4f01efe06174a5ba6342fd58e42d02295e0675bedbb465d6bef2dbaec8e46556 |
| turbo-cache-control | no-preview |
| go-import | github.com/voidzero-dev/void git https://github.com/voidzero-dev/void.git |
| octolytics-dimension-user_id | 149750581 |
| octolytics-dimension-user_login | voidzero-dev |
| octolytics-dimension-repository_id | 1164437080 |
| octolytics-dimension-repository_nwo | voidzero-dev/void |
| octolytics-dimension-repository_public | true |
| octolytics-dimension-repository_is_fork | false |
| octolytics-dimension-repository_network_root_id | 1164437080 |
| octolytics-dimension-repository_network_root_nwo | voidzero-dev/void |
| turbo-body-classes | logged-out env-production page-responsive |
| disable-turbo | false |
| browser-stats-url | https://api.github.com/_private/browser/stats |
| browser-errors-url | https://api.github.com/_private/browser/errors |
| release | a52db8866b6543b4e83730cd6a6b1360f1a9e4dc |
| ui-target | full |
| theme-color | #1e2327 |
| color-scheme | light dark |
| react-app-name | issues |
Links:
Viewport: width=device-width