Simplify runtime binding migration

Author: infomiho

examples/kitchen-sink/e2e-tests/tests/prerender.spec.ts

@@ -9,14 +9,18 @@ test.describe("prerender", () => {
 
     await page.goto("/prerender");
 
-    await expect(page.getByRole("heading", { name: "Miho" })).toBeVisible();
+    await expect(
+      page.getByRole("heading", { name: "Kitchen Sink App" }),
+    ).toBeVisible();
     await expect(page.getByTestId("render-location")).toHaveText("server");
   });
 
   test("prerender page hydrates on the client", async ({ page }) => {
     await page.goto("/prerender");
 
-    await expect(page.getByRole("heading", { name: "Miho" })).toBeVisible();
+    await expect(
+      page.getByRole("heading", { name: "Kitchen Sink App" }),
+    ).toBeVisible();
     await expect(page.getByTestId("render-location")).toHaveText("client");
   });
 

examples/kitchen-sink/package-lock.json

@@ -1,12 +1,12 @@
 {{={= =}=}}
 import * as z from "zod"
 import { FromRegister } from "../../types/register";
-import { getClientEnvValidationSchema } from "./runtimeBindings.js"
+import { clientEnvValidationSchema } from "virtual:wasp/client-env-schema"
 
 export type RegisteredClientEnvValidationSchema = FromRegister<"clientEnvValidationSchema", z.ZodObject<{}>>;
 type UserClientEnvSchema = RegisteredClientEnvValidationSchema;
 
