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

package/README.md

@@ -38,6 +38,23 @@ litestar run --reload  # Vite dev server is proxied automatically
 
 Scaffold a frontend: `litestar assets init --template vue` (or `react`, `svelte`, `htmx`, `react-inertia`, `vue-inertia`, `angular`, `astro`, `nuxt`, `sveltekit`).
 
+## Development
+
+To contribute or run the development project:
+
+```bash
+# Install all dependencies and build packages
+make install && make build
+
+# Install frontend dependencies for an example
+uv run litestar --app-dir examples/vue-inertia assets install
+
+# Run the development server
+uv run litestar --app-dir examples/vue-inertia run
+```
+
+Replace `vue-inertia` with any other example: `vue`, `react`, `svelte`, `react-inertia`, `htmx`, `angular`, `astro`, `nuxt`, or `sveltekit`.
+
 ## Template / HTMX
 
 ```python
@@ -166,4 +183,5 @@ litestar assets generate-types  # one-off or CI
 
 - Docs: <https://litestar-org.github.io/litestar-vite/>
 - Examples: `examples/` (react, vue, svelte, react-inertia, vue-inertia, astro, nuxt, sveltekit, htmx)
+- Real-world example: [litestar-fullstack](https://github.com/litestar-org/litestar-fullstack) - Full-featured application using litestar-vite
 - Issues: <https://github.com/litestar-org/litestar-vite/issues/>

package/dist/js/astro.js

@@ -1,11 +1,6 @@
-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";
-import { debounce } from "./shared/debounce.js";
-const execAsync = promisify(exec);
+import { createTypeGenerationPlugin } from "./shared/create-type-gen-plugin.js";
 function resolveConfig(config = {}) {
   const runtimeConfigPath = process.env.LITESTAR_VITE_CONFIG_PATH;
   let hotFile;
@@ -91,229 +86,6 @@ 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) {
-  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-astro]"), colors.yellow("OpenAPI schema not found:"), typesConfig.openapiPath);
-        return false;
-      }
-      console.log(colors.cyan("[litestar-astro]"), 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-astro]"), 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-fetch");
-        }
-        if (typesConfig.generateZod) {
-          plugins.push("zod");
-        }
-        if (plugins.length) {
-          args.push("--plugins", ...plugins);
-        }
-      }
-      await execAsync(`npx ${args.join(" ")}`, {
-        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-astro]"), 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-astro]"), colors.yellow("@hey-api/openapi-ts not installed"), "- run:", resolveInstallHint());
-      } else {
-        console.error(colors.cyan("[litestar-astro]"), colors.red("Type generation failed:"), message);
-      }
-      return false;
-    } finally {
-      isGenerating = false;
-    }
-  }
-  const debouncedRunTypeGeneration = debounce(runTypeGeneration, typesConfig.debounce);
-  return {
-    name: "litestar-astro-types",
-    enforce: "pre",
-    configureServer(devServer) {
-      server = devServer;
-      console.log(colors.cyan("[litestar-astro]"), 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-astro]"), colors.dim("Schema changed:"), colors.yellow(relativePath));
-        debouncedRunTypeGeneration();
-      }
-    }
-  };
-}
 function litestarAstro(userConfig = {}) {
   const config = resolveConfig(userConfig);
   return {
@@ -333,7 +105,13 @@ function litestarAstro(userConfig = {}) {
         }
         const plugins = [createProxyPlugin(config)];
         if (config.types !== false && config.types.enabled) {
-          plugins.push(createTypeGenerationPlugin(config.types));
+          plugins.push(
+            createTypeGenerationPlugin(config.types, {
+              frameworkName: "litestar-astro",
+              pluginName: "litestar-astro-types",
+              clientPlugin: "@hey-api/client-fetch"
+            })
+          );
         }
         const configUpdate = {
           vite: {

package/dist/js/helpers/htmx.d.ts

@@ -63,6 +63,11 @@ interface Dir {
     match: (a: Attr) => boolean;
     create: (el: Element, a: Attr) => Handler | null;
 }
-export declare function setDebug(_on: boolean): void;
+/**
+ * Enable or disable debug logging for the HTMX extension.
+ *
+ * @param on - Whether to enable debug logging.
+ */
+export declare function setDebug(on: boolean): void;
 export declare function addDirective(dir: Dir): void;
 export {};

package/dist/js/helpers/htmx.js

@@ -28,7 +28,7 @@
  * @module
  */
 import { getCsrfToken } from "./csrf.js";
-const DEBUG = typeof process !== "undefined" && process.env?.NODE_ENV !== "production";
+let debug = typeof process !== "undefined" && process.env?.NODE_ENV !== "production";
 const cache = new Map();
 const memoStore = new WeakMap();
 // =============================================================================
@@ -68,7 +68,7 @@ export function registerHtmxExtension() {
             return [];
         },
     });
-    if (DEBUG)
+    if (debug)
         console.log("[litestar] htmx extension registered");
 }
 // =============================================================================
@@ -483,8 +483,13 @@ function removeBetween(start, end) {
 // =============================================================================
 // Public API
 // =============================================================================
-export function setDebug(_on) {
-    // Debug flag is const, this is a no-op placeholder
+/**
+ * Enable or disable debug logging for the HTMX extension.
+ *
+ * @param on - Whether to enable debug logging.
+ */
+export function setDebug(on) {
+    debug = on;
 }
 export function addDirective(dir) {
     directives.push(dir);

package/dist/js/index.d.ts

@@ -260,7 +260,6 @@ export interface BridgeSchema {
     litestarVersion: string;
 }
 type DevServerUrl = `${"http" | "https"}://${string}:${number}`;
