litestar-vite-plugin 0.15.0-rc.5 → 0.16.0

package/dist/js/index.js

@@ -6,6 +6,7 @@ import { loadEnv } from "vite";
 import fullReload from "vite-plugin-full-reload";
 import { checkBackendAvailability, loadLitestarMeta } from "./litestar-meta.js";
 import { readBridgeConfig } from "./shared/bridge-schema.js";
+import { DEBOUNCE_MS } from "./shared/constants.js";
 import { createLogger } from "./shared/logger.js";
 import { createLitestarTypeGenPlugin } from "./shared/typegen-plugin.js";
 let exitHandlersBound = false;
@@ -222,7 +223,11 @@ function resolveLitestarPlugin(pluginConfig) {
       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 normalizedHot = pluginConfig.hotFile.replace(/^\/+/, "");
+        const normalizedBundle = pluginConfig.bundleDir?.replace(/^\/+/, "").replace(/\/+$/, "");
+        const hotUnderBundle = normalizedBundle ? normalizedHot.startsWith(`${normalizedBundle}/`) : false;
+        const baseDir = hotUnderBundle ? server.config.root : path.resolve(server.config.root, normalizedBundle ?? "");
+        pluginConfig.hotFile = path.resolve(baseDir, normalizedHot);
       }
       const initialIndexPath = await findIndexHtmlPath(server, pluginConfig);
       server.httpServer?.once("listening", () => {
@@ -509,20 +514,27 @@ function resolvePluginConfig(config) {
     resolvedConfig.refresh = [{ paths: refreshPaths }];
   }
   let typesConfig = false;
+  const defaultTypesOutput = "src/generated";
+  const defaultOpenapiPath = path.join(defaultTypesOutput, "openapi.json");
+  const defaultRoutesPath = path.join(defaultTypesOutput, "routes.json");
+  const defaultSchemasTsPath = path.join(defaultTypesOutput, "schemas.ts");
+  const defaultPagePropsPath = path.join(defaultTypesOutput, "inertia-pages.json");
   if (resolvedConfig.types === false) {
   } else if (resolvedConfig.types === true) {
     typesConfig = {
       enabled: true,
-      output: "src/generated/types",
-      openapiPath: "src/generated/openapi.json",
-      routesPath: "src/generated/routes.json",
-      pagePropsPath: "src/generated/inertia-pages.json",
+      output: defaultTypesOutput,
+      openapiPath: defaultOpenapiPath,
+      routesPath: defaultRoutesPath,
+      pagePropsPath: defaultPagePropsPath,
+      schemasTsPath: defaultSchemasTsPath,
       generateZod: false,
-      generateSdk: false,
+      generateSdk: true,
       generateRoutes: true,
       generatePageProps: true,
+      generateSchemas: true,
       globalRoute: false,
-      debounce: 300
+      debounce: DEBOUNCE_MS
     };
   } else if (resolvedConfig.types === "auto" || typeof resolvedConfig.types === "undefined") {
     if (pythonDefaults?.types) {
@@ -532,30 +544,35 @@ function resolvePluginConfig(config) {
         openapiPath: pythonDefaults.types.openapiPath,
         routesPath: pythonDefaults.types.routesPath,
         pagePropsPath: pythonDefaults.types.pagePropsPath,
+        schemasTsPath: pythonDefaults.types.schemasTsPath ?? path.join(pythonDefaults.types.output, "schemas.ts"),
         generateZod: pythonDefaults.types.generateZod,
         generateSdk: pythonDefaults.types.generateSdk,
         generateRoutes: pythonDefaults.types.generateRoutes,
         generatePageProps: pythonDefaults.types.generatePageProps,
+        generateSchemas: pythonDefaults.types.generateSchemas ?? true,
         globalRoute: pythonDefaults.types.globalRoute,
-        debounce: 300
+        debounce: DEBOUNCE_MS
       };
     }
   } else if (typeof resolvedConfig.types === "object" && resolvedConfig.types !== null) {
     const userProvidedOpenapi = Object.hasOwn(resolvedConfig.types, "openapiPath");
     const userProvidedRoutes = Object.hasOwn(resolvedConfig.types, "routesPath");
     const userProvidedPageProps = Object.hasOwn(resolvedConfig.types, "pagePropsPath");
+    const userProvidedSchemasTs = Object.hasOwn(resolvedConfig.types, "schemasTsPath");
     typesConfig = {
       enabled: resolvedConfig.types.enabled ?? true,
-      output: resolvedConfig.types.output ?? "src/generated/types",
-      openapiPath: resolvedConfig.types.openapiPath ?? (resolvedConfig.types.output ? path.join(resolvedConfig.types.output, "openapi.json") : "src/generated/openapi.json"),
-      routesPath: resolvedConfig.types.routesPath ?? (resolvedConfig.types.output ? path.join(resolvedConfig.types.output, "routes.json") : "src/generated/routes.json"),
-      pagePropsPath: resolvedConfig.types.pagePropsPath ?? (resolvedConfig.types.output ? path.join(resolvedConfig.types.output, "inertia-pages.json") : "src/generated/inertia-pages.json"),
+      output: resolvedConfig.types.output ?? defaultTypesOutput,
+      openapiPath: resolvedConfig.types.openapiPath ?? (resolvedConfig.types.output ? path.join(resolvedConfig.types.output, "openapi.json") : defaultOpenapiPath),
+      routesPath: resolvedConfig.types.routesPath ?? (resolvedConfig.types.output ? path.join(resolvedConfig.types.output, "routes.json") : defaultRoutesPath),
+      pagePropsPath: resolvedConfig.types.pagePropsPath ?? (resolvedConfig.types.output ? path.join(resolvedConfig.types.output, "inertia-pages.json") : defaultPagePropsPath),
+      schemasTsPath: resolvedConfig.types.schemasTsPath ?? (resolvedConfig.types.output ? path.join(resolvedConfig.types.output, "schemas.ts") : defaultSchemasTsPath),
       generateZod: resolvedConfig.types.generateZod ?? false,
-      generateSdk: resolvedConfig.types.generateSdk ?? false,
+      generateSdk: resolvedConfig.types.generateSdk ?? true,
       generateRoutes: resolvedConfig.types.generateRoutes ?? true,
       generatePageProps: resolvedConfig.types.generatePageProps ?? true,
+      generateSchemas: resolvedConfig.types.generateSchemas ?? true,
       globalRoute: resolvedConfig.types.globalRoute ?? false,
-      debounce: resolvedConfig.types.debounce ?? 300
+      debounce: resolvedConfig.types.debounce ?? DEBOUNCE_MS
     };
     if (!userProvidedOpenapi && resolvedConfig.types.output) {
       typesConfig.openapiPath = path.join(typesConfig.output, "openapi.json");
@@ -566,21 +583,27 @@ function resolvePluginConfig(config) {
     if (!userProvidedPageProps && resolvedConfig.types.output) {
       typesConfig.pagePropsPath = path.join(typesConfig.output, "inertia-pages.json");
     }
+    if (!userProvidedSchemasTs && resolvedConfig.types.output) {
+      typesConfig.schemasTsPath = path.join(typesConfig.output, "schemas.ts");
+    }
   }
   const inertiaMode = resolvedConfig.inertiaMode ?? (pythonDefaults?.mode === "hybrid" || pythonDefaults?.mode === "inertia");
   const effectiveResourceDir = resolvedConfig.resourceDir ?? pythonDefaults?.resourceDir ?? "src";
+  const resolvedBundleDir = resolvedConfig.bundleDir ?? pythonDefaults?.bundleDir ?? "public";
+  const resolvedStaticDir = resolvedConfig.staticDir ?? pythonDefaults?.staticDir ?? path.join(effectiveResourceDir, "public");
+  const resolvedHotFile = resolvedConfig.hotFile ?? pythonDefaults?.hotFile ?? path.join(resolvedBundleDir, "hot");
   const deployAssetUrlRaw = resolvedConfig.deployAssetUrl ?? pythonDefaults?.deployAssetUrl ?? void 0;
   const result = {
     input: resolvedConfig.input,
     assetUrl: normalizeAssetUrl(resolvedConfig.assetUrl ?? pythonDefaults?.assetUrl ?? "/static/"),
     deployAssetUrl: typeof deployAssetUrlRaw === "string" ? normalizeAssetUrl(deployAssetUrlRaw) : void 0,
     resourceDir: effectiveResourceDir,
-    bundleDir: resolvedConfig.bundleDir ?? pythonDefaults?.bundleDir ?? "public",
-    staticDir: resolvedConfig.staticDir ?? pythonDefaults?.staticDir ?? path.join(effectiveResourceDir, "public"),
+    bundleDir: resolvedBundleDir,
+    staticDir: resolvedStaticDir,
     ssr: resolvedConfig.ssr ?? resolvedConfig.input,
     ssrOutDir: resolvedConfig.ssrOutDir ?? pythonDefaults?.ssrOutDir ?? path.join(effectiveResourceDir, "bootstrap/ssr"),
     refresh: resolvedConfig.refresh ?? false,
-    hotFile: resolvedConfig.hotFile ?? path.join(resolvedConfig.bundleDir ?? "public", "hot"),
+    hotFile: resolvedHotFile,
     detectTls: resolvedConfig.detectTls ?? false,
     autoDetectIndex: resolvedConfig.autoDetectIndex ?? true,
     inertiaMode,
@@ -771,7 +794,7 @@ function dirname() {
   try {
     return fileURLToPath(new URL(".", import.meta.url));
   } catch {
-    return path.resolve(process.cwd(), "src/js/src");
+    return path.resolve(process.cwd(), "dist/js");
   }
 }
 function normalizeAssetUrl(url) {

package/dist/js/nuxt.d.ts

@@ -15,10 +15,7 @@
  *   litestar: {
  *     apiProxy: 'http://localhost:8000',
  *     apiPrefix: '/api',
- *     types: {
- *       enabled: true,
- *       output: 'generated',
- *     },
+ *     types: true,
  *   },
  * });
  * ```
@@ -46,19 +43,25 @@ export interface NuxtTypesConfig {
     /**
      * Path where the OpenAPI schema is exported by Litestar.
      *
-     * @default 'openapi.json'
+     * @default `${output}/openapi.json`
      */
     openapiPath?: string;
     /**
      * Path where route metadata is exported by Litestar.
      *
-     * @default 'routes.json'
+     * @default `${output}/routes.json`
      */
     routesPath?: string;
+    /**
+     * Optional path for the generated schemas.ts helper file.
+     *
+     * @default `${output}/schemas.ts`
+     */
+    schemasTsPath?: string;
     /**
      * Path where Inertia page props metadata is exported by Litestar.
      *
-     * @default 'inertia-pages.json'
+     * @default `${output}/inertia-pages.json`
      */
     pagePropsPath?: string;
     /**
@@ -85,6 +88,12 @@ export interface NuxtTypesConfig {
      * @default true
      */
     generatePageProps?: boolean;
+    /**
+     * Generate schemas.ts with ergonomic form/response type helpers.
+     *
+     * @default true
+     */
+    generateSchemas?: boolean;
     /**
      * Register route() globally on window object.
      *

package/dist/js/nuxt.js

@@ -2,16 +2,9 @@ import fs from "node:fs";
 import path from "node:path";
 import colors from "picocolors";
 import { readBridgeConfig } from "./shared/bridge-schema.js";
+import { DEBOUNCE_MS } from "./shared/constants.js";
+import { normalizeHost, resolveHotFilePath } from "./shared/network.js";
 import { createLitestarTypeGenPlugin } from "./shared/typegen-plugin.js";
-function normalizeHost(host) {
-  if (host === "::" || host === "::1" || host === "0.0.0.0") {
-    return "localhost";
-  }
-  if (host.includes(":") && !host.startsWith("[")) {
-    return `[${host}]`;
-  }
-  return host;
-}
 function resolveConfig(config = {}) {
   let hotFile;
   let proxyMode = "vite";
@@ -30,7 +23,7 @@ function resolveConfig(config = {}) {
   if (runtime) {
     hasPythonConfig = true;
     const hot = runtime.hotFile;
-    hotFile = path.isAbsolute(hot) ? hot : path.resolve(process.cwd(), runtime.bundleDir, hot);
+    hotFile = resolveHotFilePath(runtime.bundleDir, hot);
     proxyMode = runtime.proxyMode;
     devPort = runtime.port;
     pythonExecutor = runtime.executor;
@@ -39,47 +32,71 @@ function resolveConfig(config = {}) {
     }
   }
   let typesConfig = false;
+  const defaultTypesOutput = "generated";
+  const buildTypeDefaults = (output) => ({
+    openapiPath: path.join(output, "openapi.json"),
+    routesPath: path.join(output, "routes.json"),
+    pagePropsPath: path.join(output, "inertia-pages.json"),
+    schemasTsPath: path.join(output, "schemas.ts")
+  });
   if (config.types === true) {
+    const output = pythonTypesConfig?.output ?? defaultTypesOutput;
+    const defaults = buildTypeDefaults(output);
     typesConfig = {
       enabled: true,
-      output: pythonTypesConfig?.output ?? "generated",
-      openapiPath: pythonTypesConfig?.openapiPath ?? "openapi.json",
-      routesPath: pythonTypesConfig?.routesPath ?? "routes.json",
-      pagePropsPath: pythonTypesConfig?.pagePropsPath ?? "inertia-pages.json",
+      output,
+      openapiPath: pythonTypesConfig?.openapiPath ?? defaults.openapiPath,
+      routesPath: pythonTypesConfig?.routesPath ?? defaults.routesPath,
+      pagePropsPath: pythonTypesConfig?.pagePropsPath ?? defaults.pagePropsPath,
+      schemasTsPath: pythonTypesConfig?.schemasTsPath ?? defaults.schemasTsPath,
       generateZod: pythonTypesConfig?.generateZod ?? false,
       generateSdk: pythonTypesConfig?.generateSdk ?? true,
       generateRoutes: pythonTypesConfig?.generateRoutes ?? true,
       generatePageProps: pythonTypesConfig?.generatePageProps ?? true,
+      generateSchemas: pythonTypesConfig?.generateSchemas ?? true,
       globalRoute: pythonTypesConfig?.globalRoute ?? false,
-      debounce: 300
+      debounce: DEBOUNCE_MS
     };
   } else if (typeof config.types === "object" && config.types !== null) {
+    const userProvidedOutput = Object.hasOwn(config.types, "output");
+    const output = config.types.output ?? pythonTypesConfig?.output ?? defaultTypesOutput;
+    const defaults = buildTypeDefaults(output);
+    const openapiFallback = userProvidedOutput ? defaults.openapiPath : pythonTypesConfig?.openapiPath ?? defaults.openapiPath;
+    const routesFallback = userProvidedOutput ? defaults.routesPath : pythonTypesConfig?.routesPath ?? defaults.routesPath;
+    const pagePropsFallback = userProvidedOutput ? defaults.pagePropsPath : pythonTypesConfig?.pagePropsPath ?? defaults.pagePropsPath;
+    const schemasFallback = userProvidedOutput ? defaults.schemasTsPath : pythonTypesConfig?.schemasTsPath ?? defaults.schemasTsPath;
     typesConfig = {
       enabled: config.types.enabled ?? true,
-      output: config.types.output ?? pythonTypesConfig?.output ?? "generated",
-      openapiPath: config.types.openapiPath ?? pythonTypesConfig?.openapiPath ?? "openapi.json",
-      routesPath: config.types.routesPath ?? pythonTypesConfig?.routesPath ?? "routes.json",
-      pagePropsPath: config.types.pagePropsPath ?? pythonTypesConfig?.pagePropsPath ?? "inertia-pages.json",
+      output,
+      openapiPath: config.types.openapiPath ?? openapiFallback,
+      routesPath: config.types.routesPath ?? routesFallback,
+      pagePropsPath: config.types.pagePropsPath ?? pagePropsFallback,
+      schemasTsPath: config.types.schemasTsPath ?? schemasFallback,
       generateZod: config.types.generateZod ?? pythonTypesConfig?.generateZod ?? false,
       generateSdk: config.types.generateSdk ?? pythonTypesConfig?.generateSdk ?? true,
       generateRoutes: config.types.generateRoutes ?? pythonTypesConfig?.generateRoutes ?? true,
       generatePageProps: config.types.generatePageProps ?? pythonTypesConfig?.generatePageProps ?? true,
+      generateSchemas: config.types.generateSchemas ?? pythonTypesConfig?.generateSchemas ?? true,
       globalRoute: config.types.globalRoute ?? pythonTypesConfig?.globalRoute ?? false,
-      debounce: config.types.debounce ?? 300
+      debounce: config.types.debounce ?? DEBOUNCE_MS
     };
   } else if (config.types !== false && pythonTypesConfig?.enabled) {
+    const output = pythonTypesConfig.output ?? defaultTypesOutput;
+    const defaults = buildTypeDefaults(output);
     typesConfig = {
       enabled: true,
-      output: pythonTypesConfig.output ?? "generated",
-      openapiPath: pythonTypesConfig.openapiPath ?? "openapi.json",
-      routesPath: pythonTypesConfig.routesPath ?? "routes.json",
-      pagePropsPath: pythonTypesConfig.pagePropsPath ?? "inertia-pages.json",
+      output,
+      openapiPath: pythonTypesConfig.openapiPath ?? defaults.openapiPath,
+      routesPath: pythonTypesConfig.routesPath ?? defaults.routesPath,
+      pagePropsPath: pythonTypesConfig.pagePropsPath ?? defaults.pagePropsPath,
+      schemasTsPath: pythonTypesConfig.schemasTsPath ?? defaults.schemasTsPath,
       generateZod: pythonTypesConfig.generateZod ?? false,
       generateSdk: pythonTypesConfig.generateSdk ?? true,
       generateRoutes: pythonTypesConfig.generateRoutes ?? true,
       generatePageProps: pythonTypesConfig.generatePageProps ?? true,
+      generateSchemas: pythonTypesConfig.generateSchemas ?? true,
       globalRoute: pythonTypesConfig.globalRoute ?? false,
-      debounce: 300
+      debounce: DEBOUNCE_MS
     };
   }
   return {

package/dist/js/shared/bridge-schema.d.ts

@@ -17,10 +17,13 @@ export interface BridgeTypesConfig {
     openapiPath: string;
     routesPath: string;
     pagePropsPath: string;
+    routesTsPath?: string;
+    schemasTsPath?: string;
     generateZod: boolean;
     generateSdk: boolean;
     generateRoutes: boolean;
     generatePageProps: boolean;
+    generateSchemas: boolean;
     globalRoute: boolean;
 }
 export interface BridgeSpaConfig {

package/dist/js/shared/bridge-schema.js

@@ -61,6 +61,14 @@ function assertNullableString(obj, key) {
   }
   return value;
 }
+function assertOptionalString(obj, key) {
+  const value = obj[key];
+  if (value === void 0) return void 0;
+  if (typeof value !== "string" || value.length === 0) {
+    fail(`"${key}" must be a non-empty string`);
+  }
+  return value;
+}
 function assertEnum(value, key, allowed) {
   if (typeof value !== "string" || !allowed.has(value)) {
     fail(`"${key}" must be one of: ${Array.from(allowed).join(", ")}`);
@@ -71,6 +79,14 @@ function assertProxyMode(value) {
   if (value === null) return null;
   return assertEnum(value, "proxyMode", allowedProxyModes);
 }
+function assertOptionalBoolean(obj, key, defaultValue) {
+  const value = obj[key];
+  if (value === void 0) return defaultValue;
+  if (typeof value !== "boolean") {
+    fail(`"${key}" must be a boolean`);
+  }
+  return value;
+}
 function parseTypesConfig(value) {
   if (value === null) return null;
   const obj = assertObject(value, "types");
@@ -79,10 +95,13 @@ function parseTypesConfig(value) {
   const openapiPath = assertString(obj, "openapiPath");
   const routesPath = assertString(obj, "routesPath");
   const pagePropsPath = assertString(obj, "pagePropsPath");
+  const routesTsPath = assertOptionalString(obj, "routesTsPath");
+  const schemasTsPath = assertOptionalString(obj, "schemasTsPath");
   const generateZod = assertBoolean(obj, "generateZod");
   const generateSdk = assertBoolean(obj, "generateSdk");
   const generateRoutes = assertBoolean(obj, "generateRoutes");
   const generatePageProps = assertBoolean(obj, "generatePageProps");
+  const generateSchemas = assertOptionalBoolean(obj, "generateSchemas", true);
   const globalRoute = assertBoolean(obj, "globalRoute");
   return {
     enabled,
@@ -90,10 +109,13 @@ function parseTypesConfig(value) {
     openapiPath,
     routesPath,
     pagePropsPath,
+    routesTsPath,
+    schemasTsPath,
     generateZod,
     generateSdk,
     generateRoutes,
     generatePageProps,
+    generateSchemas,
     globalRoute
   };
 }

package/dist/js/shared/constants.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Shared constants for litestar-vite plugin.
+ *
+ * Centralizes magic values that are reused across multiple modules.
+ */
+/**
+ * Default debounce time in milliseconds for type regeneration.
+ *
+ * Used across all framework integrations (Vite, Nuxt, Astro, SvelteKit)
+ * to avoid excessive regeneration during rapid file changes.
+ */
+export declare const DEBOUNCE_MS = 300;
+/**
+ * Timeout in milliseconds for backend health checks.
+ *
+ * Used when checking if the Litestar backend is available
+ * before attempting to fetch OpenAPI schema.
+ */
+export declare const BACKEND_CHECK_TIMEOUT_MS = 2000;
+/**
+ * Default asset URL path.
+ *
+ * Used as fallback when no explicit assetUrl is configured.
+ * Should match the default in Python ViteConfig.
+ */
+export declare const DEFAULT_ASSET_URL = "/static/";
+/**
+ * Default output directory for generated TypeScript types.
+ *
+ * Used by framework integrations as fallback when no output
+ * is specified in Python bridge config or plugin options.
+ */
+export declare const DEFAULT_TYPES_OUTPUT = "src/generated";

package/dist/js/shared/constants.js

@@ -0,0 +1,10 @@
+const DEBOUNCE_MS = 300;
+const BACKEND_CHECK_TIMEOUT_MS = 2e3;
+const DEFAULT_ASSET_URL = "/static/";
+const DEFAULT_TYPES_OUTPUT = "src/generated";
+export {
+  BACKEND_CHECK_TIMEOUT_MS,
+  DEBOUNCE_MS,
+  DEFAULT_ASSET_URL,
+  DEFAULT_TYPES_OUTPUT
+};

package/dist/js/shared/emit-schemas-types.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Generate schemas.ts from routes.json and hey-api types.gen.ts.
+ *
+ * @param routesJsonPath - Path to routes.json
+ * @param outputDir - Output directory (contains api/types.gen.ts)
+ * @returns true if file was changed, false if unchanged
+ */
+export declare function emitSchemasTypes(routesJsonPath: string, outputDir: string, schemasOutputPath?: string): Promise<boolean>;