-const userClientEnvSchema = (getClientEnvValidationSchema() ?? z.object({})) as UserClientEnvSchema;
+const userClientEnvSchema = (clientEnvValidationSchema ?? z.object({})) as UserClientEnvSchema;
 
 const serverUrlSchema =
   z.string({

waspc/data/Generator/templates/sdk/wasp/client/env/runtimeBindings.ts

@@ -20,53 +20,69 @@ export function validateEnv(): Plugin {
     },
     // We validate just before any artifacts are built.
     async buildStart() {
-      await validateClientEnv(resolvedConfig);
-    },
-  };
-}
+      // We need to import the client env schema validation module
+      // through a Vite server, because both the user and the Wasp schema
+      // modules may depend on bundler features.
+      // Because of that we spin up a temporary Vite server.
+      //
+      // Alternatively, for `serve`, we could use the Vite server provided
+      // through the `configureServer` hook, but that would complicate
+      // the solution for negligible performance benefits.
+      const tempServer = await createViteServer({
+        root: resolvedConfig.root,
+        mode: resolvedConfig.mode,
+        // To ensure we pick up all user-defined plugins (resolution matches the main build)
+        // while avoiding recursion. This includes the `wasp` plugin.
+        configFile: false,
+        plugins: resolvedConfig.plugins
+          .filter((plugin) => plugin.name !== PLUGIN_NAME)
 
-export async function validateClientEnv(resolvedConfig: ResolvedConfig): Promise<void> {
-  // We need to import the client env schema validation module through a Vite
-  // server because both the user and Wasp schema modules may use bundler features.
-  const tempServer = await createViteServer({
-    root: resolvedConfig.root,
-    mode: resolvedConfig.mode,
-    // Reuse user-defined resolution and transforms while avoiding validation recursion.
-    configFile: false,
-    plugins: resolvedConfig.plugins
-      .filter((plugin) => plugin.name !== PLUGIN_NAME)
+          // Ignore `vite:`-prefixed plugins since Vite will recreate them for
+          // the temporary server anyway.
+          .filter((plugin) => !plugin.name.startsWith("vite:"))
 
-      // Ignore `vite:`-prefixed plugins since Vite recreates them for the temporary server.
-      .filter((plugin) => !plugin.name.startsWith("vite:"))
+          // Vite's `configureServer`/`configurePreviewServer` hooks let plugins
+          // wire long-lived behavior into a dev or preview server: middleware,
+          // websocket handlers, file watchers, and similar background tasks.
+          //
+          // Plugins are supposed to clean these up by returning a teardown
+          // function from the hook, but some forget to, so resources they
+          // allocate end up outliving the server. This forces the original
+          // Vite process to be alive indefinitely.
+          //
+          // We don't need either hook to validate the client env schema.
+          // We only need module resolution and transforms.
+          .map((plugin) => ({
+            ...plugin,
+            configureServer: undefined,
+            configurePreviewServer: undefined,
+          })),
 
-      // Avoid starting middleware, watchers, and other long-lived plugin behavior.
-      .map((plugin) => ({
-        ...plugin,
-        configureServer: undefined,
-        configurePreviewServer: undefined,
-      })),
+        // Minimize side effects from spinning up a temporary dev server.
+        appType: 'custom',      // avoid HTML handling
+        server: {
+          middlewareMode: true, // do not start an actual HTTP server
+          watch: null,
+          hmr: false
+        },
+        logLevel: "silent",
+        optimizeDeps: { noDiscovery: true, include: [] },
+        clearScreen: false,
+      });
 
-    // Minimize side effects from spinning up a temporary dev server.
-    appType: 'custom',
-    server: {
-      middlewareMode: true,
-      watch: null,
-      hmr: false
+      try {
+        // Vite's `ssr` means bundled for "backend JS runtime", like Node.
+        // This environment is always runnable in vite dev server.
+        if (!isRunnableDevEnvironment(tempServer.environments.ssr)) {
+          throw new Error(`Expected ssr to be a runnable dev environment`)
+        }
+        // The imported module runs env schema validation as an import
+        // side-effect and throws on failure.
+        const moduleAbsPath = path.resolve(resolvedConfig.root, CLIENT_ENV_SCHEMA_VALIDATION_MODULE);
+        await tempServer.environments.ssr.runner.import(moduleAbsPath);
+      } finally {
+        await tempServer.close();
+      }
     },
-    logLevel: "silent",
-    optimizeDeps: { noDiscovery: true, include: [] },
-    clearScreen: false,
-  });
-
-  try {
-    // Vite's `ssr` means bundled for a backend JS runtime such as Node.
-    if (!isRunnableDevEnvironment(tempServer.environments.ssr)) {
-      throw new Error(`Expected ssr to be a runnable dev environment`)
-    }
-    // Importing this module validates the client environment as a side effect.
-    const moduleAbsPath = path.resolve(resolvedConfig.root, CLIENT_ENV_SCHEMA_VALIDATION_MODULE);
-    await tempServer.environments.ssr.runner.import(moduleAbsPath);
-  } finally {
-    await tempServer.close();
-  }
+  };
 }

waspc/data/Generator/templates/sdk/wasp/client/env/schema.ts

@@ -1,107 +1,33 @@
 {{={= =}=}}
-import { type EnvironmentModuleNode, type Plugin, type ViteDevServer } from "vite";
+import { type Plugin } from "vite";
 import {
-  clientRuntimeBindingsFilePath,
   getClientEntryTsxContent,
-  getClientRuntimeBindingsTsContent,
+  getClientEnvSchemaTsContent,
   getRoutesTsxContent,
   getSsrEntryTsxContent,
 } from "../virtual-files/index.js";
 import { makeVirtualFilesResolver, type VirtualFiles } from "../virtual-files/resolver.js";
