litestar-vite-plugin 0.15.0-alpha.3 → 0.15.0-alpha.5

package/dist/js/index.js

@@ -12,12 +12,13 @@ import { checkBackendAvailability, loadLitestarMeta } from "./litestar-meta.js";
 import { debounce } from "./shared/debounce.js";
 const execAsync = promisify(exec);
 let exitHandlersBound = false;
+let warnedMissingRuntimeConfig = false;
 const refreshPaths = ["src/**", "resources/**", "assets/**"].filter((path2) => fs.existsSync(path2.replace(/\*\*$/, "")));
 function litestar(config) {
   const pluginConfig = resolvePluginConfig(config);
   const plugins = [resolveLitestarPlugin(pluginConfig), ...resolveFullReloadConfig(pluginConfig)];
   if (pluginConfig.types !== false && pluginConfig.types.enabled) {
-    plugins.push(resolveTypeGenerationPlugin(pluginConfig.types, pluginConfig.executor));
+    plugins.push(resolveTypeGenerationPlugin(pluginConfig.types, pluginConfig.executor, pluginConfig.hasPythonConfig));
   }
   return plugins;
 }
@@ -30,8 +31,8 @@ async function findIndexHtmlPath(server, pluginConfig) {
     path.join(root, "index.html"),
     path.join(root, pluginConfig.resourceDirectory.replace(/^\//, ""), "index.html"),
     // Ensure resourceDirectory path is relative to root
-    path.join(root, "public", "index.html")
-    // Check public even if publicDir is false, might exist
+    path.join(root, pluginConfig.publicDir.replace(/^\//, ""), "index.html"),
+    path.join(root, pluginConfig.bundleDirectory.replace(/^\//, ""), "index.html")
   ];
   for (const indexPath of possiblePaths) {
     try {
@@ -42,7 +43,7 @@ async function findIndexHtmlPath(server, pluginConfig) {
   }
   return null;
 }
-function normalizeAppUrl(appUrl, fallbackPort) {
+function normalizeAppUrl(appUrl, _fallbackPort) {
   if (!appUrl || appUrl === "__litestar_app_url_missing__") {
     return { url: null, note: "APP_URL missing" };
   }
@@ -59,6 +60,7 @@ function resolveLitestarPlugin(pluginConfig) {
   let resolvedConfig;
   let userConfig;
   let litestarMeta = {};
+  let shuttingDown = false;
   const pythonDefaults = loadPythonDefaults();
   const proxyMode = pythonDefaults?.proxyMode ?? "vite_proxy";
   const defaultAliases = {
@@ -73,11 +75,39 @@ function resolveLitestarPlugin(pluginConfig) {
       const env = loadEnv(mode, userConfig.envDir || process.cwd(), "");
       const assetUrl = normalizeAssetUrl(env.ASSET_URL || pluginConfig.assetUrl);
       const serverConfig = command === "serve" ? resolveDevelopmentEnvironmentServerConfig(pluginConfig.detectTls) ?? resolveEnvironmentServerConfig(env) : void 0;
+      const withProxyErrorSilencer = (proxyConfig) => {
+        if (!proxyConfig) return void 0;
+        return Object.fromEntries(
+          Object.entries(proxyConfig).map(([key, value]) => {
+            if (typeof value !== "object" || value === null) {
+              return [key, value];
+            }
+            const existingConfigure = value.configure;
+            return [
+              key,
+              {
+                ...value,
+                configure(proxy, opts) {
+                  proxy.on("error", (err) => {
+                    const msg = String(err?.message ?? "");
+                    if (shuttingDown || msg.includes("ECONNREFUSED") || msg.includes("ECONNRESET") || msg.includes("socket hang up")) {
+                      return;
+                    }
+                  });
+                  if (typeof existingConfigure === "function") {
+                    existingConfigure(proxy, opts);
+                  }
+                }
+              }
+            ];
+          })
+        );
+      };
       const devBase = pluginConfig.assetUrl.startsWith("/") ? pluginConfig.assetUrl : pluginConfig.assetUrl.replace(/\/+$/, "");
-      ensureCommandShouldRunInEnvironment(command, env);
+      ensureCommandShouldRunInEnvironment(command, env, mode);
       return {
         base: userConfig.base ?? (command === "build" ? resolveBase(pluginConfig, assetUrl) : devBase),
-        publicDir: userConfig.publicDir ?? false,
+        publicDir: userConfig.publicDir ?? pluginConfig.publicDir ?? false,
         clearScreen: false,
         build: {
           manifest: userConfig.build?.manifest ?? (ssr ? false : "manifest.json"),
@@ -101,16 +131,18 @@ function resolveLitestarPlugin(pluginConfig) {
           // 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),
+          proxy: withProxyErrorSilencer(
+            userConfig.server?.proxy ?? (env.APP_URL ? {
+              "/api": {
+                target: env.APP_URL,
+                changeOrigin: true
+              },
+              "/schema": {
+                target: env.APP_URL,
+                changeOrigin: true
+              }
+            } : void 0)
+          ),
           // Always respect VITE_PORT when set by Python (regardless of VITE_ALLOW_REMOTE)
           ...process.env.VITE_PORT ? {
             port: userConfig.server?.port ?? Number.parseInt(process.env.VITE_PORT),
@@ -157,10 +189,23 @@ function resolveLitestarPlugin(pluginConfig) {
           base: `${resolvedConfig.base}/`
         };
       }
+      if (resolvedConfig.command === "serve" && !pluginConfig.hasPythonConfig && !warnedMissingRuntimeConfig) {
+        warnedMissingRuntimeConfig = true;
+        if (typeof resolvedConfig.logger?.warn === "function") {
+          resolvedConfig.logger.warn(formatMissingConfigWarning());
+        }
+      }
+      const resourceDir = path.resolve(resolvedConfig.root, pluginConfig.resourceDirectory);
+      if (!fs.existsSync(resourceDir) && typeof resolvedConfig.logger?.warn === "function") {
+        resolvedConfig.logger.warn(
+          `${colors.cyan("litestar-vite")} ${colors.yellow("Resource directory not found:")} ${resourceDir}
+  Expected directory: ${colors.dim(pluginConfig.resourceDirectory)}`
+        );
+      }
       const hint = pluginConfig.types !== false ? pluginConfig.types.routesPath : void 0;
       litestarMeta = await loadLitestarMeta(resolvedConfig, hint);
     },
-    transform(code, id) {
+    transform(code, _id) {
       if (resolvedConfig.command === "serve" && code.includes("__litestar_vite_placeholder__")) {
         const transformedCode = code.replace(/__litestar_vite_placeholder__/g, viteDevServerUrl);
         return pluginConfig.transformOnServe(transformedCode, viteDevServerUrl);
@@ -249,9 +294,18 @@ function resolveLitestarPlugin(pluginConfig) {
           }
         };
         process.on("exit", clean);
-        process.on("SIGINT", () => process.exit());
-        process.on("SIGTERM", () => process.exit());
-        process.on("SIGHUP", () => process.exit());
+        process.on("SIGINT", () => {
+          shuttingDown = true;
+          process.exit();
+        });
+        process.on("SIGTERM", () => {
+          shuttingDown = true;
+          process.exit();
+        });
+        process.on("SIGHUP", () => {
+          shuttingDown = true;
+          process.exit();
+        });
         exitHandlersBound = true;
       }
       server.middlewares.use(async (req, res, next) => {
@@ -290,11 +344,14 @@ function resolveLitestarPlugin(pluginConfig) {
     }
   };
 }
-function ensureCommandShouldRunInEnvironment(command, env) {
+function ensureCommandShouldRunInEnvironment(command, env, mode) {
   const allowedDevModes = ["dev", "development", "local", "docker"];
   if (command === "build" || env.LITESTAR_BYPASS_ENV_CHECK === "1") {
     return;
   }
+  if (mode === "test" || env.VITEST || env.VITE_TEST || env.NODE_ENV === "test") {
+    return;
+  }
   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.");
   }
@@ -304,7 +361,7 @@ function ensureCommandShouldRunInEnvironment(command, env) {
     );
   }
 }
-function pluginVersion() {
+function _pluginVersion() {
   try {
     return JSON.parse(fs.readFileSync(path.join(dirname(), "../package.json")).toString())?.version;
   } catch {
@@ -312,11 +369,19 @@ function pluginVersion() {
   }
 }
 function loadPythonDefaults() {
-  const configPath = process.env.LITESTAR_VITE_CONFIG_PATH;
+  const isTestEnv = Boolean(process.env.VITEST || process.env.VITE_TEST || process.env.NODE_ENV === "test");
+  let configPath = process.env.LITESTAR_VITE_CONFIG_PATH;
   if (!configPath) {
-    return null;
+    const defaultPath = path.join(process.cwd(), ".litestar.json");
+    if (fs.existsSync(defaultPath)) {
+      configPath = defaultPath;
+    } else {
+      warnMissingRuntimeConfig("env", isTestEnv);
+      return null;
+    }
   }
   if (!fs.existsSync(configPath)) {
+    warnMissingRuntimeConfig("file", isTestEnv);
     return null;
   }
   try {
@@ -326,6 +391,48 @@ function loadPythonDefaults() {
     return null;
   }
 }
+function formatMissingConfigWarning() {
+  const y = colors.yellow;
+  const c = colors.cyan;
+  const d = colors.dim;
+  const b = colors.bold;
+  const lines = [
+    "",
+    y("\u256D\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256E"),
+    `${y("\u2502")}                                                                 ${y("\u2502")}`,
+    `${y("\u2502")}  ${y("\u26A0")}  ${b("Litestar backend configuration not found")}                   ${y("\u2502")}`,
+    `${y("\u2502")}                                                                 ${y("\u2502")}`,
+    `${y("\u2502")}  The plugin couldn't find ${c(".litestar.json")} which is normally     ${y("\u2502")}`,
+    `${y("\u2502")}  created when the Litestar backend starts.                     ${y("\u2502")}`,
+    `${y("\u2502")}                                                                 ${y("\u2502")}`,
+    `${y("\u2502")}  ${b("Quick fix")} - run one of these commands first:                  ${y("\u2502")}`,
+    `${y("\u2502")}                                                                 ${y("\u2502")}`,
+    `${y("\u2502")}    ${c("$ litestar run")}              ${d("# Start backend only")}            ${y("\u2502")}`,
+    `${y("\u2502")}    ${c("$ litestar assets serve")}     ${d("# Start backend + Vite together")} ${y("\u2502")}`,
+    `${y("\u2502")}                                                                 ${y("\u2502")}`,
+    `${y("\u2502")}  Or manually configure the plugin in ${c("vite.config.ts")}:           ${y("\u2502")}`,
+    `${y("\u2502")}                                                                 ${y("\u2502")}`,
+    `${y("\u2502")}    ${d("litestar({")}                                                  ${y("\u2502")}`,
+    `${y("\u2502")}    ${d('  input: ["src/main.tsx"],')}                                  ${y("\u2502")}`,
+    `${y("\u2502")}    ${d('  assetUrl: "/static/",')}                                     ${y("\u2502")}`,
+    `${y("\u2502")}    ${d('  bundleDirectory: "public",')}                                ${y("\u2502")}`,
+    `${y("\u2502")}    ${d("  types: false,")}                                             ${y("\u2502")}`,
+    `${y("\u2502")}    ${d("})")}                                                          ${y("\u2502")}`,
+    `${y("\u2502")}                                                                 ${y("\u2502")}`,
+    `${y("\u2502")}  Docs: ${c("https://docs.litestar.dev/vite/getting-started")}          ${y("\u2502")}`,
+    `${y("\u2502")}                                                                 ${y("\u2502")}`,
+    y("\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256F"),
+    "",
+    d("Continuing with defaults... some features may not work."),
+    ""
+  ];
+  return lines.join("\n");
+}
+function warnMissingRuntimeConfig(_reason, suppress) {
+  if (warnedMissingRuntimeConfig || suppress) return;
+  warnedMissingRuntimeConfig = true;
+  console.warn(formatMissingConfigWarning());
+}
 function resolvePluginConfig(config) {
   if (typeof config === "undefined") {
     throw new Error("litestar-vite-plugin: missing configuration.");
@@ -347,6 +454,12 @@ function resolvePluginConfig(config) {
       throw new Error("litestar-vite-plugin: bundleDirectory must be a subdirectory. E.g. 'public'.");
     }
   }
+  if (typeof resolvedConfig.publicDir === "string") {
+    resolvedConfig.publicDir = resolvedConfig.publicDir.trim().replace(/^\/+/, "").replace(/\/+$/, "");
+    if (resolvedConfig.publicDir === "") {
+      throw new Error("litestar-vite-plugin: publicDir must be a subdirectory. E.g. 'public'.");
+    }
+  }
   if (typeof resolvedConfig.ssrOutputDirectory === "string") {
     resolvedConfig.ssrOutputDirectory = resolvedConfig.ssrOutputDirectory.trim().replace(/^\/+/, "").replace(/\/+$/, "");
   }
@@ -354,17 +467,8 @@ function resolvePluginConfig(config) {
     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") {
+  if (resolvedConfig.types === false) {
+  } else if (resolvedConfig.types === true) {
     typesConfig = {
       enabled: true,
       output: "src/generated/types",
@@ -374,9 +478,21 @@ function resolvePluginConfig(config) {
       generateSdk: false,
       debounce: 300
     };
+  } else if (resolvedConfig.types === "auto" || typeof resolvedConfig.types === "undefined") {
+    if (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 (typeof resolvedConfig.types === "object" && resolvedConfig.types !== null) {
-    const userProvidedOpenapi = Object.prototype.hasOwnProperty.call(resolvedConfig.types, "openapiPath");
-    const userProvidedRoutes = Object.prototype.hasOwnProperty.call(resolvedConfig.types, "routesPath");
+    const userProvidedOpenapi = Object.hasOwn(resolvedConfig.types, "openapiPath");
+    const userProvidedRoutes = Object.hasOwn(resolvedConfig.types, "routesPath");
     typesConfig = {
       enabled: resolvedConfig.types.enabled ?? true,
       output: resolvedConfig.types.output ?? "src/generated/types",
@@ -398,6 +514,7 @@ function resolvePluginConfig(config) {
     assetUrl: normalizeAssetUrl(resolvedConfig.assetUrl ?? pythonDefaults?.assetUrl ?? "/static/"),
     resourceDirectory: resolvedConfig.resourceDirectory ?? pythonDefaults?.resourceDir ?? "resources",
     bundleDirectory: resolvedConfig.bundleDirectory ?? pythonDefaults?.bundleDir ?? "public",
+    publicDir: resolvedConfig.publicDir ?? pythonDefaults?.publicDir ?? "public",
     ssr: resolvedConfig.ssr ?? resolvedConfig.input,
     ssrOutputDirectory: resolvedConfig.ssrOutputDirectory ?? pythonDefaults?.ssrOutDir ?? path.join(resolvedConfig.resourceDirectory ?? pythonDefaults?.resourceDir ?? "resources", "bootstrap/ssr"),
     refresh: resolvedConfig.refresh ?? false,
@@ -406,10 +523,11 @@ function resolvePluginConfig(config) {
     autoDetectIndex: resolvedConfig.autoDetectIndex ?? true,
     transformOnServe: resolvedConfig.transformOnServe ?? ((code) => code),
     types: typesConfig,
-    executor: resolvedConfig.executor ?? pythonDefaults?.executor
+    executor: resolvedConfig.executor ?? pythonDefaults?.executor,
+    hasPythonConfig: pythonDefaults !== null
   };
 }
-function resolveBase(config, assetUrl) {
+function resolveBase(_config, assetUrl) {
   if (process.env.NODE_ENV === "development") {
     return assetUrl;
   }
@@ -557,12 +675,9 @@ declare global {
     /**
      * Simple route map (name -> uri) for legacy consumers.
      */
-    routes?: typeof routes
-    serverRoutes?: typeof serverRoutes
+    routes?: Record<string, string>
+    serverRoutes?: Record<string, string>
   }
-  // eslint-disable-next-line no-var
-  var routes: typeof routes | undefined
-  var serverRoutes: typeof serverRoutes | undefined
 }
 
 // Re-export helper functions from litestar-vite-plugin
@@ -571,12 +686,13 @@ export { getCsrfToken, csrfHeaders, csrfFetch } from "litestar-vite-plugin/helpe
 `;
   await fs.promises.writeFile(outFile, `${banner}${body}`, "utf-8");
 }
-function resolveTypeGenerationPlugin(typesConfig, executor) {
+function resolveTypeGenerationPlugin(typesConfig, executor, hasPythonConfig) {
   let lastTypesHash = null;
   let lastRoutesHash = null;
   let server = null;
   let isGenerating = false;
   let resolvedConfig = null;
+  let chosenConfigPath = null;
   async function runTypeGeneration() {
     if (isGenerating) {
       return false;
@@ -584,26 +700,47 @@ function resolveTypeGenerationPlugin(typesConfig, executor) {
     isGenerating = true;
     const startTime = Date.now();
     try {
-      const openapiPath = path.resolve(process.cwd(), typesConfig.openapiPath);
-      const routesPath = path.resolve(process.cwd(), typesConfig.routesPath);
+      const projectRoot = resolvedConfig?.root ?? process.cwd();
+      const openapiPath = path.resolve(projectRoot, typesConfig.openapiPath);
+      const routesPath = path.resolve(projectRoot, typesConfig.routesPath);
       let generated = false;
-      if (fs.existsSync(openapiPath)) {
+      const candidates = [path.resolve(projectRoot, "openapi-ts.config.ts"), path.resolve(projectRoot, "hey-api.config.ts"), path.resolve(projectRoot, ".hey-api.config.ts")];
+      const configPath = candidates.find((p) => fs.existsSync(p)) || null;
+      chosenConfigPath = configPath;
+      const shouldRunOpenApiTs = configPath || typesConfig.generateSdk;
+      if (fs.existsSync(openapiPath) && shouldRunOpenApiTs) {
+        resolvedConfig?.logger.info(`${colors.cyan("litestar-vite")} ${colors.dim("generating TypeScript types...")}`);
         if (resolvedConfig) {
-          resolvedConfig.logger.info(`${colors.cyan("litestar-vite")} ${colors.dim("generating TypeScript types...")}`);
+          resolvedConfig.logger.info(`${colors.cyan("litestar-vite")} ${colors.dim("openapi-ts config: ")}${configPath ?? "<built-in defaults>"}`);
         }
-        const args = ["@hey-api/openapi-ts", "-i", typesConfig.openapiPath, "-o", typesConfig.output];
-        if (typesConfig.generateZod) {
-          args.push("--plugins", "zod", "@hey-api/typescript");
+        const sdkOutput = path.join(typesConfig.output, "api");
+        let args;
+        if (configPath) {
+          args = ["@hey-api/openapi-ts", "--file", configPath];
+        } else {
+          args = ["@hey-api/openapi-ts", "-i", typesConfig.openapiPath, "-o", sdkOutput];
+          const plugins = ["@hey-api/typescript", "@hey-api/schemas"];
+          if (typesConfig.generateSdk) {
+            plugins.push("@hey-api/sdk", "@hey-api/client-axios");
+          }
+          if (typesConfig.generateZod) {
+            plugins.push("zod");
+          }
+          if (plugins.length) {
+            args.push("--plugins", ...plugins);
+          }
         }
-        if (typesConfig.generateSdk) {
-          args.push("--client", "fetch");
+        if (typesConfig.generateZod) {
+          try {
+            require.resolve("zod", { paths: [process.cwd()] });
+          } catch {
+            resolvedConfig?.logger.warn(`${colors.cyan("litestar-vite")} ${colors.yellow("zod not installed")} - run: ${resolveInstallHint()} zod`);
+          }
         }
         await execAsync(resolvePackageExecutor(args.join(" "), executor), {
-          cwd: process.cwd()
+          cwd: projectRoot
         });
         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);
@@ -628,7 +765,10 @@ function resolveTypeGenerationPlugin(typesConfig, executor) {
       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()}`);
+          const zodHint = typesConfig.generateZod ? " zod" : "";
+          resolvedConfig.logger.warn(
+            `${colors.cyan("litestar-vite")} ${colors.yellow("@hey-api/openapi-ts not installed")} - run: ${resolveInstallHint()} -D @hey-api/openapi-ts${zodHint}`
+          );
         } else {
           resolvedConfig.logger.error(`${colors.cyan("litestar-vite")} ${colors.red("type generation failed:")} ${message}`);
         }
@@ -648,14 +788,47 @@ function resolveTypeGenerationPlugin(typesConfig, executor) {
     configureServer(devServer) {
       server = devServer;
       if (typesConfig.enabled) {
-        resolvedConfig?.logger.info(`${colors.cyan("litestar-vite")} ${colors.dim("watching for schema changes:")} ${colors.yellow(typesConfig.openapiPath)}`);
+        const root = resolvedConfig?.root ?? process.cwd();
+        const openapiAbs = path.resolve(root, typesConfig.openapiPath);
+        const routesAbs = path.resolve(root, typesConfig.routesPath);
+        resolvedConfig?.logger.info(`${colors.cyan("litestar-vite")} ${colors.dim("watching schema/routes:")} ${colors.yellow(openapiAbs)}, ${colors.yellow(routesAbs)}`);
+        if (chosenConfigPath) {
+          resolvedConfig?.logger.info(`${colors.cyan("litestar-vite")} ${colors.dim("openapi-ts config:")} ${colors.yellow(chosenConfigPath)}`);
+        }
+      }
+    },
+    async buildStart() {
+      if (typesConfig.enabled && !hasPythonConfig) {
+        const projectRoot = resolvedConfig?.root ?? process.cwd();
+        const openapiPath = path.resolve(projectRoot, typesConfig.openapiPath);
+        if (!fs.existsSync(openapiPath)) {
+          this.warn(
+            `Type generation is enabled but .litestar.json was not found.
+The Litestar backend generates this file on startup.
+
+Solutions:
+  1. Start the backend first: ${colors.cyan("litestar run")}
+  2. Use integrated dev: ${colors.cyan("litestar assets serve")}
+  3. Disable types: ${colors.cyan("litestar({ input: [...], types: false })")}
+`
+          );
+        }
+      }
+      if (typesConfig.enabled) {
+        const projectRoot = resolvedConfig?.root ?? process.cwd();
+        const openapiPath = path.resolve(projectRoot, typesConfig.openapiPath);
+        const routesPath = path.resolve(projectRoot, typesConfig.routesPath);
+        if (fs.existsSync(openapiPath) || fs.existsSync(routesPath)) {
+          await runTypeGeneration();
+        }
       }
     },
     async handleHotUpdate({ file }) {
       if (!typesConfig.enabled) {
         return;
       }
-      const relativePath = path.relative(process.cwd(), file);
+      const root = resolvedConfig?.root ?? process.cwd();
+      const relativePath = path.relative(root, file);
       const openapiPath = typesConfig.openapiPath.replace(/^\.\//, "");
       const routesPath = typesConfig.routesPath.replace(/^\.\//, "");
       if (relativePath === openapiPath || relativePath === routesPath || file.endsWith(openapiPath) || file.endsWith(routesPath)) {

package/dist/js/inertia-helpers/index.d.ts

@@ -4,9 +4,14 @@
  * This module re-exports common helpers from litestar-vite-plugin/helpers
  * and adds Inertia-specific utilities.
  *
+ * For type-safe routing, import from your generated routes file:
+ * ```ts
+ * import { route, routes, type RouteName } from '@/generated/routes'
+ * ```
+ *
  * @module
  */
-export { getCsrfToken, csrfHeaders, csrfFetch, route, getRoutes, toRoute, currentRoute, isRoute, isCurrentRoute, getRelativeUrlPath, type RouteDefinition, type RoutesMap, } from "litestar-vite-plugin/helpers";
+export { csrfFetch, csrfHeaders, getCsrfToken, } from "litestar-vite-plugin/helpers";
 /**
  * Unwrap page props that may have content nested under "content" key.
  *

package/dist/js/inertia-helpers/index.js

@@ -4,15 +4,18 @@
  * This module re-exports common helpers from litestar-vite-plugin/helpers
  * and adds Inertia-specific utilities.
  *
+ * For type-safe routing, import from your generated routes file:
+ * ```ts
+ * import { route, routes, type RouteName } from '@/generated/routes'
+ * ```
+ *
  * @module
  */
 // Re-export all helpers from the main helpers module
 // Note: Using package path instead of relative import to ensure proper build output structure
-export { 
+export { csrfFetch, csrfHeaders, 
 // CSRF utilities
-getCsrfToken, csrfHeaders, csrfFetch, 
-// Route utilities
-route, getRoutes, toRoute, currentRoute, isRoute, isCurrentRoute, getRelativeUrlPath, } from "litestar-vite-plugin/helpers";
+getCsrfToken, } from "litestar-vite-plugin/helpers";
 /**
  * Unwrap page props that may have content nested under "content" key.
  *

package/dist/js/litestar-meta.js

@@ -11,7 +11,11 @@ async function checkBackendAvailability(appUrl) {
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), 2e3);
     const schemaPath = process.env.LITESTAR_OPENAPI_PATH || "/schema";
-    const checkUrl = new URL(schemaPath, appUrl).href;
+    const urlObj = new URL(schemaPath, appUrl);
+    if (urlObj.hostname === "0.0.0.0") {
+      urlObj.hostname = "127.0.0.1";
+    }
+    const checkUrl = urlObj.href;
     const response = await fetch(checkUrl, {
       method: "GET",
       signal: controller.signal
@@ -58,11 +62,23 @@ function firstExisting(paths) {
   }
   return null;
 }
+function loadVersionFromRuntimeConfig() {
+  const cfgPath = process.env.LITESTAR_VITE_CONFIG_PATH;
+  if (!cfgPath || !fs.existsSync(cfgPath)) return null;
+  try {
+    const raw = fs.readFileSync(cfgPath, "utf8");
+    const data = JSON.parse(raw);
+    const v = data?.litestarVersion;
+    return typeof v === "string" && v.trim() ? v.trim() : null;
+  } catch {
+    return null;
+  }
+}
 async function loadLitestarMeta(resolvedConfig, routesPathHint) {
   const fromEnv = process.env.LITESTAR_VERSION?.trim();
-  if (fromEnv) {
-    return { litestarVersion: fromEnv };
-  }
+  if (fromEnv) return { litestarVersion: fromEnv };
+  const fromRuntime = loadVersionFromRuntimeConfig();
+  if (fromRuntime) return { litestarVersion: fromRuntime };
   const root = resolvedConfig.root ?? process.cwd();
   const candidates = [routesPathHint ? path.resolve(root, routesPathHint) : null, path.resolve(root, "src/generated/routes.json"), path.resolve(root, "routes.json")].filter(
     Boolean

package/dist/js/nuxt.d.ts

@@ -61,6 +61,12 @@ export interface NuxtTypesConfig {
      * @default false
      */
     generateZod?: boolean;
+    /**
+     * Generate SDK client functions for API calls.
+     *
+     * @default true
+     */
+    generateSdk?: boolean;
     /**
      * Debounce time in milliseconds for type regeneration.
      *

package/dist/js/nuxt.js

@@ -51,6 +51,7 @@ function resolveConfig(config = {}) {
       openapiPath: "openapi.json",
       routesPath: "routes.json",
       generateZod: false,
+      generateSdk: true,
       debounce: 300
     };
   } else if (typeof config.types === "object" && config.types !== null) {
@@ -60,6 +61,7 @@ function resolveConfig(config = {}) {
       openapiPath: config.types.openapiPath ?? "openapi.json",
       routesPath: config.types.routesPath ?? "routes.json",
       generateZod: config.types.generateZod ?? false,
+      generateSdk: config.types.generateSdk ?? true,
       debounce: config.types.debounce ?? 300
     };
   }
@@ -96,6 +98,15 @@ function createProxyPlugin(config) {
       hmrPort = await getPort();
       return {
         server: {
+          // Force IPv4 binding for consistency with Python proxy configuration
+          // Without this, Nuxt/Nitro might bind to IPv6 localhost which the proxy can't reach
+          host: "127.0.0.1",
+          // Set the port from Python config/env to ensure Nuxt uses the expected port
+          // strictPort: true prevents auto-incrementing to a different port
+          ...config.devPort !== void 0 ? {
+            port: config.devPort,
+            strictPort: true
+          } : {},
           // Avoid HMR port collisions by letting Vite pick a free port for WS
           hmr: {
             port: hmrPort,
@@ -281,12 +292,28 @@ function createTypeGenerationPlugin(typesConfig, executor) {
         return false;
       }
       console.log(colors.cyan("[litestar-nuxt]"), colors.dim("Generating TypeScript types..."));
-      const args = ["@hey-api/openapi-ts", "-i", typesConfig.openapiPath, "-o", typesConfig.output];
-      if (typesConfig.generateZod) {
-        args.push("--plugins", "zod", "@hey-api/typescript");
+      const projectRoot = process.cwd();
+      const candidates = [path.resolve(projectRoot, "openapi-ts.config.ts"), path.resolve(projectRoot, "hey-api.config.ts"), path.resolve(projectRoot, ".hey-api.config.ts")];
+      const configPath = candidates.find((p) => fs.existsSync(p)) || null;
+      let args;
+      if (configPath) {
+        console.log(colors.cyan("[litestar-nuxt]"), colors.dim("Using config:"), configPath);
+        args = ["@hey-api/openapi-ts", "--file", configPath];
+      } else {
+        args = ["@hey-api/openapi-ts", "-i", typesConfig.openapiPath, "-o", typesConfig.output];
+        const plugins = ["@hey-api/typescript", "@hey-api/schemas"];
+        if (typesConfig.generateSdk) {
+          plugins.push("@hey-api/sdk", "@hey-api/client-nuxt");
+        }
+        if (typesConfig.generateZod) {
+          plugins.push("zod");
+        }
+        if (plugins.length) {
+          args.push("--plugins", ...plugins);
+        }
       }
       await execAsync(resolvePackageExecutor(args.join(" "), executor), {
-        cwd: process.cwd()
+        cwd: projectRoot
       });
       const routesPath = path.resolve(process.cwd(), typesConfig.routesPath);
       if (fs.existsSync(routesPath)) {
@@ -325,6 +352,14 @@ function createTypeGenerationPlugin(typesConfig, executor) {
       server = devServer;
       console.log(colors.cyan("[litestar-nuxt]"), colors.dim("Watching for schema changes:"), colors.yellow(typesConfig.openapiPath));
     },
+    async buildStart() {
+      if (typesConfig.enabled) {
+        const openapiPath = path.resolve(process.cwd(), typesConfig.openapiPath);
+        if (fs.existsSync(openapiPath)) {
+          await runTypeGeneration();
+        }
+      }
+    },
     handleHotUpdate({ file }) {
       if (!typesConfig.enabled) {
         return;