eliminate top-level await from the generated virtual:env/server module — boot validation used to conditionally await each Standard Schema validate() result, putting a TLA in the server env chunk whenever the schema had server keys, and any downstream bundler below esnext (Nitro's node-server preset in real deploys) rejects a TLA chunk, forcing the documented build-target-esnext workaround. Validation is now fully synchronous with identical boot semantics (same process.env read at module init, same per-key report, fail-loud before any importer's body runs, frozen env export) — synchronous init is the only shape that keeps "validated before first use", since user server modules read env.KEY at their own top level. Tradeoff made explicit: async validators are rejected for server keys at config/build time with the fix in the message (boot backstops with the same report when async-ness only surfaces on real values); client keys keep async support (baked at build time, where the plugin awaits). start-env suite: async-server-validator guard fixture + every server chunk must transform under esbuild target es2020 (rejects TLA at parse time — the exact downstream-bundler check). Patch changeset on the 3.0.0-next line.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: ryansolid

.changeset/no-tla-server-env.md

@@ -0,0 +1,27 @@
+---
+'@solidjs/vite-plugin': patch
+---
+
+`start.env`: the generated `virtual:env/server` module no longer contains
+top-level await, removing the esnext-target deploy requirement. Boot
+validation used to conditionally `await` each validator result (Standard
+Schema allows `validate()` to return a Promise), which put a TLA in the
+server env chunk whenever the schema had `server` keys — and any
+downstream bundler with a non-esnext target refuses a TLA chunk outright
+(Nitro's node-server preset is the one that bites in practice), forcing
+deployments to override the build target to `esnext`. Boot validation is
+now fully synchronous with identical semantics: same `process.env` read at
+module init, same per-key report, same fail-loud-at-boot before any
+importer's body runs, same frozen `env` export — and synchronous init is
+the only shape that can keep the "validated before first use" guarantee,
+since user server modules read `env.KEY` at their own top level (deferring
+the await to request entry cannot cover module-init consumers). The
+tradeoff is explicit: async validators (e.g. `z.string().refine(async
+...)`) are no longer supported for `server` keys — they are rejected at
+config/build time with the fix in the message (they could only ever have
+failed at deploy boot otherwise), and boot backstops with the same report
+for schemas whose async-ness only surfaces on real values. `client` keys
+keep async support: their values are baked at build time, where the plugin
+awaits. The start-env suite now asserts every built server chunk
+transforms under esbuild target es2020 (which rejects TLA at parse time —
+exactly the check a downstream bundler applies) so this cannot regress.

README.md

@@ -396,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

examples/start-env/env.async.ts

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+import * as v from 'valibot';
+
+// Guard fixture: a `server` key whose validator is async (zod async
+// refinement — Standard Schema lets validate() return a Promise). Server
+// env validates process.env synchronously at boot, because the generated
+// module must carry no top-level await (a TLA chunk forces esnext on
+// downstream bundle targets — Nitro's node-server preset rejects it), so
+// this schema must be rejected at config/build time with the
+// async-validator error naming the key. SESSION_SECRET is used on purpose:
+// .env provides a valid value, so the sync prefix of the schema passes and
+// zod actually goes async — exercising the Promise detection rather than a
+// short-circuiting sync failure.
+export default {
+  server: {
+    SESSION_SECRET: z
+      .string()
+      .min(32)
+      .refine(async () => true, { message: 'async refinement' }),
+  },
+  client: {
+    VITE_APP_NAME: v.pipe(v.string(), v.minLength(1)),
+  },
+};

examples/start-env/package.json

@@ -10,7 +10,8 @@
   },
   "devDependencies": {
     "vite": "^7.0.0",
-    "@solidjs/vite-plugin": "workspace:*"
+    "@solidjs/vite-plugin": "workspace:*",
+    "esbuild": "^0.25.0"
   },
   "dependencies": {
     "solid-js": "catalog:",

examples/start-env/test/run.mjs

@@ -12,13 +12,16 @@
 //     client-chunk leak scan; a missing SERVER var only warns at build
 //     time (runtime env — deferred to boot) while a missing CLIENT var
 //     (baked) fails the build; a non-VITE_ client key is a config-time
-//     error,
+//     error; an async SERVER validator is a config-time error (boot
+//     validation is synchronous — no top-level await in the server chunk),
 //   - prod (ssr mode): client chunks carry the client values and neither
 //     the secret, the server key names, nor any '~standard' validator
 //     machinery; dist/server bakes NO server values — it reads process.env
 //     at boot through the user's schema (validator is server-only), so the
 //     same artifact serves a rotated secret without a rebuild and fails
-//     boot with the per-key report when the runtime env is invalid;
+//     boot with the per-key report when the runtime env is invalid; every
+//     server chunk bundles at target es2020 (no top-level await — the
+//     Nitro node-server / non-esnext-target regression guard);
 //     preview folds .env into process.env (zero-config smoke test) and serves
 //     with the middleware headers live,
 //   - client mode: the same env layer on a static build — index.html shell,
@@ -371,6 +374,14 @@ async function guardsMode() {
   // is a leak the moment it exists — reject it before anything builds.
   out = await build({ ENV_SCHEMA: './env.serverprefix.ts' }).catch((e) => e.message);
   record('guards', 'prefix', 'VITE_-prefixed server key is a config-time error', /cannot keep it secret/.test(out) && /VITE_API_SECRET/.test(out), out.slice(0, 400));
+
+  // Async validators are rejected for `server` keys at config time: boot
+  // validation is synchronous (the generated server env module carries no
+  // top-level await so server bundles work on non-esnext targets), so a
+  // Promise-returning server validator could only ever fail at deploy
+  // boot — fail fast at build instead, with the fix in the message.
+  out = await build({ ENV_SCHEMA: './env.async.ts' }).catch((e) => e.message);
+  record('guards', 'sync-only', 'async server validator is a config-time error', /async validator/.test(out) && /SESSION_SECRET/.test(out), out.slice(0, 400));
 }
 
 async function prodMode() {
@@ -396,6 +407,27 @@ async function prodMode() {
   record('prod', 'server-bundle', 'server secret NOT baked into the server bundle', !serverJs.includes(SECRET));
   record('prod', 'server-bundle', 'server bundle validates process.env at boot (schema shipped server-side)', serverJs.includes('~standard') && serverJs.includes('validation failed at boot') && /process\.env/.test(serverJs));
 
+  // TLA regression guard: the env module's boot validation used to emit a
+  // top-level await (the conditional Standard Schema promise await), which
+  // made any downstream bundler with a non-esnext target — Nitro's
+  // node-server preset in practice — reject the whole server chunk unless
+  // deployments overrode the build target to esnext. esbuild at target
+  // es2020 refuses TLA at parse time (it can lower everything else, TLA it
+  // cannot), which is exactly the check a downstream bundler applies: every
+  // server chunk must pass it.
+  const esbuild = await import('esbuild');
+  let tlaFailure = '';
+  for (const [name, code] of Object.entries(readDistFiles(path.join(exampleDir, 'dist/server')))) {
+    if (!/\.m?js$/.test(name)) continue;
+    try {
+      await esbuild.transform(code, { format: 'esm', target: 'es2020' });
+    } catch (error) {
+      tlaFailure = `${name}: ${error.message}`;
+      break;
+    }
+  }
+  record('prod', 'server-bundle', 'no top-level await in any server chunk (bundles at target es2020)', !tlaFailure, tlaFailure.slice(0, 300));
+
   const preview = (env) => {
     const child = startProcess(
       'pnpm',

examples/start-env/vite.config.ts

@@ -16,7 +16,9 @@ import solidPlugin from '@solidjs/vite-plugin';
 // - ENV_SCHEMA points start.env at a fixture schema (explicit-path option):
 //   env.fail.ts requires a variable no .env provides (validation failure),
 //   env.badprefix.ts declares a client var without the VITE_ prefix
-//   (config-time prefix error).
+//   (config-time prefix error), env.async.ts puts an async validator on a
+//   server key (config-time error — boot validation is synchronous so the
+//   server chunk carries no top-level await).
 export default defineConfig({
   plugins: [
     solidPlugin({

pnpm-lock.yaml

@@ -180,6 +180,11 @@ export interface StartOptions {
    * only), so platform-injected vars work and secrets rotate without a
    * rebuild — no secret exists in any dist artifact. Build-time server
    * failures are a deferred-to-boot warning; dev failures stay hard.
+   * Boot validation is synchronous — the generated module carries no
+   * top-level await, so server bundles work on non-esnext targets
+   * (Nitro's node-server preset needs no `esnext` override) — which is
+   * why async validators are rejected for `server` keys at config time
+   * (`client` keys may stay async: they are awaited at build time).
    *
    * `true` requires the conventional file (error when missing); a string
    * is an explicit schema path; `false` disables even the probing.

src/ssr/index.ts

@@ -23,6 +23,11 @@
 // 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)
@@ -436,7 +441,30 @@ export function startEnv(option: boolean | string | undefined): Plugin[] {
     for (const side of ['server', 'client'] as const) {
       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 ?? [])
@@ -532,6 +560,16 @@ export function startEnv(option: boolean | string | undefined): Plugin[] {
   // 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: LoadedEnv) {
     const serverKeys = Object.keys(loaded.schema.server ?? {});
     const baked = `const __env = ${JSON.stringify(loaded.client)};`;
@@ -549,14 +587,18 @@ export function startEnv(option: boolean | string | undefined): Plugin[] {
       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.`,
+        `// 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)}) {`,
-        `  let __result = __schema.server[__key]['~standard'].validate(process.env[__key]);`,
-        `  if (__result instanceof Promise) __result = await __result;`,
-        `  if (__result.issues && __result.issues.length) {`,
+        `  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;`,