@nifrajs/web 2.1.0 → 2.3.0

package/src/vite.ts

@@ -1,14 +1,14 @@
 /**
- * `@nifrajs/web/vite` — a **dev-only** server with true HMR, backed by Vite in middleware mode. nifra's
+ * `@nifrajs/web/vite` - a **dev-only** server with true HMR, backed by Vite in middleware mode. nifra's
  * production pipeline stays Bun-native (`@nifrajs/web/build` → `Bun.build`); this is purely for the dev
  * loop. Bun's own HMR is dev-server-only and DCE's `import.meta.hot` under `Bun.build` (nifra's bundler),
  * so HMR comes from Vite + the framework's official Vite plugin (React Fast Refresh, Vue/Svelte/Solid
- * HMR) — which you inject via `plugins` (the same structural-injection idiom as the Bun/codec plugins).
+ * HMR) - which you inject via `plugins` (the same structural-injection idiom as the Bun/codec plugins).
  *
  * Flow: Vite serves + HMR-swaps the client modules (nifra's codegen'd entry + the route files); nifra
  * still **SSRs** each request, and the rendered HTML is run through `vite.transformIndexHtml` so Vite
  * injects its HMR client + the framework's refresh preamble. Node `http` (not `Bun.serve`) because
- * Vite's `middlewares` are Connect-style — it runs fine under Bun.
+ * Vite's `middlewares` are Connect-style - it runs fine under Bun.
  */
 import { writeFileSync } from "node:fs"
 import {
@@ -18,20 +18,29 @@ import {
 } from "node:http"
 import { relative, resolve as resolvePath } from "node:path"
 import { renderDevErrorOverlay } from "./dev-error.ts"
+import { listenOrExplain } from "./dev-port.ts"
 import { discoverRoutes } from "./fs.ts"
 import { DEFAULT_DEV_PORT, generateClientEntry } from "./index.ts"
+import { vitePublicEnvPrefix } from "./internal/server-boundary.ts"
+import { importVite } from "./internal/vite-import.ts"
+import { viteServerFnStub } from "./plugins/vite-server-fn.ts"
+import { viteServerOnlyEmpty } from "./plugins/vite-server-only.ts"
 
-/** Minimal app surface — `createWebApp(...)` satisfies it. */
+/** Minimal app surface - `createWebApp(...)` satisfies it. */
 interface FetchApp {
   fetch(request: Request): Response | Promise<Response>
 }
 
 // Structural slice of the Vite dev server this module drives (avoids a hard type dep on `vite`).
 interface ViteLike {
+  /** Load a module through VITE's graph - the seam that makes the Vite pipeline own SSR too. */
+  ssrLoadModule(url: string): Promise<Record<string, unknown>>
   readonly middlewares: (req: IncomingMessage, res: ServerResponse, next: () => void) => void
   transformIndexHtml(url: string, html: string): Promise<string>
   ssrFixStacktrace(err: Error): void
-  readonly watcher: { on(event: "change", cb: (path: string) => void): void }
+  readonly watcher: {
+    on(event: "change" | "add" | "unlink", cb: (path: string) => void): void
+  }
   close(): Promise<void>
 }
 interface ViteModule {
@@ -40,7 +49,7 @@ interface ViteModule {
   readonly rolldownVersion?: string
 }
 
-// `node:http` server type the request handler runs on (also the HMR WebSocket host — see below).
+// `node:http` server type the request handler runs on (also the HMR WebSocket host - see below).
 type NodeHttpServer = ReturnType<typeof createHttpServer>
 
 export interface ViteDevServerOptions {
@@ -49,15 +58,22 @@ export interface ViteDevServerOptions {
   /** Client runtime module providing `mountRouter` (e.g. `"@nifrajs/web-react/client"`). */
   readonly clientModule: string
   /**
-   * Build the nifra app for the given dev client-entry URL. `importQuery` changes when a route file
-   * changes — thread it into `discoverRoutes(routesDir, { importQuery })` so a hard reload SSRs edited
-   * modules (HMR handles the live client update; this keeps server-render fresh).
+   * Build the nifra app for the given dev client-entry URL.
+   *
+   * `load` resolves a route module through **Vite's** graph (`ssrLoadModule`). Pass it to
+   * `discoverRoutes(routesDir, { load })` so SSR and the client are resolved by the SAME toolchain.
+   * Without it SSR resolves through Bun while the client resolves through Vite - two resolvers, one
+   * process - which is what makes `resolve.dedupe` fail to reach SSR and produces the dual-React
+   * crash. Vite re-evaluates on change, so no `importQuery` cache-buster is needed alongside it.
    */
-  readonly createApp: (clientEntry: string, importQuery: string) => FetchApp | Promise<FetchApp>
-  /** Vite plugins — inject your framework's official plugin, e.g. `[react()]`. */
+  readonly createApp: (
+    clientEntry: string,
+    load: (absolutePath: string) => Promise<unknown>,
+  ) => FetchApp | Promise<FetchApp>
+  /** Vite plugins - inject your framework's official plugin, e.g. `[react()]`. */
   readonly plugins?: readonly unknown[]
   /**
-   * Extra `resolve.conditions` prepended ahead of nifra's defaults — some frameworks need their own
+   * Extra `resolve.conditions` prepended ahead of nifra's defaults - some frameworks need their own
    * (e.g. Solid's `"solid"` condition routes `solid-js` to its source/JSX-dev build).
    */
   readonly conditions?: readonly string[]
@@ -72,10 +88,14 @@ export interface ViteDevServerOptions {
   readonly port?: number
   /**
    * Use polling for the file watcher. Native fs events (fsevents/inotify) are unreliable inside
-   * containers, networked filesystems, and some sandboxes — there, HMR silently never fires. Set
+   * containers, networked filesystems, and some sandboxes - there, HMR silently never fires. Set
    * `true` (or the env var `CHOKIDAR_USEPOLLING=1`) to poll instead. Default: off (native events).
    */
   readonly poll?: boolean
+  /** Vite public directory. Defaults to `<root>/public`; `false` disables it. */
+  readonly publicDir?: string | false
+  /** Client-visible environment prefix (default `"PUBLIC_"`; empty disables exposure). */
+  readonly publicEnvPrefix?: string
 }
 
 export interface ViteDevServer {
@@ -114,11 +134,11 @@ function toWebRequest(req: IncomingMessage, body: Buffer | undefined): Request {
 }
 
 // A Vite `config` hook: a plain function, OR the object form `{ handler, order }` Vite accepts for hook
-// ordering (`order: "pre" | "post"`). We wrap the handler in either shape — see normalizeRolldownPlugins.
+// ordering (`order: "pre" | "post"`). We wrap the handler in either shape - see normalizeRolldownPlugins.
 type ConfigFn = (config: unknown, env: unknown) => unknown
 type ConfigHook = ConfigFn | { readonly handler: ConfigFn; readonly order?: unknown }
 
-// A Vite plugin — the only hook we wrap is `config`. Typed structurally (no `vite` type dep). Everything
+// A Vite plugin - the only hook we wrap is `config`. Typed structurally (no `vite` type dep). Everything
 // else on the plugin object is preserved by spread, so wrapping is transparent to Vite.
 interface VitePluginLike {
   readonly name?: string
@@ -126,7 +146,7 @@ interface VitePluginLike {
   readonly [key: string]: unknown
 }
 
-/** The bits of a Node ServerResponse `pipeWebBodyToNode` touches — structural, to avoid a node:http dep here. */
+/** The bits of a Node ServerResponse `pipeWebBodyToNode` touches - structural, to avoid a node:http dep here. */
 interface NodeResLike {
   flushHeaders?(): void
   on(event: "close", cb: () => void): void
@@ -141,7 +161,7 @@ interface NodeHeaderSink {
 
 /**
  * Copy a Web `Response`'s headers onto a Node response, emitting EACH `Set-Cookie` as its own header. The
- * `Headers` iterator (and `.get`) join multiple set-cookie values with ", ", which corrupts cookies — e.g.
+ * `Headers` iterator (and `.get`) join multiple set-cookie values with ", ", which corrupts cookies - e.g.
  * better-auth's `session_token` + `session_data` collapse into one unparseable cookie and the session is
  * silently lost. `getSetCookie()` returns them split; Node's `setHeader` emits one header per array element.
  */
@@ -156,7 +176,7 @@ export function applyResponseHeaders(headers: Headers, res: NodeHeaderSink): voi
 
 /**
  * Stream a Web `Response` body to a Node response chunk-by-chunk. Buffering the whole body (e.g.
- * `arrayBuffer()`) waits for the stream to END — which an open-ended SSE (`text/event-stream`) body never
+ * `arrayBuffer()`) waits for the stream to END - which an open-ended SSE (`text/event-stream`) body never
  * does, so it hung `nifra dev` (the Bun production server streamed it fine). This flushes each chunk as it
  * arrives and cancels the reader if the client disconnects; a finite body just streams its chunk(s) + ends.
  */
@@ -178,23 +198,23 @@ export async function pipeWebBodyToNode(
       res.write(value)
     }
   } catch {
-    // client disconnected mid-stream — the `close` handler already cancelled the reader
+    // client disconnected mid-stream - the `close` handler already cancelled the reader
   }
   res.end()
 }
 
 /**
  * Strip `optimizeDeps.rollupOptions.jsx` from a plugin's `config` hook output when running under
- * rolldown-vite — the source of the scary, harmless `Warning: Invalid input options … "jsx" Invalid
+ * rolldown-vite - the source of the scary, harmless `Warning: Invalid input options … "jsx" Invalid
  * key: Expected never but received "jsx"` on `nifra dev`.
  *
  * Why it happens: `@vitejs/plugin-react@4.x` (and peers) target an *older* rolldown-vite optimizeDeps
- * API — they inject `optimizeDeps.rollupOptions.jsx` to tell the dep pre-bundler to transform JSX. Vite
+ * API - they inject `optimizeDeps.rollupOptions.jsx` to tell the dep pre-bundler to transform JSX. Vite
  * 8's rolldown dep-optimizer renamed that surface to `optimizeDeps.rolldownOptions` (and moved jsx under
  * `transform.jsx`), so the stale `rollupOptions.jsx` is an unrecognized input option → the warning. It's
  * a version-skew artifact, not a real misconfig: the route source JSX transform runs through the
  * plugin's own `transform` hook (untouched here), and node_modules deps that get pre-bundled almost
- * never contain raw JSX — so dropping the dead key changes no behavior and keeps HMR/Fast Refresh
+ * never contain raw JSX - so dropping the dead key changes no behavior and keeps HMR/Fast Refresh
  * intact. We *strip* (rather than translate to `rolldownOptions`) so the fix is version-agnostic: a
  * plugin already emitting the correct `rolldownOptions` is left untouched, and a future plugin bump that
  * stops emitting `rollupOptions.jsx` makes this a no-op.
@@ -202,12 +222,12 @@ export async function pipeWebBodyToNode(
  * Scoped narrowly: only the `optimizeDeps.rollupOptions.jsx` key is removed, only under rolldown-vite,
  * and only from the value a plugin's `config` hook returns. Non-rolldown Vite is passed through verbatim.
  *
- * FLATTEN FIRST: a Vite plugin factory may return an ARRAY of plugins — `@vitejs/plugin-react`'s `react()`
+ * FLATTEN FIRST: a Vite plugin factory may return an ARRAY of plugins - `@vitejs/plugin-react`'s `react()`
  * returns `[vite:react-babel, vite:react-refresh]`, and it's `react:react-babel`'s `config` hook that emits
  * the offending `optimizeDeps.rollupOptions.jsx`. `nifra.config.ts` writes `vitePlugins = [react()]`, so the
  * plugin list arrives NESTED (`[[babel, refresh]]`). Without flattening, `.map` sees the inner array (which
- * has no `config`), leaves it untouched, and Vite — which flattens plugin arrays itself before running them
- * — then executes the un-stripped babel hook, so the warning survives. Flattening here (Vite accepts a flat
+ * has no `config`), leaves it untouched, and Vite - which flattens plugin arrays itself before running them
+ * - then executes the un-stripped babel hook, so the warning survives. Flattening here (Vite accepts a flat
  * list identically) is what lets the strip reach every real plugin.
  */
 export function normalizeRolldownPlugins(
@@ -237,7 +257,7 @@ export function normalizeRolldownPlugins(
     if (typeof handler !== "function") return plugin
     const wrappedHandler: ConfigFn = (config, env) => {
       const returned = handler(config, env)
-      // The hook may return a promise — normalize both shapes.
+      // The hook may return a promise - normalize both shapes.
       return returned instanceof Promise ? returned.then(stripJsxKey) : stripJsxKey(returned)
     }
     // Preserve the ORIGINAL shape: a function stays a function; the object form keeps its `order`
@@ -259,21 +279,23 @@ export async function createViteDevServer(options: ViteDevServerOptions): Promis
   const port = options.port ?? DEFAULT_DEV_PORT
 
   // Codegen the client entry with Vite-servable, root-relative specifiers (e.g. `/routes/index.tsx`).
-  const manifest = discoverRoutes(routesDir)
   const toUrl = (file: string): string => `/${relative(root, `${routesDir}/${file}`)}`
-  writeFileSync(
-    resolvePath(root, DEV_ENTRY),
-    generateClientEntry(manifest, { clientModule: options.clientModule, resolve: toUrl }),
-  )
+  const writeClientEntry = (): void => {
+    const manifest = discoverRoutes(routesDir)
+    writeFileSync(
+      resolvePath(root, DEV_ENTRY),
+      generateClientEntry(manifest, { clientModule: options.clientModule, resolve: toUrl }),
+    )
+  }
+  writeClientEntry()
   const entryUrl = `/${DEV_ENTRY}`
 
   // Create our HTTP server FIRST, then hand it to Vite as the HMR WebSocket host (`hmr.server`). In
-  // middleware mode Vite would otherwise open a *separate* ws port (24678) — fragile: it conflicts
+  // middleware mode Vite would otherwise open a *separate* ws port (24678) - fragile: it conflicts
   // across restarts ("Port undefined is already in use" → the client never connects). Sharing one
   // port means HMR rides the same origin as the app, robust across restarts. The handler closes over
   // `vite`, which is assigned just below before the server starts listening.
   let vite!: ViteLike
-  let version = 0
   let app: FetchApp
 
   const server: NodeHttpServer = createHttpServer((req, res) => {
@@ -286,7 +308,7 @@ export async function createViteDevServer(options: ViteDevServerOptions): Promis
           const contentType = nifraRes.headers.get("content-type") ?? ""
           res.statusCode = nifraRes.status
           if (!contentType.includes("text/html")) {
-            // Data / redirect / asset response — pass through untouched, streamed (SSE-safe). Set-Cookie is
+            // Data / redirect / asset response - pass through untouched, streamed (SSE-safe). Set-Cookie is
             // emitted per-header so multi-cookie responses (e.g. better-auth sessions) aren't collapsed.
             applyResponseHeaders(nifraRes.headers, res)
             await pipeWebBodyToNode(nifraRes.body, res)
@@ -298,7 +320,7 @@ export async function createViteDevServer(options: ViteDevServerOptions): Promis
           res.end(html)
         } catch (err) {
           // Source-map the stack first (Vite maps the bundled frames back to your `.ts`), then render
-          // the readable dev overlay instead of a bare text dump. Dev-only — production maps to `_error`.
+          // the readable dev overlay instead of a bare text dump. Dev-only - production maps to `_error`.
           if (err instanceof Error) vite.ssrFixStacktrace(err)
           res.statusCode = 500
           res.setHeader("content-type", "text/html; charset=utf-8")
@@ -309,18 +331,23 @@ export async function createViteDevServer(options: ViteDevServerOptions): Promis
   })
 
   // `conditions: ["bun"]` makes Vite resolve nifra's workspace packages (`@nifrajs/web-react/client`, …) to
-  // their TS **source** — so the dev server needs no prior `dist` build of the adapter packages.
+  // their TS **source** - so the dev server needs no prior `dist` build of the adapter packages.
   const usePolling = options.poll ?? process.env.CHOKIDAR_USEPOLLING === "1"
-  const viteModule = (await import("vite")) as unknown as ViteModule
+  // Never `import("vite")` directly here: the guard in `importVite` has to run first, and the dev
+  // server importing vite unguarded is precisely what poisoned the module for the whole process.
+  const viteModule = await importVite<ViteModule>()
   const { createServer } = viteModule
   // Under rolldown-vite (Vite 8+), strip the stale `optimizeDeps.rollupOptions.jsx` some framework
-  // plugins still emit — it triggers a noisy "Invalid key … jsx" warning but does nothing useful here.
+  // plugins still emit - it triggers a noisy "Invalid key … jsx" warning but does nothing useful here.
   const plugins = normalizeRolldownPlugins(
     options.plugins ?? [],
     viteModule.rolldownVersion !== undefined,
   )
   vite = await createServer({
     root,
+    // Dev must not inherit Vite's default `VITE_*` exposure beside Nifra's documented boundary.
+    envPrefix: vitePublicEnvPrefix(options.publicEnvPrefix),
+    ...(options.publicDir !== undefined ? { publicDir: options.publicDir } : {}),
     appType: "custom",
     server: {
       middlewareMode: true,
@@ -328,34 +355,61 @@ export async function createViteDevServer(options: ViteDevServerOptions): Promis
       // Explicit watch config; poll when native fs events aren't delivered (containers/sandboxes).
       watch: usePolling ? { usePolling: true, interval: 80 } : {},
     },
-    plugins: [...plugins],
+    // Ahead of the user's plugins: a `*.fn` module must be replaced before anything else
+    // reads it, and the dev server is a client bundler like any other.
+    plugins: [viteServerFnStub(), viteServerOnlyEmpty(), ...plugins],
     resolve: {
       conditions: [...(options.conditions ?? []), "bun", "module", "browser", "development"],
       // Dedupe React to ONE copy. In a multi-root workspace a shared package can pull react/react-dom
       // from a SIBLING app's node_modules, so the dev server loads two React cores → a second hook
       // dispatcher → `resolveDispatcher().useState` null on any hook-using route (the error points at the
-      // component, not the resolution — brutal to diagnose). Mirrors the build-time reactDedupePlugin so
+      // component, not the resolution - brutal to diagnose). Mirrors the build-time reactDedupePlugin so
       // dev matches prod. No-op for non-React apps (the package simply isn't present to dedupe).
       dedupe: ["react", "react-dom"],
     },
     ...(options.define ? { define: options.define } : {}),
   })
 
-  app = await options.createApp(entryUrl, `v=${version}`)
+  const ssrLoad = (absolutePath: string): Promise<unknown> => vite.ssrLoadModule(absolutePath)
+  app = await options.createApp(entryUrl, ssrLoad)
 
-  // Keep server-render fresh on edits (Vite already HMRs the client live; this is for a hard reload).
-  vite.watcher.on("change", () => {
-    version += 1
-    Promise.resolve(options.createApp(entryUrl, `v=${version}`))
+  // Re-create the app on change so a hard reload picks up a route ADD/REMOVE (the manifest comes
+  // from a directory scan, which `ssrLoadModule` cannot invalidate). Module CONTENT no longer needs a
+  // version counter: Vite owns SSR resolution now and re-evaluates changed modules itself, which is
+  // the cache-busting the old `importQuery` was emulating against Bun's import cache.
+  let refreshVersion = 0
+  const refreshApp = (): void => {
+    const version = ++refreshVersion
+    Promise.resolve(options.createApp(entryUrl, ssrLoad))
       .then((next) => {
-        app = next
+        if (version === refreshVersion) app = next
       })
       .catch((err) => console.error("[nifra/web/vite] app re-create failed:", err))
-  })
+  }
+  vite.watcher.on("change", refreshApp)
+  for (const event of ["add", "unlink"] as const) {
+    vite.watcher.on(event, (path) => {
+      if (path.startsWith(`${routesDir}/`) || path.startsWith(`${routesDir}\\`)) writeClientEntry()
+      refreshApp()
+    })
+  }
 
-  await new Promise<void>((done) => server.listen(port, done))
+  try {
+    await listenOrExplain(server, port)
+  } catch (err) {
+    // Nothing is listening, but Vite is fully up by now - watchers, the dep optimizer, its own sockets -
+    // and every one of those keeps the event loop alive. Left open, the process prints the diagnosis and
+    // then HANGS on it, which is worse than the raw crash this guard replaced: the user sees a dev server
+    // that appears to be starting. Tear Vite down so the failure is terminal.
+    await vite.close().catch(() => {})
+    throw err
+  }
+  // Report the port actually BOUND, not the one requested. They differ for `port: 0`, which is how you
+  // ask the OS for a free one - the correct thing to do in a test or when running several apps at once.
+  // Echoing the request back would return a literal 0, which connects to nothing.
+  const address = server.address()
   return {
-    port,
+    port: typeof address === "object" && address !== null ? address.port : port,
     stop: async () => {
       server.close()
       await vite.close()