@solidjs/vite-plugin 3.0.0-next.28 → 3.0.0-next.29

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020-2026 Alexandre Mouton-Brady and Solid contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -222,6 +222,41 @@ The Fetchable wrapper deliberately accepts only the request. Hosts may pass
 environment or execution-context arguments after it; those are not the
 Solid options accepted by `handleRequest`'s second parameter.
 
+Among those options, **`event`** is the supported public seam for extending
+the request event: its fields spread into the event at creation, so a custom
+server entry (or a host wrapper) can attach whatever its platform knows and
+read it back anywhere in the request scope with `getRequestEvent()`. The
+conventional field name is `nativeEvent` — the platform's raw request
+object. A Node entry passes the `IncomingMessage`:
+
+```js
+import { createServer } from 'node:http';
+import { handleRequest } from './dist/server/server.js';
+
+createServer(async (req, res) => {
+  const response = await handleRequest(webRequest(req), {
+    event: { nativeEvent: req },
+  });
+  // ... write response to res
+});
+```
+
+```js
+// anywhere inside the request scope (middleware, setup, app code)
+import { getRequestEvent } from '@solidjs/web';
+const event = getRequestEvent();
+event.nativeEvent; // the Node IncomingMessage the entry passed
+```
+
+The plugin's own dev and preview middlewares (and the server-function dev
+middleware) pass `event: { nativeEvent: req }` with the Node request, so
+`getRequestEvent().nativeEvent` answers the same under `vite dev` and
+`vite preview` as behind a Node entry written like the above. For the
+client's IP on bare Node, read `event.nativeEvent.socket.remoteAddress`;
+behind a proxy or load balancer that address is the proxy's, so read the
+forwarding headers off `event.request` instead (`x-forwarded-for` and
+friends) — only when you trust the proxy that set them.
+
 - **Preview**: `vite build && vite preview` runs the production artifact
   with no server file — Vite's preview statics serve `dist/client`, and
   everything else (pages, the server-function endpoint, middleware)
@@ -361,7 +396,14 @@ import { env } from 'virtual:env/client'; // the VITE_-prefixed client vars
   is fine). Platform-injected vars that don't exist at build time work,
   secrets rotate without a rebuild, and no secret value exists in any
   dist artifact; an invalid server environment fails boot with the same
-  per-key report.
+  per-key report. Boot validation is synchronous: the generated server
+  env module contains no top-level await, so the server bundle works
+  under any downstream build target (Nitro's node-server preset,
+  es2020 — no `esnext` override needed). The flip side: `server`
+  validators must be synchronous — an async refinement/transform on a
+  server key is rejected at config time with the fix in the message
+  (`client` keys may stay async; they are awaited at build time where
+  the values are baked).
 - **Leaks are errors.** Importing `virtual:env/server` from a client
   module graph is a hard error naming the importer (the app root and
   everything it imports hydrate — they are client code; keep server env
@@ -434,6 +476,19 @@ Two explicit switches remain for custom host setups:
    serving, hands only server-function dispatch in dev to the host. For
    setups without `start`, or when only the endpoint should move.
 
+**`virtual:solid-manifest`** exposes the client asset manifest that serving
+works from — a server-side module, available in dev and in SSR builds. In
+an SSR build its default export is the parsed client manifest
+(`dist/client/.vite/manifest.json`), keyed by source path with the resolved
+Vite `base` attached as `_base`; in dev it exports the live asset resolver
+the plugin uses for dev CSS collection instead of a static object. This is
+the seam for frameworks and routers that do their own asset gating —
+deciding which scripts and styles a response carries, as the TanStack Start
+integration does — without re-reading the manifest from disk or re-deriving
+`base`. Ambient types ship with the plugin
+(`/// <reference types="@solidjs/vite-plugin/virtual-solid-manifest" />`);
+see that `.d.ts` and the exported `ViteManifest` type for the full shape.
+
 Without `ssr: true` — **client mode** (experimental), the same conventions
 with client-only rendering:
 

package/dist/cjs/index.cjs

@@ -934,7 +934,15 @@ function serverFunctions(options = {}, internal = {}) {
     // the same value (config merges per key), but the handler graph cannot
     // depend on that: in dev, a mutation from an already-open page can be
     // the first request after a server restart.
-    `configureServerFunctionsServer({ provideEvent: provideRequestEvent, endpoint: ${JSON.stringify(resolvedEndpoint)}${components ? ', transformResult: frameTransformResult, transformFlightResult: frameTransformFlightResult, transformDirectResult: frameTransformDirectResult' : ''} });`, `export const endpoint = ${JSON.stringify(resolvedEndpoint)};`, `export function handleServerFunctionRequest(request, options) {`, `  return handle(request, { provideEvent: provideRequestEvent, ...options });`, `}`].join('\n');
+    `configureServerFunctionsServer({ provideEvent: provideRequestEvent, endpoint: ${JSON.stringify(resolvedEndpoint)}${components ? ', transformResult: frameTransformResult, transformFlightResult: frameTransformFlightResult, transformDirectResult: frameTransformDirectResult' : ''} });`, `export const endpoint = ${JSON.stringify(resolvedEndpoint)};`,
+    // `options.event` is the same wrapper->event extension seam the SSR
+    // handler's handleRequest carries (conventionally `nativeEvent`, the
+    // platform's raw request object). The runtime's standalone handler
+    // creates its own event (`{ request, locals }`) with no init
+    // parameter, so the extension threads through its existing
+    // `createEvent` option instead — spread before `...options` so an
+    // explicit host-provided createEvent still wins.
+    `export function handleServerFunctionRequest(request, options) {`, `  const { event: eventInit, ...rest } = options || {};`, `  return handle(request, {`, `    provideEvent: provideRequestEvent,`, `    ...(eventInit ? { createEvent: (req) => ({ request: req, locals: {}, ...eventInit }) } : {}),`, `    ...rest,`, `  });`, `}`].join('\n');
   }
 
   // Function IDs are `xxHash32(root-relative path)-<count>` (see compile.ts),
