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

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/index.d.ts

@@ -6,23 +6,33 @@
  *
  * @example
  * ```ts
+ * // CSRF utilities
  * import { getCsrfToken, csrfFetch } from 'litestar-vite-plugin/helpers'
  *
- * // Get CSRF token
  * const token = getCsrfToken()
+ * await csrfFetch('/api/submit', { method: 'POST', body: JSON.stringify(data) })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Route matching utilities
+ * import { createRouteHelpers } from 'litestar-vite-plugin/helpers'
+ * import { routeDefinitions } from '@/generated/routes'
  *
- * // Make a fetch request with CSRF token
- * await csrfFetch('/api/submit', {
- *   method: 'POST',
- *   body: JSON.stringify(data),
- * })
+ * const { isCurrentRoute, currentRoute, toRoute, isRoute } = createRouteHelpers(routeDefinitions)
+ *
+ * // Highlight active nav items
+ * if (isCurrentRoute('dashboard')) { ... }
+ *
+ * // Match with wildcards
+ * if (isCurrentRoute('book_*')) { ... }
  * ```
  *
- * For type-safe routing, import from your generated routes file:
+ * @example
  * ```ts
- * import { route, routeDefinitions, type RouteName } from '@/generated/routes'
+ * // Type-safe URL generation (from generated routes)
+ * import { route } from '@/generated/routes'
  *
- * // Type-safe URL generation
  * const url = route('user_detail', { user_id: 123 })  // Compile-time checked!
  * ```
  *
@@ -30,3 +40,4 @@
  */
 export { csrfFetch, csrfHeaders, getCsrfToken } from "./csrf.js";
 export { addDirective, registerHtmxExtension, setDebug as setHtmxDebug, swapJson } from "./htmx.js";
+export { createRouteHelpers, currentRoute, isCurrentRoute, isRoute, type RouteDefinition, type RouteDefinitions, type RouteHelpers, toRoute, } from "./routes.js";

package/dist/js/helpers/index.js

@@ -6,23 +6,33 @@
  *
  * @example
  * ```ts
+ * // CSRF utilities
  * import { getCsrfToken, csrfFetch } from 'litestar-vite-plugin/helpers'
  *
- * // Get CSRF token
  * const token = getCsrfToken()
+ * await csrfFetch('/api/submit', { method: 'POST', body: JSON.stringify(data) })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Route matching utilities
+ * import { createRouteHelpers } from 'litestar-vite-plugin/helpers'
+ * import { routeDefinitions } from '@/generated/routes'
  *
- * // Make a fetch request with CSRF token
- * await csrfFetch('/api/submit', {
- *   method: 'POST',
- *   body: JSON.stringify(data),
- * })
+ * const { isCurrentRoute, currentRoute, toRoute, isRoute } = createRouteHelpers(routeDefinitions)
+ *
+ * // Highlight active nav items
+ * if (isCurrentRoute('dashboard')) { ... }
+ *
+ * // Match with wildcards
+ * if (isCurrentRoute('book_*')) { ... }
  * ```
  *
- * For type-safe routing, import from your generated routes file:
+ * @example
  * ```ts
- * import { route, routeDefinitions, type RouteName } from '@/generated/routes'
+ * // Type-safe URL generation (from generated routes)
+ * import { route } from '@/generated/routes'
  *
- * // Type-safe URL generation
  * const url = route('user_detail', { user_id: 123 })  // Compile-time checked!
  * ```
  *
@@ -32,3 +42,5 @@
 export { csrfFetch, csrfHeaders, getCsrfToken } from "./csrf.js";
 // HTMX utilities
 export { addDirective, registerHtmxExtension, setDebug as setHtmxDebug, swapJson } from "./htmx.js";
+// Route matching utilities
+export { createRouteHelpers, currentRoute, isCurrentRoute, isRoute, toRoute, } from "./routes.js";

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

