litestar-vite-plugin 0.14.0 → 0.15.0-alpha.2

package/dist/js/index.js

@@ -1,14 +1,24 @@
+import { exec } from "node:child_process";
+import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
 import colors from "picocolors";
 import { loadEnv } from "vite";
 import fullReload from "vite-plugin-full-reload";
+import { resolveInstallHint } from "./install-hint.js";
+import { checkBackendAvailability, loadLitestarMeta } from "./litestar-meta.js";
+const execAsync = promisify(exec);
 let exitHandlersBound = false;
 const refreshPaths = ["src/**", "resources/**", "assets/**"].filter((path2) => fs.existsSync(path2.replace(/\*\*$/, "")));
 function litestar(config) {
   const pluginConfig = resolvePluginConfig(config);
-  return [resolveLitestarPlugin(pluginConfig), ...resolveFullReloadConfig(pluginConfig)];
+  const plugins = [resolveLitestarPlugin(pluginConfig), ...resolveFullReloadConfig(pluginConfig)];
+  if (pluginConfig.types !== false && pluginConfig.types.enabled) {
+    plugins.push(resolveTypeGenerationPlugin(pluginConfig.types));
+  }
+  return plugins;
 }
 async function findIndexHtmlPath(server, pluginConfig) {
   if (!pluginConfig.autoDetectIndex) {
@@ -32,10 +42,23 @@ async function findIndexHtmlPath(server, pluginConfig) {
   }
   return null;
 }
+function normalizeAppUrl(appUrl, fallbackPort) {
+  if (!appUrl || appUrl === "__litestar_app_url_missing__") {
+    return { url: null, note: "APP_URL missing" };
+  }
+  try {
+    const url = new URL(appUrl);
+    const rebuilt = url.origin + (url.pathname === "/" ? "" : url.pathname) + (url.search ?? "") + (url.hash ?? "");
+    return { url: rebuilt };
+  } catch {
+    return { url: null, note: "APP_URL invalid" };
+  }
+}
 function resolveLitestarPlugin(pluginConfig) {
   let viteDevServerUrl;
   let resolvedConfig;
   let userConfig;
+  let litestarMeta = {};
   const defaultAliases = {
     "@": `/${pluginConfig.resourceDirectory.replace(/^\/+/, "").replace(/\/+$/, "")}/`
   };
@@ -46,11 +69,12 @@ function resolveLitestarPlugin(pluginConfig) {
       userConfig = config;
       const ssr = !!userConfig.build?.ssr;
       const env = loadEnv(mode, userConfig.envDir || process.cwd(), "");
-      const assetUrl = env.ASSET_URL || pluginConfig.assetUrl;
+      const assetUrl = normalizeAssetUrl(env.ASSET_URL || pluginConfig.assetUrl);
       const serverConfig = command === "serve" ? resolveDevelopmentEnvironmentServerConfig(pluginConfig.detectTls) ?? resolveEnvironmentServerConfig(env) : void 0;
+      const devBase = pluginConfig.assetUrl.startsWith("/") ? pluginConfig.assetUrl : pluginConfig.assetUrl.replace(/\/+$/, "");
       ensureCommandShouldRunInEnvironment(command, env);
       return {
-        base: userConfig.base ?? (command === "build" ? resolveBase(pluginConfig, assetUrl) : pluginConfig.assetUrl),
+        base: userConfig.base ?? (command === "build" ? resolveBase(pluginConfig, assetUrl) : devBase),
         publicDir: userConfig.publicDir ?? false,
         clearScreen: false,
         build: {
@@ -64,6 +88,27 @@ function resolveLitestarPlugin(pluginConfig) {
         },
         server: {
           origin: userConfig.server?.origin ?? "__litestar_vite_placeholder__",
+          // Auto-configure HMR to use a path that routes through Litestar proxy
+          // Note: Vite automatically prepends `base` to `hmr.path`, so we just use "vite-hmr"
+          // Result: base="/static/" + path="vite-hmr" = "/static/vite-hmr"
+          hmr: userConfig.server?.hmr === false ? false : {
+            path: "vite-hmr",
+            ...serverConfig?.hmr ?? {},
+            ...userConfig.server?.hmr === true ? {} : userConfig.server?.hmr
+          },
+          // Auto-configure proxy to forward API requests to Litestar backend
+          // This allows the app to work when accessing Vite directly (not through Litestar proxy)
+          // Only proxies /api and /schema routes - everything else is handled by Vite
+          proxy: userConfig.server?.proxy ?? (env.APP_URL ? {
+            "/api": {
+              target: env.APP_URL,
+              changeOrigin: true
+            },
+            "/schema": {
+              target: env.APP_URL,
+              changeOrigin: true
+            }
+          } : void 0),
           ...process.env.VITE_ALLOW_REMOTE ? {
             host: userConfig.server?.host ?? "0.0.0.0",
             port: userConfig.server?.port ?? (env.VITE_PORT ? Number.parseInt(env.VITE_PORT) : 5173),
@@ -71,10 +116,6 @@ function resolveLitestarPlugin(pluginConfig) {
           } : void 0,
           ...serverConfig ? {
             host: userConfig.server?.host ?? serverConfig.host,
-            hmr: userConfig.server?.hmr === false ? false : {
-              ...serverConfig.hmr,
-              ...userConfig.server?.hmr === true ? {} : userConfig.server?.hmr
-            },
             https: userConfig.server?.https ?? serverConfig.https
           } : void 0
         },
@@ -97,7 +138,7 @@ function resolveLitestarPlugin(pluginConfig) {
         // appType: 'spa', // Try adding this - might simplify things if appropriate
       };
     },
-    configResolved(config) {
+    async configResolved(config) {
       resolvedConfig = config;
       if (resolvedConfig.command === "serve" && resolvedConfig.base && !resolvedConfig.base.endsWith("/")) {
         resolvedConfig = {
@@ -105,6 +146,8 @@ function resolveLitestarPlugin(pluginConfig) {
           base: `${resolvedConfig.base}/`
         };
       }
+      const hint = pluginConfig.types !== false ? pluginConfig.types.routesPath : void 0;
+      litestarMeta = await loadLitestarMeta(resolvedConfig, hint);
     },
     transform(code, id) {
       if (resolvedConfig.command === "serve" && code.includes("__litestar_vite_placeholder__")) {
@@ -115,7 +158,13 @@ function resolveLitestarPlugin(pluginConfig) {
     },
     async configureServer(server) {
       const envDir = resolvedConfig.envDir || process.cwd();
-      const appUrl = loadEnv(resolvedConfig.mode, envDir, "APP_URL").APP_URL ?? "undefined";
+      const envWithApp = loadEnv(resolvedConfig.mode, envDir, "APP_URL");
+      const rawAppUrl = envWithApp.APP_URL ?? "__litestar_app_url_missing__";
+      const normalizedAppUrl = normalizeAppUrl(rawAppUrl, envWithApp.LITESTAR_PORT);
+      const appUrl = normalizedAppUrl.url ?? rawAppUrl;
+      if (pluginConfig.hotFile && !path.isAbsolute(pluginConfig.hotFile)) {
+        pluginConfig.hotFile = path.resolve(server.config.root, pluginConfig.hotFile);
+      }
       const initialIndexPath = await findIndexHtmlPath(server, pluginConfig);
       server.httpServer?.once("listening", () => {
         const address = server.httpServer?.address();
@@ -124,9 +173,11 @@ function resolveLitestarPlugin(pluginConfig) {
           viteDevServerUrl = userConfig.server?.origin ? userConfig.server.origin : resolveDevServerUrl(address, server.config, userConfig);
           fs.mkdirSync(path.dirname(pluginConfig.hotFile), { recursive: true });
           fs.writeFileSync(pluginConfig.hotFile, viteDevServerUrl);
-          setTimeout(() => {
+          setTimeout(async () => {
+            const version = litestarMeta.litestarVersion ?? process.env.LITESTAR_VERSION ?? "unknown";
+            const backendStatus = await checkBackendAvailability(appUrl);
             resolvedConfig.logger.info(`
-  ${colors.red(`${colors.bold("LITESTAR")} ${litestarVersion()}`)}  ${colors.dim("plugin")} ${colors.bold(`v${pluginVersion()}`)}`);
+  ${colors.red(`${colors.bold("LITESTAR")} ${version}`)}`);
             resolvedConfig.logger.info("");
             if (initialIndexPath) {
               resolvedConfig.logger.info(
@@ -136,8 +187,45 @@ function resolveLitestarPlugin(pluginConfig) {
               resolvedConfig.logger.info(`  ${colors.green("\u279C")}  ${colors.bold("Index Mode")}: Litestar (Plugin will serve placeholder for /index.html)`);
             }
             resolvedConfig.logger.info(`  ${colors.green("\u279C")}  ${colors.bold("Dev Server")}: ${colors.cyan(viteDevServerUrl)}`);
-            resolvedConfig.logger.info(`  ${colors.green("\u279C")}  ${colors.bold("App URL")}:    ${colors.cyan(appUrl.replace(/:(\d+)/, (_, port) => `:${colors.bold(port)}`))}`);
+            if (backendStatus.available) {
+              resolvedConfig.logger.info(
+                `  ${colors.green("\u279C")}  ${colors.bold("App URL")}:    ${colors.cyan(appUrl.replace(/:(\d+)/, (_, port) => `:${colors.bold(port)}`))} ${colors.green("\u2713")}`
+              );
+            } else {
+              resolvedConfig.logger.info(
+                `  ${colors.yellow("\u279C")}  ${colors.bold("App URL")}:    ${colors.cyan(appUrl.replace(/:(\d+)/, (_, port) => `:${colors.bold(port)}`))} ${colors.yellow("\u26A0")}`
+              );
+            }
             resolvedConfig.logger.info(`  ${colors.green("\u279C")}  ${colors.bold("Assets Base")}: ${colors.cyan(resolvedConfig.base)}`);
+            if (pluginConfig.types !== false && pluginConfig.types.enabled) {
+              const openapiExists = fs.existsSync(path.resolve(process.cwd(), pluginConfig.types.openapiPath));
+              const routesExists = fs.existsSync(path.resolve(process.cwd(), pluginConfig.types.routesPath));
+              if (openapiExists || routesExists) {
+                resolvedConfig.logger.info(`  ${colors.green("\u279C")}  ${colors.bold("Type Gen")}:   ${colors.green("enabled")} ${colors.dim(`\u2192 ${pluginConfig.types.output}`)}`);
+              } else {
+                resolvedConfig.logger.info(`  ${colors.yellow("\u279C")}  ${colors.bold("Type Gen")}:   ${colors.yellow("waiting")} ${colors.dim("(no schema files yet)")}`);
+              }
+            }
+            if (!backendStatus.available) {
+              resolvedConfig.logger.info("");
+              resolvedConfig.logger.info(`  ${colors.yellow("\u26A0")}  ${colors.bold("Backend Status")}`);
+              if (backendStatus.error === "APP_URL not configured" || normalizedAppUrl.note) {
+                resolvedConfig.logger.info(`     ${colors.dim("APP_URL environment variable is not set.")}`);
+                resolvedConfig.logger.info(`     ${colors.dim("Set APP_URL in your .env file or environment.")}`);
+                if (normalizedAppUrl.note === "APP_URL invalid") {
+                  resolvedConfig.logger.info(`     ${colors.dim(`Current APP_URL is invalid: ${rawAppUrl}`)}`);
+                }
+              } else {
+                resolvedConfig.logger.info(`     ${colors.dim(backendStatus.error ?? "Backend not available")}`);
+                resolvedConfig.logger.info("");
+                resolvedConfig.logger.info(`     ${colors.bold("To start your Litestar app:")}`);
+                resolvedConfig.logger.info(`     ${colors.cyan("litestar run")} ${colors.dim("or")} ${colors.cyan("uvicorn app:app --reload")}`);
+              }
+              resolvedConfig.logger.info("");
+              resolvedConfig.logger.info(`     ${colors.dim("The Vite dev server is running and will serve assets.")}`);
+              resolvedConfig.logger.info(`     ${colors.dim("Start your Litestar backend to view the full application.")}`);
+            }
+            resolvedConfig.logger.info("");
           }, 100);
         }
       });
@@ -153,53 +241,49 @@ function resolveLitestarPlugin(pluginConfig) {
         process.on("SIGHUP", () => process.exit());
         exitHandlersBound = true;
       }
-      return () => {
-        server.middlewares.use(async (req, res, next) => {
-          const indexPath = await findIndexHtmlPath(server, pluginConfig);
-          if (indexPath && (req.url === "/" || req.url === "/index.html")) {
-            const currentUrl = req.url;
-            try {
-              const htmlContent = await fs.promises.readFile(indexPath, "utf-8");
-              const transformedHtml = await server.transformIndexHtml(req.originalUrl ?? currentUrl, htmlContent, req.originalUrl);
-              res.statusCode = 200;
-              res.setHeader("Content-Type", "text/html");
-              res.end(transformedHtml);
-              return;
-            } catch (e) {
-              resolvedConfig.logger.error(`Error serving index.html from ${indexPath}: ${e instanceof Error ? e.message : e}`);
-              next(e);
-              return;
-            }
-          }
-          if (!indexPath && req.url === "/index.html") {
-            try {
-              const placeholderPath = path.join(dirname(), "dev-server-index.html");
-              const placeholderContent = await fs.promises.readFile(placeholderPath, "utf-8");
-              res.statusCode = 200;
-              res.setHeader("Content-Type", "text/html");
-              res.end(placeholderContent.replace(/{{ APP_URL }}/g, appUrl));
-            } catch (e) {
-              resolvedConfig.logger.error(`Error serving placeholder index.html: ${e instanceof Error ? e.message : e}`);
-              res.statusCode = 404;
-              res.end("Not Found (Error loading placeholder)");
-            }
+      server.middlewares.use(async (req, res, next) => {
+        const indexPath = await findIndexHtmlPath(server, pluginConfig);
+        if (indexPath && (req.url === "/" || req.url === "/index.html")) {
+          const currentUrl = req.url;
+          try {
+            const htmlContent = await fs.promises.readFile(indexPath, "utf-8");
+            const transformedHtml = await server.transformIndexHtml(req.originalUrl ?? currentUrl, htmlContent, req.originalUrl);
+            res.statusCode = 200;
+            res.setHeader("Content-Type", "text/html");
+            res.end(transformedHtml);
+            return;
+          } catch (e) {
+            resolvedConfig.logger.error(`Error serving index.html from ${indexPath}: ${e instanceof Error ? e.message : e}`);
+            next(e);
             return;
           }
-          next();
-        });
-      };
+        }
+        if (!indexPath && req.url === "/index.html") {
+          try {
+            const placeholderPath = path.join(dirname(), "dev-server-index.html");
+            const placeholderContent = await fs.promises.readFile(placeholderPath, "utf-8");
+            res.statusCode = 200;
+            res.setHeader("Content-Type", "text/html");
+            res.end(placeholderContent.replace(/{{ APP_URL }}/g, appUrl));
+          } catch (e) {
+            resolvedConfig.logger.error(`Error serving placeholder index.html: ${e instanceof Error ? e.message : e}`);
+            res.statusCode = 404;
+            res.end("Not Found (Error loading placeholder)");
+          }
+          return;
+        }
+        next();
+      });
     }
   };
 }
 function ensureCommandShouldRunInEnvironment(command, env) {
-  const validEnvironmentNames = ["dev", "development", "local", "docker"];
+  const allowedDevModes = ["dev", "development", "local", "docker"];
   if (command === "build" || env.LITESTAR_BYPASS_ENV_CHECK === "1") {
     return;
   }
-  if (typeof env.LITESTAR_MODE !== "undefined" && validEnvironmentNames.some((e) => e === env.LITESTAR_MODE)) {
-    throw Error(
-      "You should only run Vite dev server when Litestar is development mode. You should build your assets for production instead. To disable this ENV check you may set LITESTAR_BYPASS_ENV_CHECK=1"
-    );
+  if (typeof env.LITESTAR_MODE !== "undefined" && !allowedDevModes.includes(env.LITESTAR_MODE)) {
+    throw Error("Run the Vite dev server only in development. Set LITESTAR_MODE=dev/development/local/docker or set LITESTAR_BYPASS_ENV_CHECK=1 to skip this check.");
   }
   if (typeof env.CI !== "undefined") {
     throw Error(
@@ -207,9 +291,6 @@ function ensureCommandShouldRunInEnvironment(command, env) {
     );
   }
 }
-function litestarVersion() {
-  return "";
-}
 function pluginVersion() {
   try {
     return JSON.parse(fs.readFileSync(path.join(dirname(), "../package.json")).toString())?.version;
@@ -217,10 +298,26 @@ function pluginVersion() {
     return "";
   }
 }
+function loadPythonDefaults() {
+  const configPath = process.env.LITESTAR_VITE_CONFIG_PATH;
+  if (!configPath) {
+    return null;
+  }
+  if (!fs.existsSync(configPath)) {
+    return null;
+  }
+  try {
+    const data = JSON.parse(fs.readFileSync(configPath, "utf8"));
+    return data;
+  } catch {
+    return null;
+  }
+}
 function resolvePluginConfig(config) {
   if (typeof config === "undefined") {
     throw new Error("litestar-vite-plugin: missing configuration.");
   }
+  const pythonDefaults = loadPythonDefaults();
   const resolvedConfig = typeof config === "string" || Array.isArray(config) ? { input: config, ssr: config } : config;
   if (typeof resolvedConfig.input === "undefined") {
     throw new Error('litestar-vite-plugin: missing configuration for "input".');
@@ -243,18 +340,51 @@ function resolvePluginConfig(config) {
   if (resolvedConfig.refresh === true) {
     resolvedConfig.refresh = [{ paths: refreshPaths }];
   }
+  let typesConfig = false;
+  if (typeof resolvedConfig.types === "undefined" && pythonDefaults?.types) {
+    typesConfig = {
+      enabled: pythonDefaults.types.enabled,
+      output: pythonDefaults.types.output,
+      openapiPath: pythonDefaults.types.openapiPath,
+      routesPath: pythonDefaults.types.routesPath,
+      generateZod: pythonDefaults.types.generateZod,
+      generateSdk: pythonDefaults.types.generateSdk,
+      debounce: 300
+    };
+  } else if (resolvedConfig.types === true || typeof resolvedConfig.types === "undefined") {
+    typesConfig = {
+      enabled: true,
+      output: "src/generated/types",
+      openapiPath: "src/generated/openapi.json",
+      routesPath: "src/generated/routes.json",
+      generateZod: false,
+      generateSdk: false,
+      debounce: 300
+    };
+  } else if (typeof resolvedConfig.types === "object" && resolvedConfig.types !== null) {
+    typesConfig = {
+      enabled: resolvedConfig.types.enabled ?? true,
+      output: resolvedConfig.types.output ?? "src/generated/types",
+      openapiPath: resolvedConfig.types.openapiPath ?? "src/generated/openapi.json",
+      routesPath: resolvedConfig.types.routesPath ?? "src/generated/routes.json",
+      generateZod: resolvedConfig.types.generateZod ?? false,
+      generateSdk: resolvedConfig.types.generateSdk ?? false,
+      debounce: resolvedConfig.types.debounce ?? 300
+    };
+  }
   return {
     input: resolvedConfig.input,
-    assetUrl: resolvedConfig.assetUrl ?? "static",
-    resourceDirectory: resolvedConfig.resourceDirectory ?? "resources",
-    bundleDirectory: resolvedConfig.bundleDirectory ?? "public",
+    assetUrl: normalizeAssetUrl(resolvedConfig.assetUrl ?? pythonDefaults?.assetUrl ?? "/static/"),
+    resourceDirectory: resolvedConfig.resourceDirectory ?? pythonDefaults?.resourceDir ?? "resources",
+    bundleDirectory: resolvedConfig.bundleDirectory ?? pythonDefaults?.bundleDir ?? "public",
     ssr: resolvedConfig.ssr ?? resolvedConfig.input,
-    ssrOutputDirectory: resolvedConfig.ssrOutputDirectory ?? path.join(resolvedConfig.resourceDirectory ?? "resources", "bootstrap/ssr"),
+    ssrOutputDirectory: resolvedConfig.ssrOutputDirectory ?? pythonDefaults?.ssrOutDir ?? path.join(resolvedConfig.resourceDirectory ?? pythonDefaults?.resourceDir ?? "resources", "bootstrap/ssr"),
     refresh: resolvedConfig.refresh ?? false,
     hotFile: resolvedConfig.hotFile ?? path.join(resolvedConfig.bundleDirectory ?? "public", "hot"),
     detectTls: resolvedConfig.detectTls ?? false,
     autoDetectIndex: resolvedConfig.autoDetectIndex ?? true,
-    transformOnServe: resolvedConfig.transformOnServe ?? ((code) => code)
+    transformOnServe: resolvedConfig.transformOnServe ?? ((code) => code),
+    types: typesConfig
   };
 }
 function resolveBase(config, assetUrl) {
@@ -294,6 +424,248 @@ function resolveFullReloadConfig({ refresh: config }) {
     return plugin;
   });
 }
+function debounce(func, wait) {
+  let timeout = null;
+  return (...args) => {
+    if (timeout) {
+      clearTimeout(timeout);
+    }
+    timeout = setTimeout(() => func(...args), wait);
+  };
+}
+async function emitRouteTypes(routesPath, outputDir) {
+  const contents = await fs.promises.readFile(routesPath, "utf-8");
+  const json = JSON.parse(contents);
+  const outDir = path.resolve(process.cwd(), outputDir);
+  await fs.promises.mkdir(outDir, { recursive: true });
+  const outFile = path.join(outDir, "routes.ts");
+  const banner = `// AUTO-GENERATED by litestar-vite. Do not edit.
+/* eslint-disable */
+
+`;
+  const routesData = json.routes || json;
+  const routeNames = Object.keys(routesData);
+  const routeNameType = routeNames.length > 0 ? routeNames.map((n) => `"${n}"`).join(" | ") : "never";
+  const routeParamTypes = [];
+  for (const [name, data] of Object.entries(routesData)) {
+    const routeData = data;
+    if (routeData.parameters && routeData.parameters.length > 0) {
+      const params = routeData.parameters.map((p) => `${p}: string | number`).join("; ");
+      routeParamTypes.push(`  "${name}": { ${params} }`);
+    } else {
+      routeParamTypes.push(`  "${name}": Record<string, never>`);
+    }
+  }
+  const body = `/**
+ * AUTO-GENERATED by litestar-vite.
+ *
+ * Exports:
+ * - routesMeta: full route metadata
+ * - routes: name -> uri map
+ * - serverRoutes: alias of routes for clarity in apps
+ * - route(): type-safe URL generator
+ * - hasRoute(): type guard
+ * - csrf helpers re-exported from litestar-vite-plugin/helpers
+ *
+ * @see https://litestar-vite.litestar.dev/
+ */
+export const routesMeta = ${JSON.stringify(json, null, 2)} as const
+
+/**
+ * Route name to URI mapping.
+ */
+export const routes = ${JSON.stringify(Object.fromEntries(Object.entries(routesData).map(([name, data]) => [name, data.uri])), null, 2)} as const
+
+/**
+ * Alias for server-injected route map (more descriptive for consumers).
+ */
+export const serverRoutes = routes
+
+/**
+ * All available route names.
+ */
+export type RouteName = ${routeNameType}
+
+/**
+ * Parameter types for each route.
+ */
+export interface RouteParams {
+${routeParamTypes.join("\n")}
+}
+
+/**
+ * Generate a URL for a named route with type-safe parameters.
+ *
+ * @param name - The route name
+ * @param params - Route parameters (required if route has path parameters)
+ * @returns The generated URL
+ *
+ * @example
+ * \`\`\`ts
+ * import { route } from '@/generated/routes'
+ *
+ * // Route without parameters
+ * route('home')  // "/"
+ *
+ * // Route with parameters
+ * route('user:detail', { user_id: 123 })  // "/users/123"
+ * \`\`\`
+ */
+export function route<T extends RouteName>(
+  name: T,
+  ...args: RouteParams[T] extends Record<string, never> ? [] : [params: RouteParams[T]]
+): string {
+  let uri = routes[name] as string
+  const params = args[0] as Record<string, string | number> | undefined
+
+  if (params) {
+    for (const [key, value] of Object.entries(params)) {
+      // Handle both {param} and {param:type} syntax
+      uri = uri.replace(new RegExp(\`\\\\{\${key}(?::[^}]+)?\\\\}\`, "g"), String(value))
+    }
+  }
+
+  return uri
+}
+
+/**
+ * Check if a route name exists.
+ */
+export function hasRoute(name: string): name is RouteName {
+  return name in routes
+}
+
+declare global {
+  interface Window {
+    /**
+     * Fully-typed route metadata injected by Litestar.
+     */
+    __LITESTAR_ROUTES__?: typeof routesMeta
+    /**
+     * Simple route map (name -> uri) for legacy consumers.
+     */
+    routes?: typeof routes
+    serverRoutes?: typeof serverRoutes
+  }
+  // eslint-disable-next-line no-var
+  var routes: typeof routes | undefined
+  var serverRoutes: typeof serverRoutes | undefined
+}
+
+// Re-export helper functions from litestar-vite-plugin
+// These work with the routes defined above
+export { getCsrfToken, csrfHeaders, csrfFetch } from "litestar-vite-plugin/helpers"
+`;
+  await fs.promises.writeFile(outFile, `${banner}${body}`, "utf-8");
+}
+function resolveTypeGenerationPlugin(typesConfig) {
+  let lastTypesHash = null;
+  let lastRoutesHash = null;
+  let server = null;
+  let isGenerating = false;
+  let resolvedConfig = null;
+  async function runTypeGeneration() {
+    if (isGenerating) {
+      return false;
+    }
+    isGenerating = true;
+    const startTime = Date.now();
+    try {
+      const openapiPath = path.resolve(process.cwd(), typesConfig.openapiPath);
+      const routesPath = path.resolve(process.cwd(), typesConfig.routesPath);
+      let generated = false;
+      if (fs.existsSync(openapiPath)) {
+        if (resolvedConfig) {
+          resolvedConfig.logger.info(`${colors.cyan("litestar-vite")} ${colors.dim("generating TypeScript types...")}`);
+        }
+        const args = ["@hey-api/openapi-ts", "-i", typesConfig.openapiPath, "-o", typesConfig.output];
+        if (typesConfig.generateZod) {
+          args.push("--plugins", "@hey-api/schemas", "@hey-api/types");
+        }
+        if (typesConfig.generateSdk) {
+          args.push("--client", "fetch");
+        }
+        await execAsync(`npx ${args.join(" ")}`, {
+          cwd: process.cwd()
+        });
+        generated = true;
+      } else if (resolvedConfig) {
+        resolvedConfig.logger.warn(`${colors.cyan("litestar-vite")} ${colors.yellow("OpenAPI schema not found:")} ${typesConfig.openapiPath}`);
+      }
+      if (fs.existsSync(routesPath)) {
+        await emitRouteTypes(routesPath, typesConfig.output);
+        generated = true;
+      }
+      if (generated && resolvedConfig) {
+        const duration = Date.now() - startTime;
+        resolvedConfig.logger.info(`${colors.cyan("litestar-vite")} ${colors.green("TypeScript artifacts updated")} ${colors.dim(`in ${duration}ms`)}`);
+      }
+      if (generated && server) {
+        server.ws.send({
+          type: "custom",
+          event: "litestar:types-updated",
+          data: {
+            output: typesConfig.output,
+            timestamp: Date.now()
+          }
+        });
+      }
+      return true;
+    } catch (error) {
+      if (resolvedConfig) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message.includes("not found") || message.includes("ENOENT")) {
+          resolvedConfig.logger.warn(`${colors.cyan("litestar-vite")} ${colors.yellow("@hey-api/openapi-ts not installed")} - run: ${resolveInstallHint()}`);
+        } else {
+          resolvedConfig.logger.error(`${colors.cyan("litestar-vite")} ${colors.red("type generation failed:")} ${message}`);
+        }
+      }
+      return false;
+    } finally {
+      isGenerating = false;
+    }
+  }
+  const debouncedRunTypeGeneration = debounce(runTypeGeneration, typesConfig.debounce);
+  return {
+    name: "litestar-vite-types",
+    enforce: "pre",
+    configResolved(config) {
+      resolvedConfig = config;
+    },
+    configureServer(devServer) {
+      server = devServer;
+      if (typesConfig.enabled) {
+        resolvedConfig?.logger.info(`${colors.cyan("litestar-vite")} ${colors.dim("watching for schema changes:")} ${colors.yellow(typesConfig.openapiPath)}`);
+      }
+    },
+    async handleHotUpdate({ file }) {
+      if (!typesConfig.enabled) {
+        return;
+      }
+      const relativePath = path.relative(process.cwd(), file);
+      const openapiPath = typesConfig.openapiPath.replace(/^\.\//, "");
+      const routesPath = typesConfig.routesPath.replace(/^\.\//, "");
+      if (relativePath === openapiPath || relativePath === routesPath || file.endsWith(openapiPath) || file.endsWith(routesPath)) {
+        if (resolvedConfig) {
+          resolvedConfig.logger.info(`${colors.cyan("litestar-vite")} ${colors.dim("schema changed:")} ${colors.yellow(relativePath)}`);
+        }
+        const newHash = await hashFile(file);
+        if (relativePath === openapiPath) {
+          if (lastTypesHash === newHash) return;
+          lastTypesHash = newHash;
+        } else {
+          if (lastRoutesHash === newHash) return;
+          lastRoutesHash = newHash;
+        }
+        debouncedRunTypeGeneration();
+      }
+    }
+  };
+}
+async function hashFile(filePath) {
+  const content = await fs.promises.readFile(filePath);
+  return createHash("sha1").update(content).digest("hex");
+}
 function resolveDevServerUrl(address, config, userConfig) {
   const configHmrProtocol = typeof config.server.hmr === "object" ? config.server.hmr.protocol : null;
   const clientProtocol = configHmrProtocol ? configHmrProtocol === "wss" ? "https" : "http" : null;
@@ -303,7 +675,10 @@ function resolveDevServerUrl(address, config, userConfig) {
   const configHost = typeof config.server.host === "string" ? config.server.host : null;
   const remoteHost = process.env.VITE_ALLOW_REMOTE && !userConfig.server?.host ? "localhost" : null;
   const serverAddress = isIpv6(address) ? `[${address.address}]` : address.address;
-  const host = configHmrHost ?? remoteHost ?? configHost ?? serverAddress;
+  let host = configHmrHost ?? remoteHost ?? configHost ?? serverAddress;
+  if (host === "0.0.0.0") {
+    host = "127.0.0.1";
+  }
   const configHmrClientPort = typeof config.server.hmr === "object" ? config.server.hmr.clientPort : null;
   const port = configHmrClientPort ?? address.port;
   return `${protocol}://${host}:${port}`;
@@ -403,6 +778,19 @@ function dirname() {
     return path.resolve(process.cwd(), "src/js/src");
   }
 }
+function normalizeAssetUrl(url) {
+  const trimmed = url.trim();
+  if (trimmed === "") {
+    return "static";
+  }
+  const isExternal = trimmed.startsWith("http://") || trimmed.startsWith("https://");
+  if (isExternal) {
+    return trimmed.replace(/\/+$/, "");
+  }
+  const withLeading = trimmed.startsWith("/") ? `/${trimmed.replace(/^\/+/, "")}` : trimmed;
+  const withTrailing = withLeading.endsWith("/") ? withLeading : `${withLeading}/`;
+  return withTrailing;
+}
 export {
   litestar as default,
   refreshPaths