litestar-vite-plugin 0.15.0-beta.1 → 0.15.0-beta.3

package/dist/js/nuxt.js

@@ -1,11 +1,7 @@
-import { exec } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
-import { promisify } from "node:util";
 import colors from "picocolors";
-import { resolveInstallHint, resolvePackageExecutor } from "./install-hint.js";
-import { debounce } from "./shared/debounce.js";
-const execAsync = promisify(exec);
+import { createTypeGenerationPlugin } from "./shared/create-type-gen-plugin.js";
 function normalizeHost(host) {
   if (host === "::" || host === "::1" || host === "0.0.0.0") {
     return "localhost";
@@ -151,234 +147,18 @@ function createProxyPlugin(config) {
     }
   };
 }
-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 createTypeGenerationPlugin(typesConfig, executor) {
-  let server = null;
-  let isGenerating = false;
-  async function runTypeGeneration() {
-    if (isGenerating) {
-      return false;
-    }
-    isGenerating = true;
-    const startTime = Date.now();
-    try {
-      const openapiPath = path.resolve(process.cwd(), typesConfig.openapiPath);
-      if (!fs.existsSync(openapiPath)) {
-        console.log(colors.cyan("[litestar-nuxt]"), colors.yellow("OpenAPI schema not found:"), typesConfig.openapiPath);
-        return false;
-      }
-      console.log(colors.cyan("[litestar-nuxt]"), colors.dim("Generating TypeScript types..."));
-      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: projectRoot
-      });
-      const routesPath = path.resolve(process.cwd(), typesConfig.routesPath);
-      if (fs.existsSync(routesPath)) {
-        await emitRouteTypes(routesPath, typesConfig.output);
-      }
-      const duration = Date.now() - startTime;
-      console.log(colors.cyan("[litestar-nuxt]"), colors.green("Types generated"), colors.dim(`in ${duration}ms`));
-      if (server) {
-        server.ws.send({
-          type: "custom",
-          event: "litestar:types-updated",
-          data: {
-            output: typesConfig.output,
-            timestamp: Date.now()
-          }
-        });
-      }
-      return true;
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      if (message.includes("not found") || message.includes("ENOENT")) {
-        console.log(colors.cyan("[litestar-nuxt]"), colors.yellow("@hey-api/openapi-ts not installed"), "- run:", resolveInstallHint());
-      } else {
-        console.error(colors.cyan("[litestar-nuxt]"), colors.red("Type generation failed:"), message);
-      }
-      return false;
-    } finally {
-      isGenerating = false;
-    }
-  }
-  const debouncedRunTypeGeneration = debounce(runTypeGeneration, typesConfig.debounce);
-  return {
-    name: "litestar-nuxt-types",
-    enforce: "pre",
-    configureServer(devServer) {
-      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;
-      }
-      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)) {
-        console.log(colors.cyan("[litestar-nuxt]"), colors.dim("Schema changed:"), colors.yellow(relativePath));
-        debouncedRunTypeGeneration();
-      }
-    }
-  };
-}
 function litestarPlugins(userConfig = {}) {
   const config = resolveConfig(userConfig);
   const plugins = [createProxyPlugin(config)];
   if (config.types !== false && config.types.enabled) {
-    plugins.push(createTypeGenerationPlugin(config.types, config.executor));
+    plugins.push(
+      createTypeGenerationPlugin(config.types, {
+        frameworkName: "litestar-nuxt",
+        pluginName: "litestar-nuxt-types",
+        clientPlugin: "@hey-api/client-nuxt",
+        executor: config.executor
+      })
+    );
   }
   return plugins;
 }

