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

package/dist/js/helpers/index.js

@@ -6,10 +6,10 @@
  *
  * @example
  * ```ts
- * import { route, getCsrfToken, csrfFetch } from 'litestar-vite-plugin/helpers'
+ * import { getCsrfToken, csrfFetch } from 'litestar-vite-plugin/helpers'
  *
- * // Generate a URL for a named route
- * const url = route('user:detail', { user_id: 123 })
+ * // Get CSRF token
+ * const token = getCsrfToken()
  *
  * // Make a fetch request with CSRF token
  * await csrfFetch('/api/submit', {
@@ -18,9 +18,17 @@
  * })
  * ```
  *
+ * For type-safe routing, import from your generated routes file:
+ * ```ts
+ * import { route, routes, type RouteName } from '@/generated/routes'
+ *
+ * // Type-safe URL generation
+ * const url = route('user_detail', { user_id: 123 })  // Compile-time checked!
+ * ```
+ *
  * @module
  */
 // CSRF utilities
 export { csrfFetch, csrfHeaders, getCsrfToken } from "./csrf.js";
-// Route utilities
-export { currentRoute, getRelativeUrlPath, getRoutes, isCurrentRoute, isRoute, LITESTAR, route, toRoute, } from "./routes.js";
+// HTMX utilities
+export { addDirective, registerHtmxExtension, setDebug as setHtmxDebug, swapJson } from "./htmx.js";

package/dist/js/index.d.ts

@@ -73,6 +73,13 @@ export interface PluginConfig {
      * @default 'public/dist'
      */
     bundleDirectory?: string;
+    /**
+     * Vite's public directory for static, unprocessed assets.
+     * Mirrors Vite's `publicDir` option.
+     *
+     * @default 'public'
+     */
+    publicDir?: string;
     /**
      * Litestar's public assets directory.  These are the assets that Vite will serve when developing.
      *
@@ -121,18 +128,36 @@ export interface PluginConfig {
     /**
      * Enable and configure TypeScript type generation.
      *
-     * When set to `true`, enables type generation with default settings.
-     * When set to a TypesConfig object, enables type generation with custom settings.
+     * Configuration priority (highest to lowest):
+     * 1. Explicit vite.config.ts value - ALWAYS wins
+     * 2. .litestar.json value - used if no explicit config
+     * 3. Hardcoded defaults - fallback if nothing else
+     *
+     * When set to `"auto"` (recommended): reads all config from `.litestar.json`.
+     * If `.litestar.json` is missing, type generation is disabled.
+     *
+     * When set to `true`: enables type generation with hardcoded defaults.
+     * When set to `false`: disables type generation entirely.
+     * When set to a TypesConfig object: uses your explicit settings.
      *
-     * Type generation creates TypeScript types from your Litestar OpenAPI schema
-     * and route metadata using @hey-api/openapi-ts.
+     * When not specified (undefined): behaves like `"auto"` - reads from
+     * `.litestar.json` if present, otherwise disabled.
      *
      * @example
      * ```ts
-     * // Simple enable
+     * // Recommended: auto-read from .litestar.json (simplest)
+     * litestar({ input: 'src/main.ts' })
+     *
+     * // Explicit auto mode
+     * litestar({ input: 'src/main.ts', types: 'auto' })
+     *
+     * // Force enable with hardcoded defaults (ignores .litestar.json)
      * litestar({ input: 'src/main.ts', types: true })
      *
-     * // With custom config
+     * // Force disable
+     * litestar({ input: 'src/main.ts', types: false })
+     *
+     * // Manual override (ignores .litestar.json for types)
      * litestar({
      *   input: 'src/main.ts',
      *   types: {
@@ -143,9 +168,9 @@ export interface PluginConfig {
      * })
      * ```
      *
-     * @default false
+     * @default undefined (auto-detect from .litestar.json)
      */
-    types?: boolean | TypesConfig;
+    types?: boolean | "auto" | TypesConfig;
     /**
      * JavaScript runtime executor for package commands.
      * Used when running tools like @hey-api/openapi-ts.

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 {
@@ -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,6 +189,19 @@ 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);
     },
@@ -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.");
   }
@@ -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,6 +478,18 @@ 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.hasOwn(resolvedConfig.types, "openapiPath");
     const userProvidedRoutes = Object.hasOwn(resolvedConfig.types, "routesPath");
@@ -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,7 +523,8 @@ 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) {
@@ -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 { csrfFetch, csrfHeaders, currentRoute, getCsrfToken, getRelativeUrlPath, getRoutes, isCurrentRoute, isRoute, type RouteDefinition, type RoutesMap, route, toRoute, } 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 { csrfFetch, csrfHeaders, currentRoute, 
+export { csrfFetch, csrfHeaders, 
 // CSRF utilities
-getCsrfToken, getRelativeUrlPath, getRoutes, isCurrentRoute, isRoute, 
-// Route utilities
-route, toRoute, } 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.
      *