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

package/README.md

@@ -5,7 +5,7 @@ Litestar Vite connects the Litestar backend to a Vite toolchain. It supports SPA
 ## Features
 
 - One-port dev: proxies Vite HTTP + WS/HMR through Litestar by default; switch to two-port with `VITE_PROXY_MODE=direct`.
-- SSR framework support: use `proxy_mode="ssr"` for Astro, Nuxt, SvelteKit - proxies everything except your API routes.
+- SSR framework support: use `mode="ssr"` for Astro, Nuxt, SvelteKit - proxies everything except your API routes.
 - Production assets: reads Vite manifest from `public/manifest.json` (configurable) and serves under `asset_url`.
 - Type-safe frontends: optional OpenAPI/routes export + `@hey-api/openapi-ts` via the Vite plugin.
 - Inertia support: v2 protocol with session middleware and optional SPA mode.
@@ -103,13 +103,13 @@ app = Litestar(
 
 ## Meta-frameworks (Astro, Nuxt, SvelteKit)
 
-Use `proxy_mode="ssr"` to proxy non-API routes to the framework's dev server:
+Use `mode="ssr"` (or `mode="framework"`) to proxy non-API routes to the framework's dev server:
 
 ```python
 import os
 from pathlib import Path
 from litestar import Litestar
-from litestar_vite import VitePlugin, ViteConfig, PathConfig, RuntimeConfig
+from litestar_vite import VitePlugin, ViteConfig, PathConfig
 
 here = Path(__file__).parent
 DEV_MODE = os.getenv("VITE_DEV_MODE", "true").lower() in ("true", "1", "yes")
@@ -117,9 +117,9 @@ DEV_MODE = os.getenv("VITE_DEV_MODE", "true").lower() in ("true", "1", "yes")
 app = Litestar(
     plugins=[
         VitePlugin(config=ViteConfig(
+            mode="ssr",
             dev_mode=DEV_MODE,
             paths=PathConfig(root=here),
-            runtime=RuntimeConfig(proxy_mode="ssr"),
         ))
     ],
 )

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

@@ -31,6 +31,7 @@
 export interface RouteDefinition {
     path: string;
     methods: readonly string[];
+    method: string;
     pathParams: readonly string[];
     queryParams: readonly string[];
     component?: string;

package/dist/js/index.d.ts

@@ -100,6 +100,13 @@ export interface PluginConfig {
      * @default '/static/'
      */
     assetUrl?: string;
+    /**
+     * Optional asset URL to use only during production builds.
+     *
+     * This is typically derived from Python DeployConfig.asset_url and written into `.litestar.json`
+     * as `deployAssetUrl`. It is only used when `command === "build"`.
+     */
+    deployAssetUrl?: string;
     /**
      * The public directory where all compiled/bundled assets should be written.
      *
@@ -160,11 +167,12 @@ export interface PluginConfig {
      */
     autoDetectIndex?: boolean;
     /**
-     * Enable Inertia mode, which disables index.html auto-detection.
+     * Enable Inertia mode.
      *
      * 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.
+     * page directing users to access the app through the backend (even if an
+     * index.html exists for the backend to render).
      *
      * Auto-detected from `.litestar.json` when mode is "inertia".
      *

package/dist/js/index.js

@@ -28,9 +28,6 @@ function litestar(config) {
   return plugins;
 }
 async function findIndexHtmlPath(server, pluginConfig) {
-  if (pluginConfig.inertiaMode) {
-    return null;
-  }
   if (!pluginConfig.autoDetectIndex) {
     return null;
   }
@@ -81,7 +78,8 @@ function resolveLitestarPlugin(pluginConfig) {
       userConfig = config;
       const ssr = !!userConfig.build?.ssr;
       const env = loadEnv(mode, userConfig.envDir || process.cwd(), "");
-      const assetUrl = normalizeAssetUrl(env.ASSET_URL || pluginConfig.assetUrl);
+      const runtimeAssetUrl = normalizeAssetUrl(env.ASSET_URL || pluginConfig.assetUrl);
+      const buildAssetUrl = pluginConfig.deployAssetUrl ?? runtimeAssetUrl;
       const serverConfig = command === "serve" ? resolveDevelopmentEnvironmentServerConfig(pluginConfig.detectTls) ?? resolveEnvironmentServerConfig(env) : void 0;
       const withProxyErrorSilencer = (proxyConfig) => {
         if (!proxyConfig) return void 0;
@@ -114,7 +112,7 @@ function resolveLitestarPlugin(pluginConfig) {
       const devBase = pluginConfig.assetUrl.startsWith("/") ? pluginConfig.assetUrl : pluginConfig.assetUrl.replace(/\/+$/, "");
       ensureCommandShouldRunInEnvironment(command, env, mode);
       return {
-        base: userConfig.base ?? (command === "build" ? resolveBase(pluginConfig, assetUrl) : devBase),
+        base: userConfig.base ?? (command === "build" ? resolveBase(pluginConfig, buildAssetUrl) : devBase),
         publicDir: userConfig.publicDir ?? pluginConfig.staticDir ?? false,
         clearScreen: false,
         build: {
@@ -237,15 +235,21 @@ function resolveLitestarPlugin(pluginConfig) {
           setTimeout(async () => {
             if (logger.config.level === "quiet") return;
             const litestarVersion = litestarMeta.litestarVersion ?? process.env.LITESTAR_VERSION ?? "unknown";
-            const backendStatus = await checkBackendAvailability(appUrl);
+            let backendStatus = await checkBackendAvailability(appUrl);
+            if (!backendStatus.available) {
+              for (let i = 0; i < 3 && !backendStatus.available; i++) {
+                await new Promise((resolve) => setTimeout(resolve, 500));
+                backendStatus = await checkBackendAvailability(appUrl);
+              }
+            }
             resolvedConfig.logger.info(`
   ${colors.red(`${colors.bold("LITESTAR")} ${litestarVersion}`)}`);
             resolvedConfig.logger.info("");
-            if (initialIndexPath) {
+            if (pluginConfig.inertiaMode) {
+              resolvedConfig.logger.info(`  ${colors.green("\u279C")}  ${colors.bold("Mode")}:       Inertia`);
+            } else if (initialIndexPath) {
               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("Mode")}:       Litestar`);
             }