-import { validateClientEnv } from "./validateEnv.js";
 
 const resolveVirtualFiles = makeVirtualFilesResolver([
   { id: "{= clientEntryPointPath =}", load: getClientEntryTsxContent },
-  { id: "{= clientRuntimeBindingsEntryPointPath =}", load: getClientRuntimeBindingsTsContent },
+  { id: "{= clientEnvSchemaEntryPointPath =}", load: getClientEnvSchemaTsContent },
   { id: "{= routesEntryPointPath =}", load: getRoutesTsxContent },
   { id: "{= ssrEntryPointPath =}", load: getSsrEntryTsxContent },
 ]);
 
 export function virtualWaspModules(): Plugin {
   let virtualFiles!: VirtualFiles;
-  let devServer: ViteDevServer | undefined;
-  let restartTimer: ReturnType<typeof setTimeout> | undefined;
-  let lastUpdateKey: string | undefined;
-  let lastUpdatePromise: Promise<void> | undefined;
 
   return {
     name: "wasp:virtual-wasp-modules",
     enforce: "pre",
     configResolved(config) {
       virtualFiles = resolveVirtualFiles(config.root);
     },
-    configureServer(server) {
-      devServer = server;
-      server.watcher.add(clientRuntimeBindingsFilePath);
-    },
     resolveId: (id) => virtualFiles.ids.get(id),
     load(id) {
       const loader = virtualFiles.loaders.get(id);
       return loader?.();
     },
-    async hotUpdate({ file, modules, timestamp }) {
-      if (!devServer || !shouldRestartClient(file, modules, virtualFiles)) {
-        return;
-      }
-
-      const updateKey = `${timestamp}:${file}`;
-      if (lastUpdateKey !== updateKey) {
-        lastUpdateKey = updateKey;
-        lastUpdatePromise = validateClientEnv(devServer.config).then(() => {
-          scheduleRestart();
-        });
-      }
-
-      await lastUpdatePromise;
-      return [];
-    },
   };
-
-  function scheduleRestart(): void {
-    // Restart after Vite finishes the current HMR transaction. Restarting from
-    // inside this hook replaces the environments that Vite is still iterating.
-    restartTimer ??= setTimeout(() => {
-      void devServer
-        ?.restart()
-        .catch((error) => {
-          devServer?.config.logger.error(error);
-        })
-        .finally(() => {
-          restartTimer = undefined;
-        });
-    });
-  }
-}
-
-function shouldRestartClient(
-  changedFile: string,
-  changedModules: EnvironmentModuleNode[],
-  virtualFiles: VirtualFiles,
-): boolean {
-  if (changedFile === clientRuntimeBindingsFilePath) {
-    return true;
-  }
-
-  const bindingsModuleId = virtualFiles.ids.get("{= clientRuntimeBindingsEntryPointPath =}");
-  return bindingsModuleId !== undefined && changedModules.some(
-    (module) => hasImporter(module, bindingsModuleId, new Set()),
-  );
-}
-
-function hasImporter(
-  module: EnvironmentModuleNode,
-  importerId: string,
-  visited: Set<EnvironmentModuleNode>,
-): boolean {
-  if (module.id === importerId) {
-    return true;
-  }
-  if (visited.has(module)) {
-    return false;
-  }
-
-  visited.add(module);
-  return [...module.importers].some((importer) =>
-    hasImporter(importer, importerId, visited),
-  );
 }

waspc/data/Generator/templates/sdk/wasp/client/runtime.ts

@@ -1,6 +1,4 @@
 {{={= =}=}}
-import "virtual:wasp/client-runtime-bindings";
-
 import { startTransition } from "react";
 import { hydrateRoot } from "react-dom/client";
 import { createBrowserRouter } from "react-router";

waspc/data/Generator/templates/sdk/wasp/client/vite/plugins/validateEnv.ts

@@ -0,0 +1,6 @@
+{{={= =}=}}
+{=# clientEnvValidationSchema.isDefined =}
+{=& clientEnvValidationSchema.importStatement =}
+{=/ clientEnvValidationSchema.isDefined =}
+
+export const clientEnvValidationSchema = {=# clientEnvValidationSchema.isDefined =}{= clientEnvValidationSchema.importIdentifier =}{=/ clientEnvValidationSchema.isDefined =}{=^ clientEnvValidationSchema.isDefined =}undefined{=/ clientEnvValidationSchema.isDefined =};