@@ -1018,7 +1026,15 @@ function serverFunctions(options = {}, internal = {}) {
             // middleware chain and one stub-backed request event front the
             // endpoint exactly as they front page SSR.
             const handler = await server.ssrLoadModule(internal.ssrHandler ?? HANDLER_ID$1);
-            const response = internal.ssrHandler ? await handler.handleRequest(webRequestFromNode(req, dispatchUrl)) : await handler.handleServerFunctionRequest(webRequestFromNode(req, dispatchUrl));
+            // Both dispatch shapes carry the raw Node request on the event
+            // (the `options.event` seam), matching the SSR dev middleware
+            // and what a production Node entry passes.
+            const dispatchOptions = {
+              event: {
+                nativeEvent: req
+              }
+            };
+            const response = internal.ssrHandler ? await handler.handleRequest(webRequestFromNode(req, dispatchUrl), dispatchOptions) : await handler.handleServerFunctionRequest(webRequestFromNode(req, dispatchUrl), dispatchOptions);
             await sendWebResponse(res, response);
           })().catch(error => {
             if (error instanceof Error) server.ssrFixStacktrace(error);
@@ -1590,7 +1606,14 @@ function startServe(options, internal = {}) {
     // The runtime's response-head lifecycle: commit at shell flush,
     // pre-flush Location as a real redirect, post-flush Location as the
     // script fallback; the transform injects the doctype/head pieces.
-    `  return createSSRResponse(result, event, {`, `    responseInit: options.responseInit,`, `    nonce: options.nonce,`, `    transformChunk: createHtmlChunkTransform(clientEntry, options.devHead),`, `  });`, `}`, ``, `export async function handleRequest(request, options = {}) {`, `  const event = createRequestEvent(request);`,
+    `  return createSSRResponse(result, event, {`, `    responseInit: options.responseInit,`, `    nonce: options.nonce,`, `    transformChunk: createHtmlChunkTransform(clientEntry, options.devHead),`, `  });`, `}`, ``, `export async function handleRequest(request, options = {}) {`,
+    // `options.event` is the public wrapper->event extension seam: extra
+    // fields (conventionally `nativeEvent`, the platform's raw request
+    // object) spread over the event's defaults at creation, so hosts and
+    // custom server entries can extend what getRequestEvent() answers
+    // with — no new convention beyond createRequestEvent's own init
+    // parameter (spreading undefined is a no-op).
+    `  const event = createRequestEvent(request, options.event);`,
     // Middleware runs inside the request scope, after event creation —
     // getRequestEvent() answers in middleware exactly as in app code, and
     // nothing reaches the wire until the outermost middleware returns.
@@ -1805,7 +1828,14 @@ function startServe(options, internal = {}) {
             // server-function endpoint) and hands the URL to application
             // code, so restore the base — the deployed production handler
             // receives base-prefixed URLs and preview must match it.
-            const response = await handler.handleRequest(webRequestFromNode(req, joinBase(base, req.url || '/')));
+            const response = await handler.handleRequest(webRequestFromNode(req, joinBase(base, req.url || '/')),
+            // Same event extension the dev middleware and a production
+            // Node entry pass: the raw Node request as `nativeEvent`.
+            {
+              event: {
+                nativeEvent: req
+              }
+            });
             // Preview's compression middleware buffers whole responses;
             // opting HTML out keeps SSR streaming observable, matching
             // production behavior.
@@ -1857,7 +1887,14 @@ function startServe(options, internal = {}) {
             // deployed handler receives base-prefixed requests).
             const response = await handler.handleRequest(webRequestFromNode(req, joinBase(base, req.url || '/')), {
               devHead,
-              pageRequest
+              pageRequest,
+              // The raw Node request on the event, matching what a
+              // production Node server entry passes through the
+              // `options.event` seam — getRequestEvent().nativeEvent
+              // answers the same in dev as deployed.
+              event: {
+                nativeEvent: req
+              }
             });
             // A non-page request the chain never handled: the terminal
             // dispatch answered with the marked 404 — hand it back to
@@ -1938,6 +1975,11 @@ function startServe(options, internal = {}) {
 // time work, secrets rotate without a rebuild, and no secret value exists
 // in any dist artifact. Build-time server-value failures downgrade to a
 // warning (boot enforces); dev failures stay hard errors — dev IS runtime.
+// Boot validation is synchronous by design: the generated server module
+// contains no top-level await (a TLA chunk forces esnext on downstream
+// bundlers — Nitro's node-server preset rejects it), which is why async
+// validators are rejected for `server` keys (client keys may stay async;
+// they are awaited at build time where the values are baked).
 //
 // A failed validation fails the build; in dev it renders Vite's error
 // overlay with the per-key report (the virtual modules throw it on load)
@@ -2208,7 +2250,23 @@ function startEnv(option) {
     for (const side of ['server', 'client']) {
       for (const [key, validator] of Object.entries(schema[side] ?? {})) {
         let result = validator['~standard'].validate(raw[key]);
-        if (result instanceof Promise) result = await result;
+        if (result instanceof Promise) {
+          // Async validation is fine for `client` keys — their values are
+          // baked right here at build time, where awaiting costs nothing.
+          // `server` keys validate process.env at boot through generated
+          // code that is deliberately synchronous (a top-level await in the
+          // server env chunk forces esnext on every downstream bundle
+          // target — Nitro's node-server preset rejects it outright), so a
+          // Promise-returning server validator could only ever fail at
+          // deploy boot. Async-ness is a property of the schema, not the
+          // value, so fail fast here with the fix in the message. Boot
+          // still backstops (schemas whose sync prefix short-circuits at
+          // build time can go async on real values).
+          if (side === 'server') {
+            throw new Error(`[@solidjs/vite-plugin] server env var "${key}" in ${envFile} uses an async ` + `validator (validate() returned a Promise). Server env is validated ` + `synchronously at boot — the generated module contains no top-level ` + `await, so server bundles work on non-esnext targets — which async ` + `validators cannot do. Make the validator synchronous (drop async ` + `refinements/transforms), or run the async check in application code.`);
+          }
+          result = await result;
+        }
         if (result.issues && result.issues.length) {
           for (const issue of result.issues) {
             const at = (issue.path ?? []).map(segment => typeof segment === 'object' && segment !== null && 'key' in segment ? String(segment.key) : String(segment)).join('.');
@@ -2285,6 +2343,16 @@ function startEnv(option) {
   // means. Platform-injected vars that don't exist at build time work,
   // secrets rotate without a rebuild, and no secret value exists in any
   // dist artifact.
+  //
+  // The generated code is deliberately free of top-level await. Module
+  // init is the only point where "validated and frozen before any
+  // importer's body runs" can be guaranteed — user server modules read
+  // `env.KEY` at their own top level — and the only async thing here is
+  // Standard Schema's option to return a Promise from validate(). A TLA
+  // chunk breaks every downstream bundler with a non-esnext target
+  // (Nitro's node-server preset in practice), so validation runs
+  // synchronously and a Promise-returning server validator is itself a
+  // boot issue (build/config time rejects it earlier when detectable).
   function serverEnvModuleCode(loaded) {
     const serverKeys = Object.keys(loaded.schema.server ?? {});
     const baked = `const __env = ${JSON.stringify(loaded.client)};`;
@@ -2295,7 +2363,7 @@ function startEnv(option) {
       };
     }
     return {
-      code: [`// Generated by @solidjs/vite-plugin (start.env) — server env.`, `// Server values are read from process.env and validated at boot;`, `// client (public) values are baked at build time.`, `import __schema from ${JSON.stringify(envFileAbs)};`, baked, `const __issues = [];`, `for (const __key of ${JSON.stringify(serverKeys)}) {`, `  let __result = __schema.server[__key]['~standard'].validate(process.env[__key]);`, `  if (__result instanceof Promise) __result = await __result;`, `  if (__result.issues && __result.issues.length) {`, `    for (const __issue of __result.issues) __issues.push('  \\u2717 ' + __key + ': ' + __issue.message);`, `  } else {`, `    __env[__key] = __result.value;`, `  }`, `}`, `if (__issues.length) {`, `  throw new Error(`, `    '[@solidjs/vite-plugin] server env validation failed at boot (' + __issues.length +`, `    ' issue' + (__issues.length === 1 ? '' : 's') + ') \\u2014 schema: ' + ${JSON.stringify(envFile)} +`, `    '\\n\\n' + __issues.join('\\n') +`, `    '\\n\\nServer env is read from process.env at boot, not baked at build time: set the ' +`, `    'variables in the server process environment.'`, `  );`, `}`, `export const env = Object.freeze(__env);`, `export default env;`].join('\n'),
+      code: [`// Generated by @solidjs/vite-plugin (start.env) — server env.`, `// Server values are read from process.env and validated at boot;`, `// client (public) values are baked at build time. Boot validation is`, `// synchronous on purpose: a top-level await here would force esnext`, `// on every downstream bundle target (Nitro's node-server preset and`, `// anything else below esnext rejects a TLA chunk outright).`, `import __schema from ${JSON.stringify(envFileAbs)};`, baked, `const __issues = [];`, `for (const __key of ${JSON.stringify(serverKeys)}) {`, `  const __result = __schema.server[__key]['~standard'].validate(process.env[__key]);`, `  if (__result && typeof __result.then === 'function') {`, `    __issues.push('  \\u2717 ' + __key + ': validator returned a Promise \\u2014 async validators are not supported for server keys (boot validation is synchronous so the server bundle carries no top-level await); make this validator synchronous');`, `  } else if (__result.issues && __result.issues.length) {`, `    for (const __issue of __result.issues) __issues.push('  \\u2717 ' + __key + ': ' + __issue.message);`, `  } else {`, `    __env[__key] = __result.value;`, `  }`, `}`, `if (__issues.length) {`, `  throw new Error(`, `    '[@solidjs/vite-plugin] server env validation failed at boot (' + __issues.length +`, `    ' issue' + (__issues.length === 1 ? '' : 's') + ') \\u2014 schema: ' + ${JSON.stringify(envFile)} +`, `    '\\n\\n' + __issues.join('\\n') +`, `    '\\n\\nServer env is read from process.env at boot, not baked at build time: set the ' +`, `    'variables in the server process environment.'`, `  );`, `}`, `export const env = Object.freeze(__env);`, `export default env;`].join('\n'),
       moduleType: 'js'
     };
   }
@@ -2971,12 +3039,19 @@ function solidPlugin(options = {}) {
           exclude: solidPkgsConfig.optimizeDeps.exclude,
           // Vite 8+ uses Rolldown for dependency scanning. Rolldown defaults to
           // React's automatic JSX runtime for .tsx files, injecting a
-          // react/jsx-dev-runtime import. Tell it to preserve JSX as-is since
-          // this plugin handles JSX transformation via babel-preset-solid.
+          // react/jsx-dev-runtime import that fails to resolve and aborts the
+          // scan. 'preserve' is no fix: the scanner re-parses the transformed
+          // output as plain JS, so any preserved JSX is a hard parse error
+          // (issue #262). The classic runtime is the only scan-safe lowering:
+          // it emits bare `React.createElement` calls without injecting any
+          // import, and the scan output is never executed — it only exists so
+          // rolldown can walk the import graph.
           ...(isVite8 ? {
             rolldownOptions: {
               transform: {
-                jsx: 'preserve'
+                jsx: {
+                  runtime: 'classic'
+                }
               }
             }
           } : {})