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

package/dist/js/nuxt.js

@@ -3,9 +3,46 @@ import fs from "node:fs";
 import path from "node:path";
 import { promisify } from "node:util";
 import colors from "picocolors";
-import { resolveInstallHint } from "./install-hint.js";
+import { resolveInstallHint, resolvePackageExecutor } from "./install-hint.js";
+import { debounce } from "./shared/debounce.js";
 const execAsync = promisify(exec);
+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 = {}) {
+  const runtimeConfigPath = process.env.LITESTAR_VITE_CONFIG_PATH;
+  let hotFile;
+  let proxyMode = "vite";
+  let devPort;
+  const envPort = process.env.VITE_PORT;
+  if (envPort) {
+    devPort = Number.parseInt(envPort, 10);
+    if (Number.isNaN(devPort)) {
+      devPort = void 0;
+    }
+  }
+  let pythonExecutor;
+  if (runtimeConfigPath && fs.existsSync(runtimeConfigPath)) {
+    try {
+      const json = JSON.parse(fs.readFileSync(runtimeConfigPath, "utf-8"));
+      const bundleDir = json.bundleDir ?? "public";
+      const hot = json.hotFile ?? "hot";
+      hotFile = path.resolve(process.cwd(), bundleDir, hot);
+      proxyMode = json.proxyMode ?? "vite";
+      if (json.port !== void 0) {
+        devPort = json.port;
+      }
+      pythonExecutor = json.executor;
+    } catch {
+      hotFile = void 0;
+    }
+  }
   let typesConfig = false;
   if (config.types === true) {
     typesConfig = {
@@ -30,30 +67,40 @@ function resolveConfig(config = {}) {
     apiProxy: config.apiProxy ?? "http://localhost:8000",
     apiPrefix: config.apiPrefix ?? "/api",
     types: typesConfig,
-    verbose: config.verbose ?? false
+    verbose: config.verbose ?? false,
+    hotFile,
+    proxyMode,
+    devPort,
+    executor: config.executor ?? pythonExecutor
   };
 }
-function debounce(func, wait) {
-  let timeout = null;
-  return (...args) => {
-    if (timeout) {
-      clearTimeout(timeout);
-    }
-    timeout = setTimeout(() => func(...args), wait);
-  };
+async function getPort() {
+  return new Promise((resolve, reject) => {
+    import("node:net").then(({ createServer }) => {
+      const server = createServer();
+      server.unref();
+      server.on("error", reject);
+      server.listen(0, () => {
+        const address = server.address();
+        const port = typeof address === "object" && address ? address.port : 0;
+        server.close(() => resolve(port));
+      });
+    });
+  });
 }
 function createProxyPlugin(config) {
+  let hmrPort = 0;
   return {
     name: "litestar-nuxt-proxy",
-    config() {
+    async config() {
+      hmrPort = await getPort();
       return {
         server: {
-          proxy: {
-            [config.apiPrefix]: {
-              target: config.apiProxy,
-              changeOrigin: true,
-              secure: false
-            }
+          // Avoid HMR port collisions by letting Vite pick a free port for WS
+          hmr: {
+            port: hmrPort,
+            host: "127.0.0.1",
+            clientPort: config.devPort
           }
         }
       };
@@ -67,12 +114,21 @@ function createProxyPlugin(config) {
           next();
         });
       }
+      if (config.hotFile) {
+        const hmrHotFile = `${config.hotFile}.hmr`;
+        const hmrUrl = `http://127.0.0.1:${hmrPort}`;
+        fs.writeFileSync(hmrHotFile, hmrUrl);
+        if (config.verbose) {
+          console.log(colors.cyan("[litestar-nuxt]"), colors.dim(`HMR Hotfile written: ${hmrHotFile} -> ${hmrUrl}`));
+        }
+      }
       server.httpServer?.once("listening", () => {
         setTimeout(() => {
           console.log("");
           console.log(`  ${colors.cyan("[litestar-nuxt]")} ${colors.green("Integration active")}`);
           console.log(`  ${colors.dim("\u251C\u2500")} API Proxy: ${colors.yellow(config.apiProxy)}`);
           console.log(`  ${colors.dim("\u251C\u2500")} API Prefix: ${colors.yellow(config.apiPrefix)}`);
+          console.log(`  ${colors.dim("\u251C\u2500")} HMR Port: ${colors.yellow(hmrPort)}`);
           if (config.types !== false && config.types.enabled) {
             console.log(`  ${colors.dim("\u2514\u2500")} Types Output: ${colors.yellow(config.types.output)}`);
           } else {
@@ -84,7 +140,132 @@ function createProxyPlugin(config) {
     }
   };
 }
-function createTypeGenerationPlugin(typesConfig) {
+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() {
@@ -102,11 +283,15 @@ function createTypeGenerationPlugin(typesConfig) {
       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", "@hey-api/schemas", "@hey-api/types");
+        args.push("--plugins", "zod", "@hey-api/typescript");
       }
-      await execAsync(`npx ${args.join(" ")}`, {
+      await execAsync(resolvePackageExecutor(args.join(" "), executor), {
         cwd: process.cwd()
       });
+      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) {
@@ -158,37 +343,76 @@ function litestarPlugins(userConfig = {}) {
   const config = resolveConfig(userConfig);
   const plugins = [createProxyPlugin(config)];
   if (config.types !== false && config.types.enabled) {
-    plugins.push(createTypeGenerationPlugin(config.types));
+    plugins.push(createTypeGenerationPlugin(config.types, config.executor));
   }
   return plugins;
 }
-const litestarModule = {
-  meta: {
-    name: "litestar-vite",
-    configKey: "litestar",
-    compatibility: {
-      nuxt: ">=3.0.0"
+function litestarNuxtModule(userOptions, nuxt) {
+  const nuxtConfigOptions = nuxt.options.litestar;
+  const mergedOptions = { ...nuxtConfigOptions, ...userOptions };
+  const config = resolveConfig(mergedOptions);
+  const plugins = litestarPlugins(config);
+  nuxt.options.vite = nuxt.options.vite || {};
+  nuxt.options.vite.plugins = nuxt.options.vite.plugins || [];
+  nuxt.options.vite.plugins.push(...plugins);
+  nuxt.options.runtimeConfig = nuxt.options.runtimeConfig || {};
+  nuxt.options.runtimeConfig.public = nuxt.options.runtimeConfig.public || {};
+  nuxt.options.runtimeConfig.public.apiProxy = config.apiProxy;
+  nuxt.options.runtimeConfig.public.apiPrefix = config.apiPrefix;
+  nuxt.options.nitro = nuxt.options.nitro || {};
+  nuxt.options.nitro.devProxy = nuxt.options.nitro.devProxy || {};
+  nuxt.options.nitro.devProxy[config.apiPrefix] = {
+    target: config.apiProxy,
+    changeOrigin: true,
+    ws: true
+  };
+  if (config.verbose) {
+    console.log(colors.cyan("[litestar-nuxt]"), "Runtime config:");
+    console.log(`  apiProxy: ${config.apiProxy}`);
+    console.log(`  apiPrefix: ${config.apiPrefix}`);
+    console.log(`  verbose: ${config.verbose}`);
+    console.log(colors.cyan("[litestar-nuxt]"), "Nitro devProxy configured:");
+    console.log(JSON.stringify(nuxt.options.nitro.devProxy, null, 2));
+  }
+  if (config.hotFile && config.devPort) {
+    const rawHost = process.env.NUXT_HOST || process.env.HOST || "localhost";
+    const host = normalizeHost(rawHost);
+    const url = `http://${host}:${config.devPort}`;
+    fs.mkdirSync(path.dirname(config.hotFile), { recursive: true });
+    fs.writeFileSync(config.hotFile, url);
+    if (config.verbose) {
+      console.log(colors.cyan("[litestar-nuxt]"), colors.dim(`Hotfile written: ${config.hotFile} -> ${url}`));
     }
-  },
-  defaults: {
-    apiProxy: "http://localhost:8000",
-    apiPrefix: "/api",
-    types: false,
-    verbose: false
-  },
-  /**
-   * Setup function for the Nuxt module.
-   * This is called by Nuxt when the module is loaded.
-   */
-  setup(userOptions, nuxt) {
-    const config = resolveConfig(userOptions);
-    const plugins = litestarPlugins(config);
-    nuxt.options.vite = nuxt.options.vite || {};
-    nuxt.options.vite.plugins = nuxt.options.vite.plugins || [];
-    nuxt.options.vite.plugins.push(...plugins);
-    console.log(colors.cyan("[litestar-nuxt]"), "Module initialized");
+  }
+  if (nuxt.hook && config.hotFile) {
+    nuxt.hook("listen", (_server, listener) => {
+      const info = listener;
+      if (info && typeof info.port === "number") {
+        const host = normalizeHost(info.host || "localhost");
+        const url = `http://${host}:${info.port}`;
+        fs.writeFileSync(config.hotFile, url);
+        if (config.verbose) {
+          console.log(colors.cyan("[litestar-nuxt]"), colors.dim(`Hotfile updated via listen hook: ${url}`));
+        }
+      }
+    });
+  }
+  console.log(colors.cyan("[litestar-nuxt]"), "Module initialized");
+}
+litestarNuxtModule.meta = {
+  name: "litestar-vite",
+  configKey: "litestar",
+  compatibility: {
+    nuxt: ">=3.0.0"
   }
 };
+litestarNuxtModule.getOptions = () => ({
+  apiProxy: "http://localhost:8000",
+  apiPrefix: "/api",
+  types: false,
+  verbose: false
+});
+const litestarModule = litestarNuxtModule;
 var nuxt_default = litestarModule;
 export {
   nuxt_default as default,

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

@@ -0,0 +1,27 @@
+/**
+ * Shared debounce utility for litestar-vite.
+ *
+ * @module
+ */
+/**
+ * Creates a debounced function that delays invoking `func` until after
+ * `wait` milliseconds have elapsed since the last invocation.
+ *
+ * This implementation is type-safe and properly infers argument types.
+ *
+ * @param func - The function to debounce
+ * @param wait - Milliseconds to wait before invoking
+ * @returns Debounced function with the same signature
+ *
+ * @example
+ * ```ts
+ * const debouncedSave = debounce((data: string) => {
+ *   console.log('Saving:', data)
+ * }, 300)
+ *
+ * debouncedSave('hello') // Delayed
+ * debouncedSave('world') // Cancels previous, delays again
+ * // Only 'world' is logged after 300ms
+ * ```
+ */
+export declare function debounce<Args extends unknown[]>(func: (...args: Args) => void, wait: number): (...args: Args) => void;

package/dist/js/shared/debounce.js

@@ -0,0 +1,15 @@
+function debounce(func, wait) {
+  let timeout = null;
+  return (...args) => {
+    if (timeout !== null) {
+      clearTimeout(timeout);
+    }
+    timeout = setTimeout(() => {
+      func(...args);
+      timeout = null;
+    }, wait);
+  };
+}
+export {
+  debounce
+};

package/dist/js/sveltekit.d.ts

@@ -107,6 +107,13 @@ export interface LitestarSvelteKitConfig {
      * @default false
      */
     verbose?: boolean;
+    /**
+     * JavaScript runtime executor for package commands.
+     * Used when running tools like @hey-api/openapi-ts.
+     *
+     * @default undefined (uses LITESTAR_VITE_RUNTIME env or 'node')
+     */
+    executor?: "node" | "bun" | "deno" | "yarn" | "pnpm";
 }
 /**
  * Litestar integration plugin for SvelteKit.