litestar-vite-plugin 0.15.0-alpha.7 → 0.15.0-beta.2

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
@@ -160,10 +177,11 @@ litestar assets generate-types  # one-off or CI
 
 - Prints Python vs Vite config snapshot (asset URLs, bundle/hot paths, ports, modes).
 - Flags missing hot file (dev proxy), missing manifest (prod), type-gen exports, env/config mismatches, and plugin install issues.
-- `--fix` can rewrite simple vite.config values (assetUrl, bundleDirectory, hotFile, type paths) after creating a backup.
+- `--fix` can rewrite simple vite.config values (assetUrl, bundleDir, hotFile, type paths) after creating a backup.
 
 ## Links
 
 - 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

@@ -54,6 +54,16 @@ export interface TypesConfig {
      * @default false
      */
     generateSdk?: boolean;
+    /**
+     * Register route() function globally on window object.
+     *
+     * When true, the generated routes.ts will include code that registers
+     * the type-safe route() function on `window.route`, similar to Laravel's
+     * Ziggy library. This allows using route() without imports.
+     *
+     * @default false
+     */
+    globalRoute?: boolean;
     /**
      * Debounce time in milliseconds for type regeneration.
      * Prevents regeneration from running too frequently when
@@ -79,7 +89,7 @@ export interface PluginConfig {
      *
      * @default 'public/dist'
      */
-    bundleDirectory?: string;
+    bundleDir?: string;
     /**
      * Vite's public directory for static, unprocessed assets.
      * Mirrors Vite's `publicDir` option.
@@ -90,13 +100,13 @@ export interface PluginConfig {
     /**
      * Litestar's public assets directory.  These are the assets that Vite will serve when developing.
      *
-     * @default 'resources'
+     * @default 'src'
      */
-    resourceDirectory?: string;
+    resourceDir?: string;
     /**
      * The path to the "hot" file.
      *
-     * @default `${bundleDirectory}/hot`
+     * @default `${bundleDir}/hot`
      */
     hotFile?: string;
     /**
@@ -106,9 +116,9 @@ export interface PluginConfig {
     /**
      * The directory where the SSR bundle should be written.
      *
-     * @default '${bundleDirectory}/bootstrap/ssr'
+     * @default '${bundleDir}/bootstrap/ssr'
      */
-    ssrOutputDirectory?: string;
+    ssrOutDir?: string;
     /**
      * Configuration for performing full page refresh on python (or other) file changes.
      *
@@ -128,6 +138,18 @@ export interface PluginConfig {
      * @default true
      */
     autoDetectIndex?: boolean;
+    /**
+     * Enable Inertia mode, which disables index.html auto-detection.
+     *
+     * In Inertia apps, the backend (Litestar) serves all HTML responses.
+     * When enabled, direct access to the Vite dev server will show a placeholder
+     * page directing users to access the app through the backend.
+     *
+     * Auto-detected from `.litestar.json` when mode is "inertia".
+     *
+     * @default false (auto-detected from .litestar.json)
+     */
+    inertiaMode?: boolean;
     /**
      * Transform the code while serving.
      */
@@ -193,8 +215,51 @@ interface RefreshConfig {
     paths: string[];
     config?: FullReloadConfig;
 }
+/**
+ * Bridge schema for `.litestar.json` - the shared configuration contract
+ * between Python (Litestar) and TypeScript (Vite plugin).
+ *
+ * Python writes this file on startup; TypeScript reads it as defaults.
+ * Field names use camelCase (JavaScript convention) and match exactly
+ * between the JSON file and this TypeScript interface.
+ *
+ * Precedence: vite.config.ts > .litestar.json > hardcoded defaults
+ */
+export interface BridgeSchema {
+    assetUrl: string;
+    bundleDir: string;
+    resourceDir: string;
+    publicDir: string;
+    hotFile: string;
+    manifest: string;
+    mode: "spa" | "inertia" | "ssr" | "hybrid";
+    proxyMode: "vite_proxy" | "vite_direct" | "external_proxy";
+    host: string;
+    port: number;
+    protocol: "http" | "https";
+    ssrEnabled: boolean;
+    ssrOutDir: string | null;
+    types: {
+        enabled: boolean;
+        output: string;
+        openapiPath: string;
+        routesPath: string;
+        pagePropsPath?: string;
+        generateZod: boolean;
+        generateSdk: boolean;
+        globalRoute: boolean;
+    } | null;
+    executor: "node" | "bun" | "deno" | "yarn" | "pnpm";
+    logging: {
+        level: "quiet" | "normal" | "verbose";
+        showPathsAbsolute: boolean;
+        suppressNpmOutput: boolean;
+        suppressViteBanner: boolean;
+        timestamps: boolean;
+    } | null;
+    litestarVersion: string;
+}
 type DevServerUrl = `${"http" | "https"}://${string}:${number}`;
-export declare const refreshPaths: string[];
 /**
  * Litestar plugin for Vite.
  *