@@ -0,0 +1,138 @@
+/**
+ * Route matching utilities for Litestar applications.
+ *
+ * These helpers work with the generated `routeDefinitions` from your routes.ts file
+ * to provide runtime route matching capabilities.
+ *
+ * **IMPORTANT**: This file serves as both the runtime library AND the reference
+ * implementation for the Python code generator. The same logic is also generated
+ * inline in `routes.ts` by `src/py/litestar_vite/_codegen/routes.py`.
+ *
+ * **If you modify the logic here, you MUST also update the Python generator!**
+ *
+ * @example
+ * ```ts
+ * import { routeDefinitions } from '@/generated/routes'
+ * import { createRouteHelpers } from 'litestar-vite-plugin/helpers'
+ *
+ * const { isCurrentRoute, currentRoute, toRoute, isRoute } = createRouteHelpers(routeDefinitions)
+ *
+ * // Check if current URL matches a route
+ * if (isCurrentRoute('dashboard')) {
+ *   // highlight nav item
+ * }
+ * ```
+ *
+ * @module
+ */
+/**
+ * Route definition structure from generated routes.
+ */
+export interface RouteDefinition {
+    path: string;
+    methods: readonly string[];
+    method: string;
+    pathParams: readonly string[];
+    queryParams: readonly string[];
+    component?: string;
+}
+/**
+ * Map of route names to their definitions.
+ */
+export type RouteDefinitions = Record<string, RouteDefinition>;
+/**
+ * Convert a URL to its corresponding route name.
+ *
+ * @param url - URL or path to match (query strings and hashes are stripped)
+ * @param routes - The routeDefinitions object from generated routes
+ * @returns The matching route name, or null if no match found
+ *
+ * @example
+ * toRoute('/api/books', routeDefinitions)        // 'books'
+ * toRoute('/api/books/123', routeDefinitions)    // 'book_detail'
+ * toRoute('/unknown', routeDefinitions)          // null
+ */
+export declare function toRoute<T extends string>(url: string, routes: Record<T, RouteDefinition>): T | null;
+/**
+ * Get the current route name based on the browser URL.
+ *
+ * Returns null in SSR/non-browser environments.
+ *
+ * @param routes - The routeDefinitions object from generated routes
+ * @returns Current route name, or null if no match or not in browser
+ *
+ * @example
+ * // On page /api/books/123
+ * currentRoute(routeDefinitions)  // 'book_detail'
+ */
+export declare function currentRoute<T extends string>(routes: Record<T, RouteDefinition>): T | null;
+/**
+ * Check if a URL matches a route name or pattern.
+ *
+ * Supports wildcard patterns with `*` to match multiple routes.
+ *
+ * @param url - URL or path to check
+ * @param pattern - Route name or pattern (e.g., 'books', 'book_*', '*_detail')
+ * @param routes - The routeDefinitions object from generated routes
+ * @returns True if the URL matches the route pattern
+ *
+ * @example
+ * isRoute('/api/books', 'books', routeDefinitions)           // true
+ * isRoute('/api/books/123', 'book_detail', routeDefinitions) // true
+ * isRoute('/api/books/123', 'book_*', routeDefinitions)      // true (wildcard)
+ * isRoute('/api/users', 'book_*', routeDefinitions)          // false
+ */
+export declare function isRoute<T extends string>(url: string, pattern: string, routes: Record<T, RouteDefinition>): boolean;
+/**
+ * Check if the current browser URL matches a route name or pattern.
+ *
+ * Supports wildcard patterns with `*` to match multiple routes.
+ * Returns false in SSR/non-browser environments.
+ *
+ * @param pattern - Route name or pattern (e.g., 'books', 'book_*', '*_page')
+ * @param routes - The routeDefinitions object from generated routes
+ * @returns True if current URL matches the route pattern
+ *
+ * @example
+ * // On page /books
+ * isCurrentRoute('books_page', routeDefinitions)  // true
+ * isCurrentRoute('book_*', routeDefinitions)      // false (no match)
+ * isCurrentRoute('*_page', routeDefinitions)      // true (wildcard)
+ */
+export declare function isCurrentRoute<T extends string>(pattern: string, routes: Record<T, RouteDefinition>): boolean;
+/**
+ * Route helpers interface returned by createRouteHelpers.
+ */
+export interface RouteHelpers<T extends string> {
+    /** Convert URL to route name */
+    toRoute: (url: string) => T | null;
+    /** Get current route name (SSR-safe) */
+    currentRoute: () => T | null;
+    /** Check if URL matches route pattern */
+    isRoute: (url: string, pattern: string) => boolean;
+    /** Check if current URL matches route pattern */
+    isCurrentRoute: (pattern: string) => boolean;
+}
+/**
+ * Create route helpers bound to a specific routeDefinitions object.
+ *
+ * This is the recommended way to use route helpers - it creates bound functions
+ * so you don't need to pass routeDefinitions to every call.
+ *
+ * @param routes - The routeDefinitions object from your generated routes
+ * @returns Object with bound route helper functions
+ *
+ * @example
+ * ```ts
+ * import { routeDefinitions } from '@/generated/routes'
+ * import { createRouteHelpers } from 'litestar-vite-plugin/helpers'
+ *
+ * export const { isCurrentRoute, currentRoute, toRoute, isRoute } = createRouteHelpers(routeDefinitions)
+ *
+ * // Now use without passing routes:
+ * if (isCurrentRoute('dashboard')) {
+ *   // ...
+ * }
+ * ```
+ */
+export declare function createRouteHelpers<T extends string>(routes: Record<T, RouteDefinition>): RouteHelpers<T>;