-export declare const refreshPaths: string[];
 /**
  * Litestar plugin for Vite.
  *

package/dist/js/index.js

@@ -1,5 +1,4 @@
 import { exec } from "node:child_process";
-import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -10,6 +9,7 @@ import fullReload from "vite-plugin-full-reload";
 import { resolveInstallHint, resolvePackageExecutor } from "./install-hint.js";
 import { checkBackendAvailability, loadLitestarMeta } from "./litestar-meta.js";
 import { debounce } from "./shared/debounce.js";
+import { emitRouteTypes } from "./shared/emit-route-types.js";
 import { formatPath } from "./shared/format-path.js";
 import { createLogger } from "./shared/logger.js";
 const execAsync = promisify(exec);
@@ -367,13 +367,6 @@ function ensureCommandShouldRunInEnvironment(command, env, mode) {
     );
   }
 }
-function _pluginVersion() {
-  try {
-    return JSON.parse(fs.readFileSync(path.join(dirname(), "../package.json")).toString())?.version;
-  } catch {
-    return "";
-  }
-}
 function loadPythonDefaults() {
   const isTestEnv = Boolean(process.env.VITEST || process.env.VITE_TEST || process.env.NODE_ENV === "test");
   let configPath = process.env.LITESTAR_VITE_CONFIG_PATH;
@@ -587,11 +580,15 @@ function resolveInput(config, ssr) {
   }
   return config.input;
 }
+function isAbsolutePath(path2) {
+  return path2.startsWith("/") || /^[a-zA-Z]:[\\/]/.test(path2);
+}
 function resolveOutDir(config, ssr) {
-  if (ssr) {
-    return config.ssrOutDir.replace(/^\/+/, "").replace(/\/+$/, "");
+  const dir = ssr ? config.ssrOutDir : config.bundleDir;
+  if (isAbsolutePath(dir)) {
+    return dir.replace(/[\\/]+$/, "");
   }
-  return config.bundleDir.replace(/^\/+/, "").replace(/\/+$/, "");
+  return dir.replace(/^\/+/, "").replace(/\/+$/, "");
 }
 function resolveFullReloadConfig({ refresh: config }) {
   if (typeof config === "boolean") {
@@ -760,139 +757,6 @@ declare module "litestar-vite/inertia" {
 `;
   await fs.promises.writeFile(outFile, body, "utf-8");
 }
-async function emitRouteTypes(routesPath, outputDir, globalRoute = false) {
-  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?: Record<string, string>
-    serverRoutes?: Record<string, string>
-    /**
-     * Global route helper (available when globalRoute=true in TypeGenConfig).
-     * @see route
-     */
-    route?: typeof route
-  }
-}
-
-// Re-export helper functions from litestar-vite-plugin
-// These work with the routes defined above
-export { getCsrfToken, csrfHeaders, csrfFetch } from "litestar-vite-plugin/helpers"
-${globalRoute ? `
-// Register route() globally on window for Laravel/Ziggy-style usage
-if (typeof window !== "undefined") {
-  window.route = route
-}
-` : ""}
-`;
-  await fs.promises.writeFile(outFile, `${banner}${body}`, "utf-8");
-}
 function resolveTypeGenerationPlugin(typesConfig, executor, hasPythonConfig) {
   let lastTypesHash = null;
   let lastRoutesHash = null;
@@ -953,7 +817,7 @@ function resolveTypeGenerationPlugin(typesConfig, executor, hasPythonConfig) {
         generated = true;
       }
       if (fs.existsSync(routesPath)) {
-        await emitRouteTypes(routesPath, typesConfig.output, typesConfig.globalRoute ?? false);
+        await emitRouteTypes(routesPath, typesConfig.output, { globalRoute: typesConfig.globalRoute ?? false });
         generated = true;
       }
       if (fs.existsSync(pagePropsPath)) {
@@ -1054,7 +918,7 @@ Solutions:
         if (resolvedConfig) {
           resolvedConfig.logger.info(`${colors.cyan("litestar-vite")} ${colors.dim("schema changed:")} ${colors.yellow(relativePath)}`);
         }
-        const newHash = await hashFile(file);
+        const newHash = await getFileMtime(file);
         if (isOpenapi) {
           if (lastTypesHash === newHash) return;
           lastTypesHash = newHash;
@@ -1070,9 +934,9 @@ Solutions:
     }
   };
 }
-async function hashFile(filePath) {
-  const content = await fs.promises.readFile(filePath);
-  return createHash("sha1").update(content).digest("hex");
+async function getFileMtime(filePath) {
+  const stat = await fs.promises.stat(filePath);
+  return stat.mtimeMs.toString();
 }
 function resolveDevServerUrl(address, config, userConfig) {
   const configHmrProtocol = typeof config.server.hmr === "object" ? config.server.hmr.protocol : null;
@@ -1200,6 +1064,5 @@ function normalizeAssetUrl(url) {
   return withTrailing;
 }
 export {
-  litestar as default,
-  refreshPaths
+  litestar as default
 };