@@ -314,24 +318,51 @@ function resolveLitestarPlugin(pluginConfig) {
         exitHandlersBound = true;
       }
       server.middlewares.use(async (req, res, next) => {
-        const indexPath = await findIndexHtmlPath(server, pluginConfig);
-        if (indexPath && (req.url === "/" || req.url === "/index.html")) {
-          const currentUrl = req.url;
+        const requestUrl = req.originalUrl ?? req.url ?? "/";
+        const requestPath = requestUrl.split("?")[0];
+        const isRootRequest = requestPath === "/" || requestPath === "/index.html";
+        if (requestPath === "/__litestar__/transform-index") {
+          if (req.method !== "POST") {
+            res.statusCode = 405;
+            res.setHeader("Content-Type", "text/plain");
+            res.end("Method Not Allowed");
+            return;
+          }
+          const readBody = async () => new Promise((resolve, reject) => {
+            let data = "";
+            req.on("data", (chunk) => {
+              data += chunk;
+            });
+            req.on("end", () => resolve(data));
+            req.on("error", (err) => reject(err));
+          });
           try {
-            const htmlContent = await fs.promises.readFile(indexPath, "utf-8");
-            const transformedHtml = await server.transformIndexHtml(req.originalUrl ?? currentUrl, htmlContent, req.originalUrl);
+            const body = await readBody();
+            const payload = JSON.parse(body);
+            if (!payload.html || typeof payload.html !== "string") {
+              res.statusCode = 400;
+              res.setHeader("Content-Type", "text/plain");
+              res.end("Invalid payload");
+              return;
+            }
+            const url = typeof payload.url === "string" && payload.url ? payload.url : "/";
+            const transformedHtml = await server.transformIndexHtml(url, payload.html, url);
             res.statusCode = 200;
             res.setHeader("Content-Type", "text/html");
             res.end(transformedHtml);
-            return;
           } catch (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;
+            resolvedConfig.logger.error(`Error transforming index.html: ${e instanceof Error ? e.message : e}`);
+            res.statusCode = 500;
+            res.setHeader("Content-Type", "text/plain");
+            res.end("Error transforming HTML");
           }
+          return;
         }
-        if (!indexPath && (req.url === "/" || req.url === "/index.html")) {
+        if (!isRootRequest) {
+          next();
+          return;
+        }
+        if (pluginConfig.inertiaMode) {
           try {
             const placeholderPath = path.join(dirname(), "dev-server-index.html");
             const placeholderContent = await fs.promises.readFile(placeholderPath, "utf-8");
@@ -345,7 +376,33 @@ function resolveLitestarPlugin(pluginConfig) {
           }
           return;
         }
-        next();
+        const indexPath = await findIndexHtmlPath(server, pluginConfig);
+        if (indexPath) {
+          try {
+            const htmlContent = await fs.promises.readFile(indexPath, "utf-8");
+            const transformedHtml = await server.transformIndexHtml(requestUrl, htmlContent, requestUrl);
+            res.statusCode = 200;
+            res.setHeader("Content-Type", "text/html");
+            res.end(transformedHtml);
+            return;
+          } catch (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;
+          }
+        }
+        try {
+          const placeholderPath = path.join(dirname(), "dev-server-index.html");
+          const placeholderContent = await fs.promises.readFile(placeholderPath, "utf-8");
+          res.statusCode = 200;
+          res.setHeader("Content-Type", "text/html");
+          res.end(placeholderContent.replace(/{{ APP_URL }}/g, appUrl));
+        } catch (e) {
+          resolvedConfig.logger.error(`Error serving placeholder index.html: ${e instanceof Error ? e.message : e}`);
+          res.statusCode = 404;
+          res.end("Not Found (Error loading placeholder)");
+        }
       });
     }
   };
@@ -512,9 +569,11 @@ function resolvePluginConfig(config) {
   }
   const inertiaMode = resolvedConfig.inertiaMode ?? (pythonDefaults?.mode === "hybrid" || pythonDefaults?.mode === "inertia");
   const effectiveResourceDir = resolvedConfig.resourceDir ?? pythonDefaults?.resourceDir ?? "src";
+  const deployAssetUrlRaw = resolvedConfig.deployAssetUrl ?? pythonDefaults?.deployAssetUrl ?? void 0;
   const result = {
     input: resolvedConfig.input,
     assetUrl: normalizeAssetUrl(resolvedConfig.assetUrl ?? pythonDefaults?.assetUrl ?? "/static/"),
+    deployAssetUrl: typeof deployAssetUrlRaw === "string" ? normalizeAssetUrl(deployAssetUrlRaw) : void 0,
     resourceDir: effectiveResourceDir,
     bundleDir: resolvedConfig.bundleDir ?? pythonDefaults?.bundleDir ?? "public",
     staticDir: resolvedConfig.staticDir ?? pythonDefaults?.staticDir ?? path.join(effectiveResourceDir, "public"),
@@ -549,7 +608,8 @@ function validateAgainstPythonDefaults(resolved, pythonDefaults, userConfig) {
   if (userConfig.staticDir !== void 0 && hasPythonValue(pythonDefaults.staticDir) && resolved.staticDir !== pythonDefaults.staticDir) {
     warnings.push(`staticDir: vite.config.ts="${resolved.staticDir}" differs from Python="${pythonDefaults.staticDir}"`);
   }
-  if (pythonDefaults.ssrEnabled && userConfig.ssrOutDir !== void 0 && hasPythonValue(pythonDefaults.ssrOutDir) && resolved.ssrOutDir !== pythonDefaults.ssrOutDir) {
+  const frameworkMode = pythonDefaults.mode === "framework" || pythonDefaults.mode === "ssr" || pythonDefaults.mode === "ssg";
+  if (frameworkMode && 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) {

package/dist/js/inertia-types.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Base types for Inertia.js type generation.
+ *
+ * These types are generated by `litestar assets generate-types` in your
+ * project's `generated/page-props.ts` file. This module provides fallback
+ * types for when the generated file hasn't been created yet.
+ *
+ * To customize types, edit your project's `generated/page-props.user.ts` file.
+ */
+/** User interface - customize in page-props.user.ts */
+export interface User {
+}
+/** Authentication data interface */
+export interface AuthData {
+}
+/** Flash messages interface */
+export interface FlashMessages {
+}
+/** User-defined shared props - customize in page-props.user.ts */
+export interface SharedProps {
+}
+/** Generated shared props (populated by page-props.ts) */
+export interface GeneratedSharedProps {
+}
+/** Full shared props = generated + user-defined */
+export type FullSharedProps = GeneratedSharedProps & SharedProps & {
+    [key: string]: unknown;
+};
+/** Page props mapped by component name (populated by page-props.ts) */
+export interface PageProps {
+}
+/** 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];

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

@@ -1,7 +1,12 @@
+/**
+ * Detect the executor from .litestar.json or environment.
+ * Priority: LITESTAR_VITE_RUNTIME env > .litestar.json executor > lockfile detection > 'node'
+ */
+export declare function detectExecutor(): string;
 export declare function resolveInstallHint(pkg?: string): string;
 /**
  * Resolves the package executor command based on runtime.
- * Priority: explicit executor > LITESTAR_VITE_RUNTIME env > 'node' default
+ * Priority: explicit executor > .litestar.json > LITESTAR_VITE_RUNTIME env > lockfile detection > 'npx'
  *
  * @param pkg - The package command to execute (e.g., "@hey-api/openapi-ts -i schema.json -o src/types")
  * @param executor - Optional explicit executor override

package/dist/js/install-hint.js

@@ -1,5 +1,37 @@
+import fs from "node:fs";
+import path from "node:path";
+function detectExecutor() {
+  const envRuntime = (process.env.LITESTAR_VITE_RUNTIME ?? "").toLowerCase();
+  if (envRuntime) return envRuntime;
+  const configPath = process.env.LITESTAR_VITE_CONFIG_PATH ?? path.resolve(process.cwd(), ".litestar.json");
+  if (fs.existsSync(configPath)) {
+    try {
+      const raw = fs.readFileSync(configPath, "utf8");
+      const data = JSON.parse(raw);
+      const executor = data?.executor;
+      if (typeof executor === "string" && executor.trim()) {
+        return executor.trim().toLowerCase();
+      }
+    } catch {
+    }
+  }
+  const cwd = process.cwd();
+  if (fs.existsSync(path.join(cwd, "bun.lockb")) || fs.existsSync(path.join(cwd, "bun.lock"))) {
+    return "bun";
+  }
+  if (fs.existsSync(path.join(cwd, "pnpm-lock.yaml"))) {
+    return "pnpm";
+  }
+  if (fs.existsSync(path.join(cwd, "yarn.lock"))) {
+    return "yarn";
+  }
+  if (fs.existsSync(path.join(cwd, "deno.lock"))) {
+    return "deno";
+  }
+  return "node";
+}
 function resolveInstallHint(pkg = "@hey-api/openapi-ts") {
-  const runtime = (process.env.LITESTAR_VITE_RUNTIME ?? "").toLowerCase();
+  const runtime = detectExecutor();
   switch (runtime) {
     case "bun":
       return `bun add -d ${pkg}`;
@@ -17,7 +49,7 @@ function resolveInstallHint(pkg = "@hey-api/openapi-ts") {
   return `npm install -D ${pkg}`;
 }
 function resolvePackageExecutor(pkg, executor) {
-  const runtime = (executor ?? process.env.LITESTAR_VITE_RUNTIME ?? "").toLowerCase();
+  const runtime = executor || detectExecutor();
   switch (runtime) {
     case "bun":
       return `bunx ${pkg}`;
@@ -32,6 +64,7 @@ function resolvePackageExecutor(pkg, executor) {
   }
 }
 export {
+  detectExecutor,
   resolveInstallHint,
   resolvePackageExecutor
 };

package/dist/js/shared/bridge-schema.d.ts

@@ -8,7 +8,7 @@
  *
  * @module
  */
-export type BridgeMode = "spa" | "template" | "htmx" | "hybrid" | "inertia" | "ssr" | "ssg" | "external";
+export type BridgeMode = "spa" | "template" | "htmx" | "hybrid" | "inertia" | "framework" | "ssr" | "ssg" | "external";
 export type BridgeProxyMode = "vite" | "direct" | "proxy" | null;
 export type BridgeExecutor = "node" | "bun" | "deno" | "yarn" | "pnpm";
 export interface BridgeTypesConfig {
@@ -23,8 +23,13 @@ export interface BridgeTypesConfig {
     generatePageProps: boolean;
     globalRoute: boolean;
 }
+export interface BridgeSpaConfig {
+    /** Use script element instead of data-page attribute for Inertia page data */
+    useScriptElement: boolean;
+}
 export interface BridgeSchema {
     assetUrl: string;
+    deployAssetUrl: string | null;
     bundleDir: string;
     resourceDir: string;
     staticDir: string;
@@ -34,9 +39,9 @@ export interface BridgeSchema {
     proxyMode: BridgeProxyMode;
     host: string;
     port: number;
-    ssrEnabled: boolean;
     ssrOutDir: string | null;
     types: BridgeTypesConfig | null;
+    spa: BridgeSpaConfig | null;
     executor: BridgeExecutor;
     logging: {
         level: "quiet" | "normal" | "verbose";

package/dist/js/shared/bridge-schema.js

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 const allowedTopLevelKeys = /* @__PURE__ */ new Set([
   "assetUrl",
+  "deployAssetUrl",
   "bundleDir",
   "resourceDir",
   "staticDir",
@@ -11,14 +12,14 @@ const allowedTopLevelKeys = /* @__PURE__ */ new Set([
   "proxyMode",
   "host",
   "port",
-  "ssrEnabled",
   "ssrOutDir",
   "types",
+  "spa",
   "executor",
   "logging",
   "litestarVersion"
 ]);
-const allowedModes = /* @__PURE__ */ new Set(["spa", "template", "htmx", "hybrid", "inertia", "ssr", "ssg", "external"]);
+const allowedModes = /* @__PURE__ */ new Set(["spa", "template", "htmx", "hybrid", "inertia", "framework", "ssr", "ssg", "external"]);
 const allowedProxyModes = /* @__PURE__ */ new Set(["vite", "direct", "proxy"]);
 const allowedExecutors = /* @__PURE__ */ new Set(["node", "bun", "deno", "yarn", "pnpm"]);
 const allowedLogLevels = /* @__PURE__ */ new Set(["quiet", "normal", "verbose"]);
@@ -106,6 +107,12 @@ function parseLogging(value) {
   const timestamps = assertBoolean(obj, "timestamps");
   return { level, showPathsAbsolute, suppressNpmOutput, suppressViteBanner, timestamps };
 }
+function parseSpaConfig(value) {
+  if (value === null || value === void 0) return null;
+  const obj = assertObject(value, "spa");
+  const useScriptElement = assertBoolean(obj, "useScriptElement");
+  return { useScriptElement };
+}
 function parseBridgeSchema(value) {
   const obj = assertObject(value, "root");
   for (const key of Object.keys(obj)) {
@@ -114,6 +121,7 @@ function parseBridgeSchema(value) {
     }
   }
   const assetUrl = assertString(obj, "assetUrl");
+  const deployAssetUrl = assertNullableString(obj, "deployAssetUrl");
   const bundleDir = assertString(obj, "bundleDir");
   const resourceDir = assertString(obj, "resourceDir");
   const staticDir = assertString(obj, "staticDir");
@@ -123,14 +131,15 @@ function parseBridgeSchema(value) {
   const proxyMode = assertProxyMode(obj.proxyMode);
   const host = assertString(obj, "host");
   const port = assertNumber(obj, "port");
-  const ssrEnabled = assertBoolean(obj, "ssrEnabled");
   const ssrOutDir = assertNullableString(obj, "ssrOutDir");
   const types = parseTypesConfig(obj.types);
+  const spa = parseSpaConfig(obj.spa);
   const executor = assertEnum(obj.executor, "executor", allowedExecutors);
   const logging = parseLogging(obj.logging);
   const litestarVersion = assertString(obj, "litestarVersion");
   return {
     assetUrl,
+    deployAssetUrl,
     bundleDir,
     resourceDir,
     staticDir,
@@ -140,9 +149,9 @@ function parseBridgeSchema(value) {
     proxyMode,
     host,
     port,
-    ssrEnabled,
     ssrOutDir,
     types,
+    spa,
     executor,
     logging,
     litestarVersion

package/dist/js/shared/emit-page-props-types.d.ts

@@ -1,4 +1,6 @@
 /**
  * Generate `page-props.ts` from `inertia-pages.json` metadata.
+ *
+ * @returns true if file was changed, false if unchanged
  */
-export declare function emitPagePropsTypes(pagesPath: string, outputDir: string): Promise<void>;
+export declare function emitPagePropsTypes(pagesPath: string, outputDir: string): Promise<boolean>;

package/dist/js/shared/emit-page-props-types.js

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import { writeIfChanged } from "./write-if-changed.js";
 async function emitPagePropsTypes(pagesPath, outputDir) {
   const contents = await fs.promises.readFile(pagesPath, "utf-8");
   const json = JSON.parse(contents);
@@ -16,18 +17,9 @@ async function emitPagePropsTypes(pagesPath, outputDir) {
   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-plugin/inertia' {
- *   interface User {
- *     avatarUrl?: string | null
- *     roles: Role[]
- *     teams: Team[]
- *   }
- * }
+ * Extend by adding properties to UserExtensions in page-props.user.ts
  */
-export interface User {
+export interface User extends UserExtensions {
   id: string
   email: string
   name?: string | null
@@ -46,23 +38,13 @@ export interface AuthData {
 `;
   } else {
     userTypes = `/**
- * User interface - define via module augmentation.
- * Default auth types are disabled.
- *
- * @example
- * declare module 'litestar-vite-plugin/inertia' {
- *   interface User {
- *     uuid: string
- *     username: string
- *   }
- * }
+ * User interface - add properties to UserExtensions in page-props.user.ts
  */
-export interface User {}
+export interface User extends UserExtensions {}
 
 `;
     authTypes = `/**
- * AuthData interface - define via module augmentation.
- * Default auth types are disabled.
+ * AuthData interface - define your auth structure here or in page-props.user.ts
  */
 export interface AuthData {}
 
@@ -163,7 +145,7 @@ export interface FlashMessages {}
   const availableApiTypes = /* @__PURE__ */ new Set();
   if (fs.existsSync(apiTypesPath)) {
     const content = await fs.promises.readFile(apiTypesPath, "utf-8");
-    for (const match of content.matchAll(/export (?:type|interface|enum|class) (\\w+)/g)) {
+    for (const match of content.matchAll(/export (?:type|interface|enum|class) (\w+)/g)) {
       if (match[1]) {
         availableApiTypes.add(match[1]);
       }
@@ -184,7 +166,13 @@ export interface FlashMessages {}
     }
   }
   if (unresolvedTypes.length > 0) {
-    console.warn(`litestar-vite: unresolved Inertia props types: ${unresolvedTypes.join(", ")}. Add them to TypeGenConfig.type_import_paths or include them in OpenAPI.`);
+    console.warn(
+      `litestar-vite: Unresolved Inertia props types: ${unresolvedTypes.join(", ")}.
+  To fix:
+  1. Add to OpenAPI by including in route return types
+  2. Or configure TypeGenConfig.type_import_paths:
+     types=TypeGenConfig(type_import_paths={"${unresolvedTypes[0]}": "@/types/custom"})`
+    );
   }
   let importStatement = "";
   if (apiImports.length > 0) {
@@ -211,6 +199,9 @@ export interface FlashMessages {}
   const body = `// AUTO-GENERATED by litestar-vite. Do not edit.
 /* eslint-disable */
 
+// Import user-defined type extensions (edit page-props.user.ts to customize)
+import type { UserExtensions, SharedPropsExtensions } from "./page-props.user"
+
 ${importStatement}${userTypes}${authTypes}${flashTypes}/**
  * Generated shared props (always present).
  * Includes built-in props + static config props.
@@ -221,26 +212,13 @@ ${generatedSharedPropLines.join("\n")}
 
 /**
  * User-defined shared props for dynamic share() calls in guards/middleware.
- * Extend this interface via module augmentation.
- *
- * @example
- * declare module 'litestar-vite-plugin/inertia' {
- *   interface User {
- *     avatarUrl?: string | null
- *     roles: Role[]
- *     teams: Team[]
- *   }
- *   interface SharedProps {
- *     locale?: string
- *     currentTeam?: CurrentTeam
- *   }
- * }
+ * Extend by adding properties to SharedPropsExtensions in page-props.user.ts
  */
-export interface SharedProps {
-}
+export type SharedProps = SharedPropsExtensions
 
-/** Full shared props = generated + user-defined */
-export type FullSharedProps = GeneratedSharedProps & SharedProps
+/** Full shared props = generated + user-defined.
+ * Includes index signature for compatibility with Inertia's usePage<T>(). */
+export type FullSharedProps = GeneratedSharedProps & SharedProps & { [key: string]: unknown }
 
 /** Page props mapped by component name */
 export interface PageProps {
@@ -255,13 +233,57 @@ export type InertiaPageProps<C extends ComponentName> = PageProps[C]
 
 /** Get props type for a specific page component */
 export type PagePropsFor<C extends ComponentName> = PageProps[C]
+`;
+  const result = await writeIfChanged(outFile, body, { encoding: "utf-8" });
+  const userStubFile = path.join(outDir, "page-props.user.ts");
+  if (!fs.existsSync(userStubFile)) {
+    const userStub = `/**
+ * User-defined type extensions for Inertia page props.
+ * This file is generated ONCE and never overwritten - edit freely!
+ *
+ * Add properties to these interfaces to extend the generated types.
+ * The main page-props.ts file imports and uses these extensions.
+ */
+
+/**
+ * Extend the User interface with additional properties.
+ *
+ * @example
+ * export interface UserExtensions {
+ *   avatarUrl?: string | null
+ *   roles: string[]
+ *   teams: Team[]
+ * }
+ */
+export interface UserExtensions {
+  // Add your custom User properties here
+}
 
-// Re-export for module augmentation
-declare module "litestar-vite-plugin/inertia" {
-  export { User, AuthData, FlashMessages, SharedProps, GeneratedSharedProps, FullSharedProps, PageProps, ComponentName, InertiaPageProps, PagePropsFor }
+/**
+ * Extend SharedProps with session-based or dynamic properties.
+ *
+ * @example
+ * export interface SharedPropsExtensions {
+ *   locale?: string
+ *   currentTeam?: {
+ *     teamId: string
+ *     teamName: string
+ *   }
+ * }
+ */
+export interface SharedPropsExtensions {
+  // Add your custom shared props here
 }
+
+// Export custom types that can be used in page props
+// export interface CurrentTeam {
+//   teamId: string
+//   teamName: string
+// }
 `;
-  await fs.promises.writeFile(outFile, body, "utf-8");
+    await fs.promises.writeFile(userStubFile, userStub, "utf-8");
+  }
+  return result.changed;
 }
 export {
   emitPagePropsTypes