package/dist/js/helpers/routes.js

@@ -0,0 +1,181 @@
+/**
+ * Route matching utilities for Litestar applications.
+ *
+ * These helpers work with the generated `routeDefinitions` from your routes.ts file
+ * to provide runtime route matching capabilities.
+ *
+ * **IMPORTANT**: This file serves as both the runtime library AND the reference
+ * implementation for the Python code generator. The same logic is also generated
+ * inline in `routes.ts` by `src/py/litestar_vite/_codegen/routes.py`.
+ *
+ * **If you modify the logic here, you MUST also update the Python generator!**
+ *
+ * @example
+ * ```ts
+ * import { routeDefinitions } from '@/generated/routes'
+ * import { createRouteHelpers } from 'litestar-vite-plugin/helpers'
+ *
+ * const { isCurrentRoute, currentRoute, toRoute, isRoute } = createRouteHelpers(routeDefinitions)
+ *
+ * // Check if current URL matches a route
+ * if (isCurrentRoute('dashboard')) {
+ *   // highlight nav item
+ * }
+ * ```
+ *
+ * @module
+ */
+/** Cache for compiled route patterns */
+const patternCache = new Map();
+/**
+ * Compile a route path pattern to a regex for URL matching.
+ * Results are cached for performance.
+ *
+ * @param path - Route path with {param} placeholders
+ * @returns Compiled regex pattern
+ */
+function compilePattern(path) {
+    const cached = patternCache.get(path);
+    if (cached)
+        return cached;
+    // Escape special regex characters except { }
+    let pattern = path.replace(/[.*+?^$|()[\]]/g, "\\$&");
+    // Replace {param} or {param:type} with matchers
+    pattern = pattern.replace(/\{([^}]+)\}/g, (_match, paramSpec) => {
+        const paramType = paramSpec.includes(":") ? paramSpec.split(":")[1] : "str";
+        switch (paramType) {
+            case "uuid":
+                return "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}";
+            case "path":
+                return ".*";
+            case "int":
+                return "\\d+";
+            default:
+                return "[^/]+";
+        }
+    });
+    const regex = new RegExp(`^${pattern}$`, "i");
+    patternCache.set(path, regex);
+    return regex;
+}
+/**
+ * Convert a URL to its corresponding route name.
+ *
+ * @param url - URL or path to match (query strings and hashes are stripped)
+ * @param routes - The routeDefinitions object from generated routes
+ * @returns The matching route name, or null if no match found
+ *
+ * @example
+ * toRoute('/api/books', routeDefinitions)        // 'books'
+ * toRoute('/api/books/123', routeDefinitions)    // 'book_detail'
+ * toRoute('/unknown', routeDefinitions)          // null
+ */
+export function toRoute(url, routes) {
+    // Strip query string and hash
+    const path = url.split("?")[0].split("#")[0];
+    // Normalize: remove trailing slash except for root
+    const normalized = path === "/" ? path : path.replace(/\/$/, "");
+    for (const [name, def] of Object.entries(routes)) {
+        if (compilePattern(def.path).test(normalized)) {
+            return name;
+        }
+    }
+    return null;
+}
+/**
+ * Get the current route name based on the browser URL.
+ *
+ * Returns null in SSR/non-browser environments.
+ *
+ * @param routes - The routeDefinitions object from generated routes
+ * @returns Current route name, or null if no match or not in browser
+ *
+ * @example
+ * // On page /api/books/123
+ * currentRoute(routeDefinitions)  // 'book_detail'
+ */
+export function currentRoute(routes) {
+    if (typeof window === "undefined")
+        return null;
+    return toRoute(window.location.pathname, routes);
+}
+/**
+ * Check if a URL matches a route name or pattern.
+ *
+ * Supports wildcard patterns with `*` to match multiple routes.
+ *
+ * @param url - URL or path to check
+ * @param pattern - Route name or pattern (e.g., 'books', 'book_*', '*_detail')
+ * @param routes - The routeDefinitions object from generated routes
+ * @returns True if the URL matches the route pattern
+ *
+ * @example
+ * isRoute('/api/books', 'books', routeDefinitions)           // true
+ * isRoute('/api/books/123', 'book_detail', routeDefinitions) // true
+ * isRoute('/api/books/123', 'book_*', routeDefinitions)      // true (wildcard)
+ * isRoute('/api/users', 'book_*', routeDefinitions)          // false
+ */
+export function isRoute(url, pattern, routes) {
+    const routeName = toRoute(url, routes);
+    if (!routeName)
+        return false;
+    // Escape special regex chars (except *), then convert * to .*
+    const escaped = pattern.replace(/[.+?^$|()[\]{}]/g, "\\$&");
+    const regex = new RegExp(`^${escaped.replace(/\*/g, ".*")}$`);
+    return regex.test(routeName);
+}
+/**
+ * Check if the current browser URL matches a route name or pattern.
+ *
+ * Supports wildcard patterns with `*` to match multiple routes.
+ * Returns false in SSR/non-browser environments.
+ *
+ * @param pattern - Route name or pattern (e.g., 'books', 'book_*', '*_page')
+ * @param routes - The routeDefinitions object from generated routes
+ * @returns True if current URL matches the route pattern
+ *
+ * @example
+ * // On page /books
+ * isCurrentRoute('books_page', routeDefinitions)  // true
+ * isCurrentRoute('book_*', routeDefinitions)      // false (no match)
+ * isCurrentRoute('*_page', routeDefinitions)      // true (wildcard)
+ */
+export function isCurrentRoute(pattern, routes) {
+    const current = currentRoute(routes);
+    if (!current)
+        return false;
+    // Escape special regex chars (except *), then convert * to .*
+    const escaped = pattern.replace(/[.+?^$|()[\]{}]/g, "\\$&");
+    const regex = new RegExp(`^${escaped.replace(/\*/g, ".*")}$`);
+    return regex.test(current);
+}
+/**
+ * Create route helpers bound to a specific routeDefinitions object.
+ *
+ * This is the recommended way to use route helpers - it creates bound functions
+ * so you don't need to pass routeDefinitions to every call.
+ *
+ * @param routes - The routeDefinitions object from your generated routes
+ * @returns Object with bound route helper functions
+ *
+ * @example
+ * ```ts
+ * import { routeDefinitions } from '@/generated/routes'
+ * import { createRouteHelpers } from 'litestar-vite-plugin/helpers'
+ *
+ * export const { isCurrentRoute, currentRoute, toRoute, isRoute } = createRouteHelpers(routeDefinitions)
+ *
+ * // Now use without passing routes:
+ * if (isCurrentRoute('dashboard')) {
+ *   // ...
+ * }
+ * ```
+ */
+export function createRouteHelpers(routes) {
+    return {
+        toRoute: (url) => toRoute(url, routes),
+        currentRoute: () => currentRoute(routes),
+        isRoute: (url, pattern) => isRoute(url, pattern, routes),
+        isCurrentRoute: (pattern) => isCurrentRoute(pattern, routes),
+    };
+}

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)");
+        }
       });
     }
   };
@@ -510,11 +567,13 @@ function resolvePluginConfig(config) {
       typesConfig.pagePropsPath = path.join(typesConfig.output, "inertia-pages.json");
     }
   }
-  const inertiaMode = resolvedConfig.inertiaMode ?? pythonDefaults?.mode === "inertia";
+  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) {