litestar-vite-plugin 0.15.0-alpha.6 → 0.15.0-beta.1

package/README.md

@@ -160,7 +160,7 @@ 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
 

package/dist/js/index.d.ts

@@ -35,6 +35,13 @@ export interface TypesConfig {
      * @default 'routes.json'
      */
     routesPath?: string;
+    /**
+     * Path where Inertia page props metadata is exported by Litestar.
+     * The Vite plugin watches this file for page props type generation.
+     *
+     * @default 'inertia-pages.json'
+     */
+    pagePropsPath?: string;
     /**
      * Generate Zod schemas in addition to TypeScript types.
      *
@@ -47,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
@@ -72,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.
@@ -83,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;
     /**
@@ -99,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.
      *
@@ -121,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.
      */
@@ -186,6 +215,50 @@ 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[];
 /**

package/dist/js/index.js

@@ -10,6 +10,8 @@ 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 { formatPath } from "./shared/format-path.js";
+import { createLogger } from "./shared/logger.js";
 const execAsync = promisify(exec);
 let exitHandlersBound = false;
 let warnedMissingRuntimeConfig = false;
@@ -23,16 +25,19 @@ function litestar(config) {
   return plugins;
 }
 async function findIndexHtmlPath(server, pluginConfig) {
+  if (pluginConfig.inertiaMode) {
+    return null;
+  }
   if (!pluginConfig.autoDetectIndex) {
     return null;
   }
   const root = server.config.root;
   const possiblePaths = [
     path.join(root, "index.html"),
-    path.join(root, pluginConfig.resourceDirectory.replace(/^\//, ""), "index.html"),
-    // Ensure resourceDirectory path is relative to root
+    path.join(root, pluginConfig.resourceDir.replace(/^\//, ""), "index.html"),
+    // Ensure resourceDir path is relative to root
     path.join(root, pluginConfig.publicDir.replace(/^\//, ""), "index.html"),
-    path.join(root, pluginConfig.bundleDirectory.replace(/^\//, ""), "index.html")
+    path.join(root, pluginConfig.bundleDir.replace(/^\//, ""), "index.html")
   ];
   for (const indexPath of possiblePaths) {
     try {
@@ -63,8 +68,9 @@ function resolveLitestarPlugin(pluginConfig) {
   let shuttingDown = false;
   const pythonDefaults = loadPythonDefaults();
   const proxyMode = pythonDefaults?.proxyMode ?? "vite_proxy";
+  const logger = createLogger(pythonDefaults?.logging);
   const defaultAliases = {
-    "@": `/${pluginConfig.resourceDirectory.replace(/^\/+/, "").replace(/\/+$/, "")}/`
+    "@": `/${pluginConfig.resourceDir.replace(/^\/+/, "").replace(/\/+$/, "")}/`
   };
   return {
     name: "litestar",
@@ -195,12 +201,9 @@ function resolveLitestarPlugin(pluginConfig) {
           resolvedConfig.logger.warn(formatMissingConfigWarning());
         }
       }
-      const resourceDir = path.resolve(resolvedConfig.root, pluginConfig.resourceDirectory);
-      if (!fs.existsSync(resourceDir) && typeof resolvedConfig.logger?.warn === "function") {
-        resolvedConfig.logger.warn(
-          `${colors.cyan("litestar-vite")} ${colors.yellow("Resource directory not found:")} ${resourceDir}
-  Expected directory: ${colors.dim(pluginConfig.resourceDirectory)}`
-        );
+      const resourceDirPath = path.resolve(resolvedConfig.root, pluginConfig.resourceDir);
+      if (!fs.existsSync(resourceDirPath) && typeof resolvedConfig.logger?.warn === "function") {
+        resolvedConfig.logger.warn(`${colors.cyan("litestar-vite")} ${colors.yellow("Resource directory not found:")} ${pluginConfig.resourceDir}`);
       }
       const hint = pluginConfig.types !== false ? pluginConfig.types.routesPath : void 0;
       litestarMeta = await loadLitestarMeta(resolvedConfig, hint);
@@ -232,19 +235,20 @@ function resolveLitestarPlugin(pluginConfig) {
             fs.writeFileSync(pluginConfig.hotFile, viteDevServerUrl);
           }
           setTimeout(async () => {
-            const version = litestarMeta.litestarVersion ?? process.env.LITESTAR_VERSION ?? "unknown";
+            if (logger.config.level === "quiet") return;
+            const litestarVersion = litestarMeta.litestarVersion ?? process.env.LITESTAR_VERSION ?? "unknown";
             const backendStatus = await checkBackendAvailability(appUrl);
             resolvedConfig.logger.info(`
-  ${colors.red(`${colors.bold("LITESTAR")} ${version}`)}`);
+  ${colors.red(`${colors.bold("LITESTAR")} ${litestarVersion}`)}`);
             resolvedConfig.logger.info("");
             if (initialIndexPath) {
-              resolvedConfig.logger.info(
-                `  ${colors.green("\u279C")}  ${colors.bold("Index Mode")}: SPA (Serving ${colors.cyan(path.relative(server.config.root, initialIndexPath))} from root)`
-              );
+              const relIndexPath = logger.path(initialIndexPath, server.config.root);
+              resolvedConfig.logger.info(`  ${colors.green("\u279C")}  ${colors.bold("Mode")}:       SPA (${colors.cyan(relIndexPath)})`);
+            } else if (pluginConfig.inertiaMode) {
+              resolvedConfig.logger.info(`  ${colors.green("\u279C")}  ${colors.bold("Mode")}:       Inertia`);
             } else {
-              resolvedConfig.logger.info(`  ${colors.green("\u279C")}  ${colors.bold("Index Mode")}: Litestar (Plugin will serve placeholder for /index.html)`);
+              resolvedConfig.logger.info(`  ${colors.green("\u279C")}  ${colors.bold("Mode")}:       Litestar`);
             }
-            resolvedConfig.logger.info(`  ${colors.green("\u279C")}  ${colors.bold("Dev Server")}: ${colors.cyan(viteDevServerUrl)}`);
             if (backendStatus.available) {
               resolvedConfig.logger.info(
                 `  ${colors.green("\u279C")}  ${colors.bold("App URL")}:    ${colors.cyan(appUrl.replace(/:(\d+)/, (_, port) => `:${colors.bold(port)}`))} ${colors.green("\u2713")}`
@@ -254,12 +258,13 @@ function resolveLitestarPlugin(pluginConfig) {
                 `  ${colors.yellow("\u279C")}  ${colors.bold("App URL")}:    ${colors.cyan(appUrl.replace(/:(\d+)/, (_, port) => `:${colors.bold(port)}`))} ${colors.yellow("\u26A0")}`
               );
             }
-            resolvedConfig.logger.info(`  ${colors.green("\u279C")}  ${colors.bold("Assets Base")}: ${colors.cyan(resolvedConfig.base)}`);
+            resolvedConfig.logger.info(`  ${colors.green("\u279C")}  ${colors.bold("Dev Server")}: ${colors.cyan(viteDevServerUrl)}`);
             if (pluginConfig.types !== false && pluginConfig.types.enabled) {
               const openapiExists = fs.existsSync(path.resolve(process.cwd(), pluginConfig.types.openapiPath));
               const routesExists = fs.existsSync(path.resolve(process.cwd(), pluginConfig.types.routesPath));
+              const relTypesOutput = logger.path(pluginConfig.types.output, process.cwd());
               if (openapiExists || routesExists) {
-                resolvedConfig.logger.info(`  ${colors.green("\u279C")}  ${colors.bold("Type Gen")}:   ${colors.green("enabled")} ${colors.dim(`\u2192 ${pluginConfig.types.output}`)}`);
+                resolvedConfig.logger.info(`  ${colors.green("\u279C")}  ${colors.bold("Type Gen")}:   ${colors.dim(`${relTypesOutput}/`)}`);
               } else {
                 resolvedConfig.logger.info(`  ${colors.yellow("\u279C")}  ${colors.bold("Type Gen")}:   ${colors.yellow("waiting")} ${colors.dim("(no schema files yet)")}`);
               }
@@ -320,12 +325,13 @@ function resolveLitestarPlugin(pluginConfig) {
             res.end(transformedHtml);
             return;
           } catch (e) {
-            resolvedConfig.logger.error(`Error serving index.html from ${indexPath}: ${e instanceof Error ? e.message : e}`);
+            const relIndexPath = path.relative(server.config.root, indexPath);
+            resolvedConfig.logger.error(`Error serving index.html from ${relIndexPath}: ${e instanceof Error ? e.message : e}`);
             next(e);
             return;
           }
         }
-        if (!indexPath && req.url === "/index.html") {
+        if (!indexPath && (req.url === "/" || req.url === "/index.html")) {
           try {
             const placeholderPath = path.join(dirname(), "dev-server-index.html");
             const placeholderContent = await fs.promises.readFile(placeholderPath, "utf-8");
@@ -415,7 +421,7 @@ function formatMissingConfigWarning() {
     `${y("\u2502")}    ${d("litestar({")}                                                  ${y("\u2502")}`,
     `${y("\u2502")}    ${d('  input: ["src/main.tsx"],')}                                  ${y("\u2502")}`,
     `${y("\u2502")}    ${d('  assetUrl: "/static/",')}                                     ${y("\u2502")}`,
-    `${y("\u2502")}    ${d('  bundleDirectory: "public",')}                                ${y("\u2502")}`,
+    `${y("\u2502")}    ${d('  bundleDir: "public",')}                                     ${y("\u2502")}`,
     `${y("\u2502")}    ${d("  types: false,")}                                             ${y("\u2502")}`,
     `${y("\u2502")}    ${d("})")}                                                          ${y("\u2502")}`,
     `${y("\u2502")}                                                                 ${y("\u2502")}`,
@@ -442,16 +448,16 @@ function resolvePluginConfig(config) {
   if (typeof resolvedConfig.input === "undefined") {
     throw new Error('litestar-vite-plugin: missing configuration for "input".');
   }
-  if (typeof resolvedConfig.resourceDirectory === "string") {
-    resolvedConfig.resourceDirectory = resolvedConfig.resourceDirectory.trim().replace(/^\/+/, "").replace(/\/+$/, "");
-    if (resolvedConfig.resourceDirectory === "") {
-      throw new Error("litestar-vite-plugin: resourceDirectory must be a subdirectory. E.g. 'resources'.");
+  if (typeof resolvedConfig.resourceDir === "string") {
+    resolvedConfig.resourceDir = resolvedConfig.resourceDir.trim().replace(/^\/+/, "").replace(/\/+$/, "");
+    if (resolvedConfig.resourceDir === "") {
+      throw new Error("litestar-vite-plugin: resourceDir must be a subdirectory. E.g. 'resources'.");
     }
   }
-  if (typeof resolvedConfig.bundleDirectory === "string") {
-    resolvedConfig.bundleDirectory = resolvedConfig.bundleDirectory.trim().replace(/^\/+/, "").replace(/\/+$/, "");
-    if (resolvedConfig.bundleDirectory === "") {
-      throw new Error("litestar-vite-plugin: bundleDirectory must be a subdirectory. E.g. 'public'.");
+  if (typeof resolvedConfig.bundleDir === "string") {
+    resolvedConfig.bundleDir = resolvedConfig.bundleDir.trim().replace(/^\/+/, "").replace(/\/+$/, "");
+    if (resolvedConfig.bundleDir === "") {
+      throw new Error("litestar-vite-plugin: bundleDir must be a subdirectory. E.g. 'public'.");
     }
   }
   if (typeof resolvedConfig.publicDir === "string") {
@@ -460,8 +466,8 @@ function resolvePluginConfig(config) {
       throw new Error("litestar-vite-plugin: publicDir must be a subdirectory. E.g. 'public'.");
     }
   }
-  if (typeof resolvedConfig.ssrOutputDirectory === "string") {
-    resolvedConfig.ssrOutputDirectory = resolvedConfig.ssrOutputDirectory.trim().replace(/^\/+/, "").replace(/\/+$/, "");
+  if (typeof resolvedConfig.ssrOutDir === "string") {
+    resolvedConfig.ssrOutDir = resolvedConfig.ssrOutDir.trim().replace(/^\/+/, "").replace(/\/+$/, "");
   }
   if (resolvedConfig.refresh === true) {
     resolvedConfig.refresh = [{ paths: refreshPaths }];
@@ -474,8 +480,10 @@ function resolvePluginConfig(config) {
       output: "src/generated/types",
       openapiPath: "src/generated/openapi.json",
       routesPath: "src/generated/routes.json",
+      pagePropsPath: "src/generated/inertia-pages.json",
       generateZod: false,
       generateSdk: false,
+      globalRoute: false,
       debounce: 300
     };
   } else if (resolvedConfig.types === "auto" || typeof resolvedConfig.types === "undefined") {
@@ -485,21 +493,26 @@ function resolvePluginConfig(config) {
         output: pythonDefaults.types.output,
         openapiPath: pythonDefaults.types.openapiPath,
         routesPath: pythonDefaults.types.routesPath,
+        pagePropsPath: pythonDefaults.types.pagePropsPath ?? path.join(pythonDefaults.types.output, "inertia-pages.json"),
         generateZod: pythonDefaults.types.generateZod,
         generateSdk: pythonDefaults.types.generateSdk,
+        globalRoute: pythonDefaults.types.globalRoute ?? false,
         debounce: 300
       };
     }
   } else if (typeof resolvedConfig.types === "object" && resolvedConfig.types !== null) {
     const userProvidedOpenapi = Object.hasOwn(resolvedConfig.types, "openapiPath");
     const userProvidedRoutes = Object.hasOwn(resolvedConfig.types, "routesPath");
+    const userProvidedPageProps = Object.hasOwn(resolvedConfig.types, "pagePropsPath");
     typesConfig = {
       enabled: resolvedConfig.types.enabled ?? true,
       output: resolvedConfig.types.output ?? "src/generated/types",
       openapiPath: resolvedConfig.types.openapiPath ?? (resolvedConfig.types.output ? path.join(resolvedConfig.types.output, "openapi.json") : "src/generated/openapi.json"),
       routesPath: resolvedConfig.types.routesPath ?? (resolvedConfig.types.output ? path.join(resolvedConfig.types.output, "routes.json") : "src/generated/routes.json"),
+      pagePropsPath: resolvedConfig.types.pagePropsPath ?? (resolvedConfig.types.output ? path.join(resolvedConfig.types.output, "inertia-pages.json") : "src/generated/inertia-pages.json"),
       generateZod: resolvedConfig.types.generateZod ?? false,
       generateSdk: resolvedConfig.types.generateSdk ?? false,
+      globalRoute: resolvedConfig.types.globalRoute ?? false,
       debounce: resolvedConfig.types.debounce ?? 300
     };
     if (!userProvidedOpenapi && resolvedConfig.types.output) {
@@ -508,24 +521,59 @@ function resolvePluginConfig(config) {
     if (!userProvidedRoutes && resolvedConfig.types.output) {
       typesConfig.routesPath = path.join(typesConfig.output, "routes.json");
     }
+    if (!userProvidedPageProps && resolvedConfig.types.output) {
+      typesConfig.pagePropsPath = path.join(typesConfig.output, "inertia-pages.json");
+    }
   }
-  return {
+  const inertiaMode = resolvedConfig.inertiaMode ?? pythonDefaults?.mode === "inertia";
+  const result = {
     input: resolvedConfig.input,
     assetUrl: normalizeAssetUrl(resolvedConfig.assetUrl ?? pythonDefaults?.assetUrl ?? "/static/"),
-    resourceDirectory: resolvedConfig.resourceDirectory ?? pythonDefaults?.resourceDir ?? "resources",
-    bundleDirectory: resolvedConfig.bundleDirectory ?? pythonDefaults?.bundleDir ?? "public",
+    resourceDir: resolvedConfig.resourceDir ?? pythonDefaults?.resourceDir ?? "src",
+    bundleDir: resolvedConfig.bundleDir ?? pythonDefaults?.bundleDir ?? "public",
     publicDir: resolvedConfig.publicDir ?? pythonDefaults?.publicDir ?? "public",
     ssr: resolvedConfig.ssr ?? resolvedConfig.input,
-    ssrOutputDirectory: resolvedConfig.ssrOutputDirectory ?? pythonDefaults?.ssrOutDir ?? path.join(resolvedConfig.resourceDirectory ?? pythonDefaults?.resourceDir ?? "resources", "bootstrap/ssr"),
+    ssrOutDir: resolvedConfig.ssrOutDir ?? pythonDefaults?.ssrOutDir ?? path.join(resolvedConfig.resourceDir ?? pythonDefaults?.resourceDir ?? "src", "bootstrap/ssr"),
     refresh: resolvedConfig.refresh ?? false,
-    hotFile: resolvedConfig.hotFile ?? path.join(resolvedConfig.bundleDirectory ?? "public", "hot"),
+    hotFile: resolvedConfig.hotFile ?? path.join(resolvedConfig.bundleDir ?? "public", "hot"),
     detectTls: resolvedConfig.detectTls ?? false,
     autoDetectIndex: resolvedConfig.autoDetectIndex ?? true,
+    inertiaMode,
     transformOnServe: resolvedConfig.transformOnServe ?? ((code) => code),
     types: typesConfig,
     executor: resolvedConfig.executor ?? pythonDefaults?.executor,
     hasPythonConfig: pythonDefaults !== null
   };
+  validateAgainstPythonDefaults(result, pythonDefaults, resolvedConfig);
+  return result;
+}
+function validateAgainstPythonDefaults(resolved, pythonDefaults, userConfig) {
+  if (!pythonDefaults) return;
+  const warnings = [];
+  const hasPythonValue = (value) => typeof value === "string" && value.length > 0;
+  if (userConfig.assetUrl !== void 0 && hasPythonValue(pythonDefaults.assetUrl) && resolved.assetUrl !== pythonDefaults.assetUrl) {
+    warnings.push(`assetUrl: vite.config.ts="${resolved.assetUrl}" differs from Python="${pythonDefaults.assetUrl}"`);
+  }
+  if (userConfig.bundleDir !== void 0 && hasPythonValue(pythonDefaults.bundleDir) && resolved.bundleDir !== pythonDefaults.bundleDir) {
+    warnings.push(`bundleDir: vite.config.ts="${resolved.bundleDir}" differs from Python="${pythonDefaults.bundleDir}"`);
+  }
+  if (userConfig.resourceDir !== void 0 && hasPythonValue(pythonDefaults.resourceDir) && resolved.resourceDir !== pythonDefaults.resourceDir) {
+    warnings.push(`resourceDir: vite.config.ts="${resolved.resourceDir}" differs from Python="${pythonDefaults.resourceDir}"`);
+  }
+  if (userConfig.publicDir !== void 0 && hasPythonValue(pythonDefaults.publicDir) && resolved.publicDir !== pythonDefaults.publicDir) {
+    warnings.push(`publicDir: vite.config.ts="${resolved.publicDir}" differs from Python="${pythonDefaults.publicDir}"`);
+  }
+  if (pythonDefaults.ssrEnabled && userConfig.ssrOutDir !== void 0 && hasPythonValue(pythonDefaults.ssrOutDir) && resolved.ssrOutDir !== pythonDefaults.ssrOutDir) {
+    warnings.push(`ssrOutDir: vite.config.ts="${resolved.ssrOutDir}" differs from Python="${pythonDefaults.ssrOutDir}"`);
+  }
+  if (warnings.length > 0) {
+    console.warn(
+      colors.yellow("[litestar-vite] Configuration mismatch detected:\n") + warnings.map((w) => `  ${colors.dim("\u2022")} ${w}`).join("\n") + `
+
+${colors.dim("Precedence: vite.config.ts > .litestar.json > defaults")}
+` + colors.dim("See: https://docs.litestar.dev/vite/config-precedence\n")
+    );
+  }
 }
 function resolveBase(_config, assetUrl) {
   if (process.env.NODE_ENV === "development") {
@@ -541,9 +589,9 @@ function resolveInput(config, ssr) {
 }
 function resolveOutDir(config, ssr) {
   if (ssr) {
-    return config.ssrOutputDirectory.replace(/^\/+/, "").replace(/\/+$/, "");
+    return config.ssrOutDir.replace(/^\/+/, "").replace(/\/+$/, "");
   }
-  return config.bundleDirectory.replace(/^\/+/, "").replace(/\/+$/, "");
+  return config.bundleDir.replace(/^\/+/, "").replace(/\/+$/, "");
 }
 function resolveFullReloadConfig({ refresh: config }) {
   if (typeof config === "boolean") {
@@ -564,7 +612,155 @@ function resolveFullReloadConfig({ refresh: config }) {
     return plugin;
   });
 }
-async function emitRouteTypes(routesPath, outputDir) {
+async function emitPagePropsTypes(pagesPath, outputDir) {
+  const contents = await fs.promises.readFile(pagesPath, "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, "page-props.ts");
+  const { includeDefaultAuth, includeDefaultFlash } = json.typeGenConfig;
+  let userTypes = "";
+  let authTypes = "";
+  let flashTypes = "";
+  if (includeDefaultAuth) {
+    userTypes = `/**
+ * Default User interface - minimal baseline for common auth patterns.
+ * Users extend this via module augmentation with their full user model.
+ *
+ * @example
+ * declare module 'litestar-vite/inertia' {
+ *   interface User {
+ *     avatarUrl?: string | null
+ *     roles: Role[]
+ *     teams: Team[]
+ *   }
+ * }
+ */
+export interface User {
+  id: string
+  email: string
+  name?: string | null
+}
+
+`;
+    authTypes = `/**
+ * Default AuthData interface - mirrors Laravel Jetstream pattern.
+ * isAuthenticated + optional user is the universal pattern.
+ */
+export interface AuthData {
+  isAuthenticated: boolean
+  user?: User
+}
+
+`;
+  } else {
+    userTypes = `/**
+ * User interface - define via module augmentation.
+ * Default auth types are disabled.
+ *
+ * @example
+ * declare module 'litestar-vite/inertia' {
+ *   interface User {
+ *     uuid: string
+ *     username: string
+ *   }
+ * }
+ */
+export interface User {}
+
+`;
+    authTypes = `/**
+ * AuthData interface - define via module augmentation.
+ * Default auth types are disabled.
+ */
+export interface AuthData {}
+
+`;
+  }
+  if (includeDefaultFlash) {
+    flashTypes = `/**
+ * Default FlashMessages interface - category to messages mapping.
+ * Standard categories: success, error, info, warning.
+ */
+export interface FlashMessages {
+  [category: string]: string[]
+}
+
+`;
+  } else {
+    flashTypes = `/**
+ * FlashMessages interface - define via module augmentation.
+ * Default flash types are disabled.
+ */
+export interface FlashMessages {}
+
+`;
+  }
+  const sharedPropsContent = includeDefaultAuth || includeDefaultFlash ? `  auth?: AuthData
+  flash?: FlashMessages` : "";
+  const pageEntries = [];
+  for (const [component, data] of Object.entries(json.pages)) {
+    const propsType = data.propsType ? data.propsType : "Record<string, unknown>";
+    pageEntries.push(`  "${component}": ${propsType} & FullSharedProps`);
+  }
+  const body = `// AUTO-GENERATED by litestar-vite. Do not edit.
+/* eslint-disable */
+
+${userTypes}${authTypes}${flashTypes}/**
+ * Generated shared props (always present).
+ * Includes built-in props + static config props.
+ */
+export interface GeneratedSharedProps {
+  errors?: Record<string, string[]>
+  csrf_token?: string
+}
+
+/**
+ * User-defined shared props for dynamic share() calls in guards/middleware.
+ * Extend this interface via module augmentation.
+ *
+ * @example
+ * declare module 'litestar-vite/inertia' {
+ *   interface User {
+ *     avatarUrl?: string | null
+ *     roles: Role[]
+ *     teams: Team[]
+ *   }
+ *   interface SharedProps {
+ *     locale?: string
+ *     currentTeam?: CurrentTeam
+ *   }
+ * }
+ */
+export interface SharedProps {
+${sharedPropsContent}
+}
+
+/** Full shared props = generated + user-defined */
+export type FullSharedProps = GeneratedSharedProps & SharedProps
+
+/** Page props mapped by component name */
+export interface PageProps {
+${pageEntries.join("\n")}
+}
+
+/** Component name union type */
+export type ComponentName = keyof PageProps
+
+/** Type-safe props for a specific component */
+export type InertiaPageProps<C extends ComponentName> = PageProps[C]
+
+/** Get props type for a specific page component */
+export type PagePropsFor<C extends ComponentName> = PageProps[C]
+
+// Re-export for module augmentation
+declare module "litestar-vite/inertia" {
+  export { User, AuthData, FlashMessages, SharedProps, GeneratedSharedProps, FullSharedProps, PageProps, ComponentName, InertiaPageProps, PagePropsFor }
+}
+`;
+  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);
@@ -677,18 +873,30 @@ declare global {
      */
     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;
+  let lastPagePropsHash = null;
   let server = null;
   let isGenerating = false;
   let resolvedConfig = null;
@@ -703,15 +911,17 @@ function resolveTypeGenerationPlugin(typesConfig, executor, hasPythonConfig) {
       const projectRoot = resolvedConfig?.root ?? process.cwd();
       const openapiPath = path.resolve(projectRoot, typesConfig.openapiPath);
       const routesPath = path.resolve(projectRoot, typesConfig.routesPath);
+      const pagePropsPath = path.resolve(projectRoot, typesConfig.pagePropsPath);
       let generated = false;
       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;
       chosenConfigPath = configPath;
       const shouldRunOpenApiTs = configPath || typesConfig.generateSdk;
       if (fs.existsSync(openapiPath) && shouldRunOpenApiTs) {
-        resolvedConfig?.logger.info(`${colors.cyan("litestar-vite")} ${colors.dim("generating TypeScript types...")}`);
-        if (resolvedConfig) {
-          resolvedConfig.logger.info(`${colors.cyan("litestar-vite")} ${colors.dim("openapi-ts config: ")}${configPath ?? "<built-in defaults>"}`);
+        resolvedConfig?.logger.info(`${colors.cyan("\u2022")} Generating TypeScript types...`);
+        if (resolvedConfig && configPath) {
+          const relConfigPath = formatPath(configPath, resolvedConfig.root);
+          resolvedConfig.logger.info(`${colors.cyan("\u2022")} openapi-ts config: ${relConfigPath}`);
         }
         const sdkOutput = path.join(typesConfig.output, "api");
         let args;
@@ -734,7 +944,7 @@ function resolveTypeGenerationPlugin(typesConfig, executor, hasPythonConfig) {
           try {
             require.resolve("zod", { paths: [process.cwd()] });
           } catch {
-            resolvedConfig?.logger.warn(`${colors.cyan("litestar-vite")} ${colors.yellow("zod not installed")} - run: ${resolveInstallHint()} zod`);
+            resolvedConfig?.logger.warn(`${colors.yellow("!")} zod not installed - run: ${resolveInstallHint()} zod`);
           }
         }
         await execAsync(resolvePackageExecutor(args.join(" "), executor), {
@@ -743,12 +953,16 @@ function resolveTypeGenerationPlugin(typesConfig, executor, hasPythonConfig) {
         generated = true;
       }
       if (fs.existsSync(routesPath)) {
-        await emitRouteTypes(routesPath, typesConfig.output);
+        await emitRouteTypes(routesPath, typesConfig.output, typesConfig.globalRoute ?? false);
+        generated = true;
+      }
+      if (fs.existsSync(pagePropsPath)) {
+        await emitPagePropsTypes(pagePropsPath, typesConfig.output);
         generated = true;
       }
       if (generated && resolvedConfig) {
         const duration = Date.now() - startTime;
-        resolvedConfig.logger.info(`${colors.cyan("litestar-vite")} ${colors.green("TypeScript artifacts updated")} ${colors.dim(`in ${duration}ms`)}`);
+        resolvedConfig.logger.info(`${colors.green("\u2713")} TypeScript artifacts updated ${colors.dim(`(${duration}ms)`)}`);
       }
       if (generated && server) {
         server.ws.send({
@@ -789,11 +1003,12 @@ function resolveTypeGenerationPlugin(typesConfig, executor, hasPythonConfig) {
       server = devServer;
       if (typesConfig.enabled) {
         const root = resolvedConfig?.root ?? process.cwd();
-        const openapiAbs = path.resolve(root, typesConfig.openapiPath);
-        const routesAbs = path.resolve(root, typesConfig.routesPath);
-        resolvedConfig?.logger.info(`${colors.cyan("litestar-vite")} ${colors.dim("watching schema/routes:")} ${colors.yellow(openapiAbs)}, ${colors.yellow(routesAbs)}`);
+        const openapiRel = path.basename(typesConfig.openapiPath);
+        const routesRel = path.basename(typesConfig.routesPath);
+        resolvedConfig?.logger.info(`${colors.cyan("\u2022")} Watching: ${colors.yellow(openapiRel)}, ${colors.yellow(routesRel)}`);
         if (chosenConfigPath) {
-          resolvedConfig?.logger.info(`${colors.cyan("litestar-vite")} ${colors.dim("openapi-ts config:")} ${colors.yellow(chosenConfigPath)}`);
+          const relConfigPath = formatPath(chosenConfigPath, root);
+          resolvedConfig?.logger.info(`${colors.cyan("\u2022")} openapi-ts config: ${colors.yellow(relConfigPath)}`);
         }
       }
     },
@@ -831,17 +1046,24 @@ Solutions:
       const relativePath = path.relative(root, file);
       const openapiPath = typesConfig.openapiPath.replace(/^\.\//, "");
       const routesPath = typesConfig.routesPath.replace(/^\.\//, "");
-      if (relativePath === openapiPath || relativePath === routesPath || file.endsWith(openapiPath) || file.endsWith(routesPath)) {
+      const pagePropsPath = typesConfig.pagePropsPath.replace(/^\.\//, "");
+      const isOpenapi = relativePath === openapiPath || file.endsWith(openapiPath);
+      const isRoutes = relativePath === routesPath || file.endsWith(routesPath);
+      const isPageProps = relativePath === pagePropsPath || file.endsWith(pagePropsPath);
+      if (isOpenapi || isRoutes || isPageProps) {
         if (resolvedConfig) {
           resolvedConfig.logger.info(`${colors.cyan("litestar-vite")} ${colors.dim("schema changed:")} ${colors.yellow(relativePath)}`);
         }
         const newHash = await hashFile(file);
-        if (relativePath === openapiPath) {
+        if (isOpenapi) {
           if (lastTypesHash === newHash) return;
           lastTypesHash = newHash;
-        } else {
+        } else if (isRoutes) {
           if (lastRoutesHash === newHash) return;
           lastRoutesHash = newHash;
+        } else if (isPageProps) {
+          if (lastPagePropsHash === newHash) return;
+          lastPagePropsHash = newHash;
         }
         debouncedRunTypeGeneration();
       }

package/dist/js/shared/format-path.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Path formatting utilities for consistent logging output.
+ *
+ * @module
+ */
+/**
+ * Format an absolute path as relative to the project root for cleaner logging.
+ *
+ * @param absolutePath - The absolute path to format
+ * @param root - The project root directory (defaults to process.cwd())
+ * @returns The path relative to root, or the original path if already relative or on different drive
+ */
+export declare function formatPath(absolutePath: string, root?: string): string;
+/**
+ * Format multiple paths, joining them with a separator.
+ *
+ * @param paths - Array of absolute paths to format
+ * @param root - The project root directory (defaults to process.cwd())
+ * @param separator - Separator between paths (defaults to ", ")
+ * @returns Formatted paths joined by separator
+ */
+export declare function formatPaths(paths: string[], root?: string, separator?: string): string;

package/dist/js/shared/format-path.js

@@ -0,0 +1,24 @@
+import path from "node:path";
+function formatPath(absolutePath, root) {
+  if (!absolutePath) return absolutePath;
+  const projectRoot = root ?? process.cwd();
+  if (!path.isAbsolute(absolutePath)) {
+    return absolutePath;
+  }
+  try {
+    const relativePath = path.relative(projectRoot, absolutePath);
+    if (path.isAbsolute(relativePath)) {
+      return absolutePath;
+    }
+    return relativePath;
+  } catch {
+    return absolutePath;
+  }
+}
+function formatPaths(paths, root, separator = ", ") {
+  return paths.map((p) => formatPath(p, root)).join(separator);
+}
+export {
+  formatPath,
+  formatPaths
+};

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

@@ -0,0 +1,43 @@
+/**
+ * Logging utilities for litestar-vite with configurable output.
+ *
+ * @module
+ */
+/**
+ * Logging configuration matching the Python LoggingConfig.
+ */
+export interface LoggingConfig {
+    level: "quiet" | "normal" | "verbose";
+    showPathsAbsolute: boolean;
+    suppressNpmOutput: boolean;
+    suppressViteBanner: boolean;
+    timestamps: boolean;
+}
+/**
+ * Default logging configuration.
+ */
+export declare const defaultLoggingConfig: LoggingConfig;
+/**
+ * Logger instance with configurable behavior.
+ */
+export interface Logger {
+    /** Log a message at normal level */
+    info: (message: string) => void;
+    /** Log a message at verbose level */
+    debug: (message: string) => void;
+    /** Log a warning (always shown except in quiet mode) */
+    warn: (message: string) => void;
+    /** Log an error (always shown) */
+    error: (message: string) => void;
+    /** Format a path according to config (relative or absolute) */
+    path: (absolutePath: string, root?: string) => string;
+    /** Get the current config */
+    config: LoggingConfig;
+}
+/**
+ * Create a logger instance with the given configuration.
+ *
+ * @param config - Logging configuration (partial, will be merged with defaults)
+ * @returns A Logger instance
+ */
+export declare function createLogger(config?: Partial<LoggingConfig> | null): Logger;

package/dist/js/shared/logger.js

@@ -0,0 +1,59 @@
+import { formatPath } from "./format-path.js";
+const defaultLoggingConfig = {
+  level: "normal",
+  showPathsAbsolute: false,
+  suppressNpmOutput: false,
+  suppressViteBanner: false,
+  timestamps: false
+};
+const LOG_LEVELS = {
+  quiet: 0,
+  normal: 1,
+  verbose: 2
+};
+function createLogger(config) {
+  const mergedConfig = {
+    ...defaultLoggingConfig,
+    ...config
+  };
+  const levelNum = LOG_LEVELS[mergedConfig.level];
+  const formatMessage = (message) => {
+    if (mergedConfig.timestamps) {
+      const now = (/* @__PURE__ */ new Date()).toISOString().slice(11, 23);
+      return `[${now}] ${message}`;
+    }
+    return message;
+  };
+  const formatPathValue = (absolutePath, root) => {
+    if (mergedConfig.showPathsAbsolute) {
+      return absolutePath;
+    }
+    return formatPath(absolutePath, root);
+  };
+  return {
+    info: (message) => {
+      if (levelNum >= LOG_LEVELS.normal) {
+        console.log(formatMessage(message));
+      }
+    },
+    debug: (message) => {
+      if (levelNum >= LOG_LEVELS.verbose) {
+        console.log(formatMessage(message));
+      }
+    },
+    warn: (message) => {
+      if (levelNum >= LOG_LEVELS.normal) {
+        console.warn(formatMessage(message));
+      }
+    },
+    error: (message) => {
+      console.error(formatMessage(message));
+    },
+    path: formatPathValue,
+    config: mergedConfig
+  };
+}
+export {
+  createLogger,
+  defaultLoggingConfig
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "litestar-vite-plugin",
-  "version": "0.15.0-alpha.6",
+  "version": "0.15.0-beta.1",
   "type": "module",
   "description": "Litestar plugin for Vite.",
   "keywords": [
@@ -55,7 +55,7 @@
     "build": "npm run build-plugin && npm run build-helpers && npm run build-inertia-helpers && npm run build-integrations",
     "build-plugin": "rm -rf dist/js && npm run build-plugin-types && npm run build-plugin-esm && cp src/js/src/dev-server-index.html dist/js/",
     "build-plugin-types": "tsc --project src/js/tsconfig.json --emitDeclarationOnly",
-    "build-plugin-esm": "esbuild src/js/src/index.ts --platform=node --format=esm --outfile=dist/js/index.js && esbuild src/js/src/install-hint.ts --platform=node --format=esm --outfile=dist/js/install-hint.js && esbuild src/js/src/litestar-meta.ts --platform=node --format=esm --outfile=dist/js/litestar-meta.js && mkdir -p dist/js/shared && esbuild src/js/src/shared/debounce.ts --platform=node --format=esm --outfile=dist/js/shared/debounce.js",
+    "build-plugin-esm": "esbuild src/js/src/index.ts --platform=node --format=esm --outfile=dist/js/index.js && esbuild src/js/src/install-hint.ts --platform=node --format=esm --outfile=dist/js/install-hint.js && esbuild src/js/src/litestar-meta.ts --platform=node --format=esm --outfile=dist/js/litestar-meta.js && mkdir -p dist/js/shared && esbuild src/js/src/shared/debounce.ts src/js/src/shared/format-path.ts src/js/src/shared/logger.ts --platform=node --format=esm --outdir=dist/js/shared",
     "build-helpers": "rm -rf dist/js/helpers && tsc --project src/js/tsconfig.helpers.json",
     "build-inertia-helpers": "rm -rf dist/js/inertia-helpers && tsc --project src/js/tsconfig.inertia-helpers.json",
     "build-integrations": "esbuild src/js/src/astro.ts src/js/src/sveltekit.ts src/js/src/nuxt.ts --platform=node --format=esm --outdir=dist/js",