litestar-vite-plugin 0.14.0 → 0.15.0-alpha.1

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

@@ -0,0 +1,47 @@
+/**
+ * Inertia.js helpers for Litestar applications.
+ *
+ * This module re-exports common helpers from litestar-vite-plugin/helpers
+ * and adds Inertia-specific utilities.
+ *
+ * @module
+ */
+// Re-export all helpers from the main helpers module
+export { 
+// CSRF utilities
+getCsrfToken, csrfHeaders, csrfFetch, 
+// Route utilities
+route, getRoutes, toRoute, currentRoute, isRoute, isCurrentRoute, getRelativeUrlPath, } from "../helpers/index.js";
+/**
+ * Resolve a page component from a glob import.
+ *
+ * Used with Inertia.js to dynamically import page components.
+ *
+ * @param path - Component path or array of paths to try
+ * @param pages - Glob import result (e.g., import.meta.glob('./pages/**\/*.vue'))
+ * @returns Promise resolving to the component
+ * @throws Error if no matching component is found
+ *
+ * @example
+ * ```ts
+ * import { resolvePageComponent } from 'litestar-vite-plugin/inertia-helpers'
+ *
+ * createInertiaApp({
+ *   resolve: (name) => resolvePageComponent(
+ *     `./pages/${name}.vue`,
+ *     import.meta.glob('./pages/**\/*.vue')
+ *   ),
+ *   // ...
+ * })
+ * ```
+ */
+export async function resolvePageComponent(path, pages) {
+    for (const p of Array.isArray(path) ? path : [path]) {
+        const page = pages[p];
+        if (typeof page === "undefined") {
+            continue;
+        }
+        return typeof page === "function" ? page() : page;
+    }
+    throw new Error(`Page not found: ${path}`);
+}

package/dist/js/install-hint.d.ts

@@ -0,0 +1 @@
+export declare function resolveInstallHint(pkg?: string): string;

package/dist/js/install-hint.js

@@ -0,0 +1,21 @@
+function resolveInstallHint(pkg = "@hey-api/openapi-ts") {
+  const runtime = (process.env.LITESTAR_VITE_RUNTIME ?? "").toLowerCase();
+  switch (runtime) {
+    case "bun":
+      return `bun add -d ${pkg}`;
+    case "deno":
+      return `deno add -d npm:${pkg}`;
+    case "pnpm":
+      return `pnpm add -D ${pkg}`;
+    case "yarn":
+      return `yarn add -D ${pkg}`;
+  }
+  const envInstall = process.env.LITESTAR_VITE_INSTALL_CMD?.trim();
+  if (envInstall) {
+    return `${envInstall} -D ${pkg}`;
+  }
+  return `npm install -D ${pkg}`;
+}
+export {
+  resolveInstallHint
+};

package/dist/js/litestar-meta.d.ts

@@ -0,0 +1,18 @@
+import type { ResolvedConfig } from "vite";
+export interface LitestarMeta {
+    litestarVersion?: string;
+}
+export interface BackendStatus {
+    available: boolean;
+    url?: string;
+    error?: string;
+}
+/**
+ * Check if the Litestar backend is reachable at the given URL.
+ *
+ * Uses a GET request to the OpenAPI schema endpoint as a lightweight
+ * health check, since it's typically enabled and responds quickly.
+ * The schema path is read from LITESTAR_OPENAPI_PATH env var (default: "/schema").
+ */
+export declare function checkBackendAvailability(appUrl: string): Promise<BackendStatus>;
+export declare function loadLitestarMeta(resolvedConfig: ResolvedConfig, routesPathHint?: string): Promise<LitestarMeta>;

package/dist/js/litestar-meta.js