package/dist/js/shared/create-type-gen-plugin.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Shared type generation Vite plugin.
+ *
+ * Creates a Vite plugin that watches for OpenAPI schema and route metadata changes
+ * and regenerates TypeScript types using @hey-api/openapi-ts.
+ * Used by Astro, Nuxt, and SvelteKit integrations.
+ *
+ * @module
+ */
+import type { Plugin } from "vite";
+/**
+ * Base configuration for type generation.
+ */
+export interface BaseTypesConfig {
+    /**
+     * Enable type generation.
+     * @default false
+     */
+    enabled?: boolean;
+    /**
+     * Path to output generated TypeScript types.
+     */
+    output?: string;
+    /**
+     * Path where the OpenAPI schema is exported by Litestar.
+     * @default 'openapi.json'
+     */
+    openapiPath?: string;
+    /**
+     * Path where route metadata is exported by Litestar.
+     * @default 'routes.json'
+     */
+    routesPath?: string;
+    /**
+     * Generate Zod schemas in addition to TypeScript types.
+     * @default false
+     */
+    generateZod?: boolean;
+    /**
+     * Generate SDK client functions for API calls.
+     * @default true
+     */
+    generateSdk?: boolean;
+    /**
+     * Debounce time in milliseconds for type regeneration.
+     * @default 300
+     */
+    debounce?: number;
+}
+/**
+ * Required version of types config (all fields defined).
+ */
+export interface RequiredTypesConfig {
+    enabled: boolean;
+    output: string;
+    openapiPath: string;
+    routesPath: string;
+    generateZod: boolean;
+    generateSdk: boolean;
+    debounce: number;
+}
+/**
+ * Options for creating the type generation plugin.
+ */
+export interface TypeGenPluginOptions {
+    /**
+     * Framework name for logging (e.g., "litestar-astro", "litestar-nuxt").
+     */
+    frameworkName: string;
+    /**
+     * Vite plugin name.
+     */
+    pluginName: string;
+    /**
+     * The @hey-api client plugin to use when generating SDK.
+     * @default '@hey-api/client-fetch'
+     */
+    clientPlugin?: string;
+    /**
+     * Optional executor for running npx/bunx/pnpm dlx commands.
+     */
+    executor?: string;
+}
+/**
+ * Create a Vite plugin for type generation from OpenAPI schemas.
+ *
+ * @param typesConfig - The type generation configuration
+ * @param options - Plugin creation options
+ * @returns A Vite plugin that watches for schema changes and regenerates types
+ *
+ * @example
+ * ```typescript
+ * const plugin = createTypeGenerationPlugin(
+ *   { enabled: true, output: 'src/generated' },
+ *   { frameworkName: 'litestar-astro', pluginName: 'litestar-astro-types' }
+ * )
+ * ```
+ */
+export declare function createTypeGenerationPlugin(typesConfig: RequiredTypesConfig, options: TypeGenPluginOptions): Plugin;

package/dist/js/shared/create-type-gen-plugin.js

@@ -0,0 +1,110 @@
+import { exec } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { promisify } from "node:util";
+import colors from "picocolors";
+import { resolveInstallHint, resolvePackageExecutor } from "../install-hint.js";
+import { debounce } from "./debounce.js";
+import { emitRouteTypes } from "./emit-route-types.js";
+const execAsync = promisify(exec);
+function createTypeGenerationPlugin(typesConfig, options) {
+  const { frameworkName, pluginName, clientPlugin = "@hey-api/client-fetch", executor } = options;
+  let server = null;
+  let isGenerating = false;
+  async function runTypeGeneration() {
+    if (isGenerating) {
+      return false;
+    }
+    isGenerating = true;
+    const startTime = Date.now();
+    try {
+      const openapiPath = path.resolve(process.cwd(), typesConfig.openapiPath);
+      if (!fs.existsSync(openapiPath)) {
+        console.log(colors.cyan(`[${frameworkName}]`), colors.yellow("OpenAPI schema not found:"), typesConfig.openapiPath);
+        return false;
+      }
+      console.log(colors.cyan(`[${frameworkName}]`), colors.dim("Generating TypeScript types..."));
+      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(`[${frameworkName}]`), 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", clientPlugin);
+        }
+        if (typesConfig.generateZod) {
+          plugins.push("zod");
+        }
+        if (plugins.length) {
+          args.push("--plugins", ...plugins);
+        }
+      }
+      const command = executor ? resolvePackageExecutor(args.join(" "), executor) : `npx ${args.join(" ")}`;
+      await execAsync(command, { cwd: projectRoot });
+      const routesPath = path.resolve(process.cwd(), typesConfig.routesPath);
+      if (fs.existsSync(routesPath)) {
+        await emitRouteTypes(routesPath, typesConfig.output, { declareGlobalVars: true });
+      }
+      const duration = Date.now() - startTime;
+      console.log(colors.cyan(`[${frameworkName}]`), colors.green("Types generated"), colors.dim(`in ${duration}ms`));
+      if (server) {
+        server.ws.send({
+          type: "custom",
+          event: "litestar:types-updated",
+          data: {
+            output: typesConfig.output,
+            timestamp: Date.now()
+          }
+        });
+      }
+      return true;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (message.includes("not found") || message.includes("ENOENT")) {
+        console.log(colors.cyan(`[${frameworkName}]`), colors.yellow("@hey-api/openapi-ts not installed"), "- run:", resolveInstallHint());
+      } else {
+        console.error(colors.cyan(`[${frameworkName}]`), colors.red("Type generation failed:"), message);
+      }
+      return false;
+    } finally {
+      isGenerating = false;
+    }
+  }
+  const debouncedRunTypeGeneration = debounce(runTypeGeneration, typesConfig.debounce);
+  return {
+    name: pluginName,
+    enforce: "pre",
+    configureServer(devServer) {
+      server = devServer;
+      console.log(colors.cyan(`[${frameworkName}]`), 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;
+      }
+      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)) {
+        console.log(colors.cyan(`[${frameworkName}]`), colors.dim("Schema changed:"), colors.yellow(relativePath));
+        debouncedRunTypeGeneration();
+      }
+    }
+  };
+}
+export {
+  createTypeGenerationPlugin
+};

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

@@ -0,0 +1,41 @@
+/**
+ * Shared route type generation utility.
+ *
+ * Generates TypeScript types from routes.json metadata for type-safe routing.
+ * Used by the main litestar plugin and framework integrations (Astro, Nuxt, SvelteKit).
+ *
+ * @module
+ */
+/**
+ * Options for emitRouteTypes.
+ */
+export interface EmitRouteTypesOptions {
+    /**
+     * Whether to register route() on window for global access.
+     * Only used by the main plugin.
+     * @default false
+     */
+    globalRoute?: boolean;
+    /**
+     * Whether to declare global `var routes` and `var serverRoutes`.
+     * Used by framework integrations for SSR compatibility.
+     * @default false
+     */
+    declareGlobalVars?: boolean;
+}
+/**
+ * Generate TypeScript route types from routes.json metadata.
+ *
+ * Creates a routes.ts file with:
+ * - routesMeta: full route metadata
+ * - routes: name -> uri map
+ * - serverRoutes: alias of routes
+ * - route(): type-safe URL generator
+ * - hasRoute(): type guard
+ * - CSRF helpers re-exported from litestar-vite-plugin/helpers
+ *
+ * @param routesPath - Path to routes.json file
+ * @param outputDir - Output directory for routes.ts
+ * @param options - Generation options
+ */
+export declare function emitRouteTypes(routesPath: string, outputDir: string, options?: EmitRouteTypesOptions): Promise<void>;

package/dist/js/shared/emit-route-types.js

@@ -0,0 +1,151 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+async function emitRouteTypes(routesPath, outputDir, options = {}) {
+  const { globalRoute = false, declareGlobalVars = false } = options;
+  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)) {
+    if (data.parameters && data.parameters.length > 0) {
+      const params = data.parameters.map((p) => `${p}: string | number`).join("; ");
+      routeParamTypes.push(`  "${name}": { ${params} }`);
+    } else {
+      routeParamTypes.push(`  "${name}": Record<string, never>`);
+    }
+  }
+  let globalDeclarations = `declare global {
+  interface Window {
+    /**
+     * Fully-typed route metadata injected by Litestar.
+     */
+    __LITESTAR_ROUTES__?: typeof routesMeta
+    /**
+     * Simple route map (name -> uri) for legacy consumers.
+     */
+    routes?: ${declareGlobalVars ? "typeof routes" : "Record<string, string>"}
+    serverRoutes?: ${declareGlobalVars ? "typeof serverRoutes" : "Record<string, string>"}`;
+  if (globalRoute) {
+    globalDeclarations += `
+    /**
+     * Global route helper (available when globalRoute=true in TypeGenConfig).
+     * @see route
+     */
+    route?: typeof route`;
+  }
+  globalDeclarations += `
+  }`;
+  if (declareGlobalVars) {
+    globalDeclarations += `
+  // eslint-disable-next-line no-var
+  var routes: typeof routes | undefined
+  var serverRoutes: typeof serverRoutes | undefined`;
+  }
+  globalDeclarations += `
+}`;
+  const globalRouteRegistration = globalRoute ? `
+
+// Register route() globally on window for Laravel/Ziggy-style usage
+if (typeof window !== "undefined") {
+  window.route = route
+}
+` : "";
+  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
+}
+
+${globalDeclarations}
+
+// Re-export helper functions from litestar-vite-plugin
+// These work with the routes defined above
+export { getCsrfToken, csrfHeaders, csrfFetch } from "litestar-vite-plugin/helpers"
+${globalRouteRegistration}`;
+  await fs.promises.writeFile(outFile, `${banner}${body}`, "utf-8");
+}
+export {
+  emitRouteTypes
+};