@@ -0,0 +1,84 @@
+import fs from "node:fs";
+import path from "node:path";
+async function checkBackendAvailability(appUrl) {
+  if (!appUrl || appUrl === "undefined") {
+    return {
+      available: false,
+      error: "APP_URL not configured"
+    };
+  }
+  try {
+    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 response = await fetch(checkUrl, {
+      method: "GET",
+      signal: controller.signal
+    });
+    clearTimeout(timeout);
+    return {
+      available: response.ok || response.status < 500,
+      url: appUrl
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (message.includes("ECONNREFUSED") || message.includes("fetch failed")) {
+      return {
+        available: false,
+        url: appUrl,
+        error: "Backend not reachable (is Litestar running?)"
+      };
+    }
+    if (message.includes("aborted")) {
+      return {
+        available: false,
+        url: appUrl,
+        error: "Backend connection timeout"
+      };
+    }
+    return {
+      available: false,
+      url: appUrl,
+      error: message
+    };
+  }
+}
+function readJson(file) {
+  try {
+    const raw = fs.readFileSync(file, "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+function firstExisting(paths) {
+  for (const p of paths) {
+    if (fs.existsSync(p)) return p;
+  }
+  return null;
+}
+async function loadLitestarMeta(resolvedConfig, routesPathHint) {
+  const fromEnv = process.env.LITESTAR_VERSION?.trim();
+  if (fromEnv) {
+    return { litestarVersion: fromEnv };
+  }
+  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
+  );
+  const match = firstExisting(candidates);
+  if (!match) return {};
+  const data = readJson(match);
+  if (!data) return {};
+  const fromData = (key) => {
+    const value = data[key];
+    return typeof value === "string" ? value : null;
+  };
+  const litestarVersion = fromData("litestar_version") ?? fromData("litestarVersion") ?? fromData("version");
+  return litestarVersion ? { litestarVersion } : {};
+}
+export {
+  checkBackendAvailability,
+  loadLitestarMeta
+};

package/dist/js/nuxt.d.ts

@@ -0,0 +1,193 @@
+/**
+ * Nuxt module for Litestar-Vite.
+ *
+ * This module provides seamless integration between Nuxt 3+ and Litestar backend.
+ * It enables:
+ * - API proxy configuration for dev server
+ * - Type generation integration (shares @hey-api/openapi-ts output)
+ * - Server-side and client-side API access patterns
+ *
+ * @example
+ * ```typescript
+ * // nuxt.config.ts
+ * export default defineNuxtConfig({
+ *   modules: ['litestar-vite-plugin/nuxt'],
+ *   litestar: {
+ *     apiProxy: 'http://localhost:8000',
+ *     apiPrefix: '/api',
+ *     types: {
+ *       enabled: true,
+ *       output: 'types/api',
+ *     },
+ *   },
+ * });
+ * ```
+ *
+ * @module
+ */
+import type { Plugin } from "vite";
+/**
+ * Configuration for TypeScript type generation in Nuxt.
+ */
+export interface NuxtTypesConfig {
+    /**
+     * Enable type generation.
+     *
+     * @default false
+     */
+    enabled?: boolean;
+    /**
+     * Path to output generated TypeScript types.
+     * Relative to the Nuxt project root.
+     *
+     * @default 'types/api'
+     */
+    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;
+    /**
+     * Debounce time in milliseconds for type regeneration.
+     *
+     * @default 300
+     */
+    debounce?: number;
+}
+/**
+ * Configuration options for the Litestar Nuxt module.
+ */
+export interface LitestarNuxtConfig {
+    /**
+     * URL of the Litestar API backend for proxying requests during development.
+     *
+     * @example 'http://localhost:8000'
+     * @default 'http://localhost:8000'
+     */
+    apiProxy?: string;
+    /**
+     * API route prefix to proxy to the Litestar backend.
+     * Requests matching this prefix will be forwarded to the apiProxy URL.
+     *
+     * @example '/api'
+     * @default '/api'
+     */
+    apiPrefix?: string;
+    /**
+     * Enable and configure TypeScript type generation.
+     *
+     * When set to `true`, enables type generation with default settings.
+     * When set to a NuxtTypesConfig object, enables type generation with custom settings.
+     *
+     * @default false
+     */
+    types?: boolean | NuxtTypesConfig;
+    /**
+     * Enable verbose logging for debugging.
+     *
+     * @default false
+     */
+    verbose?: boolean;
+}
+/**
+ * Litestar Vite plugins for Nuxt.
+ *
+ * This function returns an array of Vite plugins that can be added to Nuxt's
+ * vite configuration. For the full Nuxt module experience, use the module
+ * directly in your nuxt.config.ts.
+ *
+ * @param userConfig - Configuration options
+ * @returns Array of Vite plugins
+ *
+ * @example Using as Vite plugins in nuxt.config.ts
+ * ```typescript
+ * import { litestarPlugins } from 'litestar-vite-plugin/nuxt';
+ *
+ * export default defineNuxtConfig({
+ *   vite: {
+ *     plugins: [
+ *       ...litestarPlugins({
+ *         apiProxy: 'http://localhost:8000',
+ *         types: true,
+ *       }),
+ *     ],
+ *   },
+ * });
+ * ```
+ */
+export declare function litestarPlugins(userConfig?: LitestarNuxtConfig): Plugin[];
+/**
+ * Nuxt module definition for Litestar integration.
+ *
+ * This is a minimal module interface that can be used with Nuxt's module system.
+ * For full type safety, install @nuxt/kit as a dev dependency.
+ *
+ * @example
+ * ```typescript
+ * // nuxt.config.ts
+ * export default defineNuxtConfig({
+ *   modules: ['litestar-vite-plugin/nuxt'],
+ *   litestar: {
+ *     apiProxy: 'http://localhost:8000',
+ *     apiPrefix: '/api',
+ *     types: {
+ *       enabled: true,
+ *       output: 'types/api',
+ *     },
+ *   },
+ * });
+ * ```
+ *
+ * @example Using generated types in a composable
+ * ```typescript
+ * // composables/useApi.ts
+ * import type { User } from '~/types/api/types.gen';
+ * import { route } from '~/types/api/routes';
+ *
+ * export async function useUser(id: string) {
+ *   const { data } = await useFetch<User>(route('users.show', { id }));
+ *   return data;
+ * }
+ * ```
+ */
+export declare const litestarModule: {
+    meta: {
+        name: string;
+        configKey: string;
+        compatibility: {
+            nuxt: string;
+        };
+    };
+    defaults: {
+        apiProxy: string;
+        apiPrefix: string;
+        types: false;
+        verbose: false;
+    };
+    /**
+     * Setup function for the Nuxt module.
+     * This is called by Nuxt when the module is loaded.
+     */
+    setup(userOptions: LitestarNuxtConfig, nuxt: {
+        options: {
+            vite: {
+                plugins?: Plugin[];
+            };
+        };
+    }): void;
+};
+export default litestarModule;

package/dist/js/nuxt.js

@@ -0,0 +1,197 @@
+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 } from "./install-hint.js";
+const execAsync = promisify(exec);
+function resolveConfig(config = {}) {
+  let typesConfig = false;
+  if (config.types === true) {
+    typesConfig = {
+      enabled: true,
+      output: "types/api",
+      openapiPath: "openapi.json",
+      routesPath: "routes.json",
+      generateZod: false,
+      debounce: 300
+    };
+  } else if (typeof config.types === "object" && config.types !== null) {
+    typesConfig = {
+      enabled: config.types.enabled ?? true,
+      output: config.types.output ?? "types/api",
+      openapiPath: config.types.openapiPath ?? "openapi.json",
+      routesPath: config.types.routesPath ?? "routes.json",
+      generateZod: config.types.generateZod ?? false,
+      debounce: config.types.debounce ?? 300
+    };
+  }
+  return {
+    apiProxy: config.apiProxy ?? "http://localhost:8000",
+    apiPrefix: config.apiPrefix ?? "/api",
+    types: typesConfig,
+    verbose: config.verbose ?? false
+  };
+}
+function debounce(func, wait) {
+  let timeout = null;
+  return (...args) => {
+    if (timeout) {
+      clearTimeout(timeout);
+    }
+    timeout = setTimeout(() => func(...args), wait);
+  };
+}
+function createProxyPlugin(config) {
+  return {
+    name: "litestar-nuxt-proxy",
+    config() {
+      return {
+        server: {
+          proxy: {
+            [config.apiPrefix]: {
+              target: config.apiProxy,
+              changeOrigin: true,
+              secure: false
+            }
+          }
+        }
+      };
+    },
+    configureServer(server) {
+      if (config.verbose) {
+        server.middlewares.use((req, _res, next) => {
+          if (req.url?.startsWith(config.apiPrefix)) {
+            console.log(colors.cyan("[litestar-nuxt]"), `Proxying: ${req.method} ${req.url}`);
+          }
+          next();
+        });
+      }
+      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)}`);
+          if (config.types !== false && config.types.enabled) {
+            console.log(`  ${colors.dim("\u2514\u2500")} Types Output: ${colors.yellow(config.types.output)}`);
+          } else {
+            console.log(`  ${colors.dim("\u2514\u2500")} Types: ${colors.dim("disabled")}`);
+          }
+          console.log("");
+        }, 100);
+      });
+    }
+  };
+}
+function createTypeGenerationPlugin(typesConfig) {
+  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 args = ["@hey-api/openapi-ts", "-i", typesConfig.openapiPath, "-o", typesConfig.output];
+      if (typesConfig.generateZod) {
+        args.push("--plugins", "@hey-api/schemas", "@hey-api/types");
+      }
+      await execAsync(`npx ${args.join(" ")}`, {
+        cwd: process.cwd()
+      });
+      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));
+    },
+    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));
+  }
+  return plugins;
+}
+const litestarModule = {
+  meta: {
+    name: "litestar-vite",
+    configKey: "litestar",
+    compatibility: {
+      nuxt: ">=3.0.0"
+    }
+  },
+  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");
+  }
+};
+var nuxt_default = litestarModule;
+export {
+  nuxt_default as default,
+  litestarModule,
+  litestarPlugins
+};