perf: tighten vite integration hot paths (#315)

## Summary

- reduce repeated work in the typegen/export, route metadata, proxy,
deploy, and handler paths
- keep SPA worker lifespan initialization on the active async event loop
- preserve custom Inertia component option keys during startup wrapping

Author: cofin

docs/changelog.rst

@@ -7,27 +7,33 @@ Notable changes to this project are documented in this file.
 Litestar Vite Changelog
 ^^^^^^^^^^^^^^^^^^^^^^^
 
-0.26.0 (unreleased)
+0.26.0 - 2026-07-05
 -------------------
 
-- Fixed Inertia asset-version mismatch handling so only ``GET`` requests can return the protocol ``409`` refresh response; non-GET submissions now continue to their handlers instead of being downgraded and losing the request body.
-- Fixed ``share()`` with Inertia redirects so top-level sync special props are materialized before session storage and async special props are skipped instead of crashing session serialization.
-- Fixed Inertia infinite-scroll ``scrollProps`` to emit a record keyed by data prop name, matching the official client protocol.
-- Fixed auto-wrapped Inertia responses so non-Inertia JSON handlers preserve Litestar's resolved ``201``/``204`` status codes while user-created ``InertiaResponse`` statuses still win.
-- Fixed Precognition validation success handling for handlers without an explicit ``request`` parameter by using the middleware request context.
-- Fixed Inertia SSR serialization so app, handler, and response type encoders are honored for custom page prop values.
-- Fixed Inertia partial reloads so ``deferredProps`` metadata is omitted on partial responses while initial responses still advertise deferred props.
+- Fixed Inertia asset-version mismatch handling so only ``GET`` requests can return the protocol ``409`` refresh response; non-GET submissions now continue to their handlers instead of being downgraded and losing the request body. (#306)
+- Fixed ``share()`` with Inertia redirects so top-level sync special props are materialized before session storage and async special props are skipped instead of crashing session serialization. (#306)
+- Fixed Inertia infinite-scroll ``scrollProps`` to emit a record keyed by data prop name, matching the official client protocol. (#306)
+- Fixed auto-wrapped Inertia responses so non-Inertia JSON handlers preserve Litestar's resolved ``201``/``204`` status codes while user-created ``InertiaResponse`` statuses still win. (#306)
+- Fixed Precognition validation success handling for handlers without an explicit ``request`` parameter by using the middleware request context. (#306)
+- Fixed Inertia SSR serialization so app, handler, and response type encoders are honored for custom page prop values. (#306)
+- Fixed Inertia partial reloads so ``deferredProps`` metadata is omitted on partial responses while initial responses still advertise deferred props. (#306)
 - Fixed ``litestar assets init`` so generated ``package.json`` files no longer emit duplicate dependency keys. (#302, #303)
 - Fixed type generation so the JS plugin resolves local ``@hey-api/openapi-ts`` installs first, uses a pinned package-manager fallback when needed, fails production builds loudly by default, and lets ``TypeGenConfig(fail_on_error=False)`` or ``types.failOnError = false`` opt out. (#311, #314)
 - Fixed type generation reliability for generated outputs by preserving queued dev regenerations, checking that expected output files exist before reusing caches, watching ``routes.json``, emitting ``static-props.ts`` from the shared CLI path, and handling semantic aliases and nested hey-api operation types. (#311, #314)
 - Fixed Vite dev-server resilience by revalidating hotfile targets by mtime, recovering after missing or replaced hotfiles, tolerating additive/corrupt bridge config files, aligning TLS certificate env vars, and preserving static-files defaults when user overrides leave fields unset. (#312, #314)
 - Fixed ``litestar assets init`` scaffold correctness for framework variants without dedicated directories, Tailwind CSS/PostCSS dependencies and entry inputs, current hey-api/TanStack/Vite template APIs, transactional writes, and non-interactive collision handling. (#313, #314)
 - Updated npm publishing to use trusted publishing with provenance and no npm token. (#314)
-- Fixed Vite dev-server lifecycle handling so unexpected exits are restarted with capped backoff and intentional shutdowns do not trigger restarts.
-- Changed SPA/proxy route-prefix fallbacks so ``/docs`` is no longer reserved unless Litestar actually registers docs there or ``RuntimeConfig.extra_route_prefixes`` includes it.
+- Fixed Vite dev-server lifecycle handling so unexpected exits are restarted with capped backoff and intentional shutdowns do not trigger restarts. (#317)
+- Changed SPA/proxy route-prefix fallbacks so ``/docs`` is no longer reserved unless Litestar actually registers docs there or ``RuntimeConfig.extra_route_prefixes`` includes it. (#317)
 - Added ``ViteConfig(enabled=...)`` and ``VITE_ENABLED`` so Vite routes and lifespans can be disabled in CLI, worker, and test contexts while keeping asset CLI commands available. (#301, #310)
-- Added ``RuntimeConfig.extra_route_prefixes`` for deliberately reserving custom backend prefixes from SPA/proxy fallbacks.
+- Added ``RuntimeConfig.extra_route_prefixes`` for deliberately reserving custom backend prefixes from SPA/proxy fallbacks. (#317)
 - Fixed ``getCsrfToken()`` so SPA and HTMX helpers can fall back to the ``csrftoken`` or ``XSRF-TOKEN`` cookie when injected page-state sources are absent. (#299, #310)
+- Hardened HTMX helper handling so dynamic ``href``, ``src``, and ``action`` attributes reject dangerous protocols and expression checks catch denied globals reconstructed through string concatenation. (#316)
+- Simplified Vite integration internals by consolidating type-config resolution, hotfile handling, proxy helpers, Inertia prop wrappers, and typing-only helper paths without removing public exports. (#316)
+- Reduced duplicate work in type generation, route metadata extraction, proxy header filtering, deploy diffing, bridge reads, placeholder probing, and Inertia response wrapping while preserving generated output paths and public behavior. (#315)
+- Fixed SPA startup so async lifespan initialization uses the async handler path and custom Inertia component option keys are preserved when startup wrappers are installed. (#315)
+- Fixed production SPA manifest resolution for Vite's default ``.vite/manifest.json`` path and recursive deploy change detection for nested bundle assets. (#315)
+- Updated Python dependencies: ``typing-extensions`` 4.16.0, ``prek`` 0.4.8, ``slotscheck`` 0.20.1, and ``coverage`` 7.15.0. (#309)
 
 0.25.0 - 2026-06-25
 -------------------

src/js/src/index.ts

@@ -1504,29 +1504,47 @@ function dirname(): string {
   return path.resolve(process.cwd(), "../dist/js")
 }
 
+let cachedDevServerPlaceholderCandidates: string[] | undefined
+let cachedDevServerPlaceholderPath: string | undefined
+
 function getDevServerPlaceholderCandidates(): string[] {
+  if (cachedDevServerPlaceholderCandidates) {
+    return cachedDevServerPlaceholderCandidates
+  }
+
   const distJsRoot = "dist/js"
   const placeholderName = "dev-server-index.html"
   const moduleDir = dirname()
 
   const candidates = [
-    path.join(dirname(), placeholderName),
+    path.join(moduleDir, placeholderName),
     path.join(process.cwd(), distJsRoot, placeholderName),
     path.join(process.cwd(), "src", "js", distJsRoot, placeholderName),
     path.resolve(process.cwd(), "..", distJsRoot, placeholderName),
     path.join(moduleDir, distJsRoot, placeholderName),
   ]
 
-  return [...new Set(candidates)]
+  cachedDevServerPlaceholderCandidates = [...new Set(candidates)]
+  return cachedDevServerPlaceholderCandidates
 }
 
 async function loadDevServerPlaceholder(): Promise<string> {
+  if (cachedDevServerPlaceholderPath) {
+    try {
+      return await fs.promises.readFile(cachedDevServerPlaceholderPath, "utf-8")
+    } catch {
+      cachedDevServerPlaceholderPath = undefined
+    }
+  }
+
   const candidates = getDevServerPlaceholderCandidates()
   let lastError: unknown = new Error("Failed to load dev server placeholder index.html")
 
   for (const candidatePath of candidates) {
     try {
-      return await fs.promises.readFile(candidatePath, "utf-8")
+      const content = await fs.promises.readFile(candidatePath, "utf-8")
+      cachedDevServerPlaceholderPath = candidatePath
+      return content
     } catch (error) {
       lastError = error
     }

src/js/src/shared/bridge-schema.ts

@@ -335,28 +335,53 @@ export function parseBridgeSchema(value: unknown): BridgeSchema {
 export function readBridgeConfig(explicitPath?: string): BridgeSchema | null {
   const envPath = explicitPath ?? process.env.LITESTAR_VITE_CONFIG_PATH
   if (envPath) {
-    if (!fs.existsSync(envPath)) {
-      return null
-    }
-    try {
-      return readBridgeConfigFile(envPath)
-    } catch (error) {
-      warn(error instanceof Error ? error.message : String(error))
-      return null
-    }
+    return readBridgeConfigFileCached(envPath)
   }
 
   const defaultPath = path.join(process.cwd(), ".litestar.json")
-  if (fs.existsSync(defaultPath)) {
-    try {
-      return readBridgeConfigFile(defaultPath)
-    } catch (error) {
-      warn(error instanceof Error ? error.message : String(error))
-      return null
+  return readBridgeConfigFileCached(defaultPath)
+}
+
+interface BridgeConfigCacheEntry {
+  mtimeMs: number
+  config: BridgeSchema | null
+}
+
+const bridgeConfigCache = new Map<string, BridgeConfigCacheEntry>()
+
+function readBridgeConfigFileCached(filePath: string): BridgeSchema | null {
+  const resolvedPath = path.resolve(filePath)
+  if (!fs.existsSync(resolvedPath)) {
+    return null
+  }
+
+  let mtimeMs: number | null = null
+  try {
+    mtimeMs = fs.statSync(resolvedPath).mtimeMs
+  } catch {
+    mtimeMs = null
+  }
+
+  if (mtimeMs !== null) {
+    const cached = bridgeConfigCache.get(resolvedPath)
+    if (cached?.mtimeMs === mtimeMs) {
+      return cached.config
     }
   }
 
-  return null
+  try {
+    const config = readBridgeConfigFile(resolvedPath)
+    if (mtimeMs !== null) {
+      bridgeConfigCache.set(resolvedPath, { mtimeMs, config })
+    }
+    return config
+  } catch (error) {
+    warn(error instanceof Error ? error.message : String(error))
+    if (mtimeMs !== null) {
+      bridgeConfigCache.set(resolvedPath, { mtimeMs, config: null })
+    }
+    return null
+  }
 }
 
 function readBridgeConfigFile(filePath: string): BridgeSchema {

src/js/src/shared/typegen-plugin.ts

@@ -341,6 +341,10 @@ export function createLitestarTypeGenPlugin(typesConfig: RequiredTypeGenConfig,
     },
 
     async buildStart() {
+      if (resolvedConfig?.command === "build" && process.env.LITESTAR_VITE_SKIP_BUILD_TYPEGEN === "1") {
+        return
+      }
+
       if (typesConfig.enabled && hasPythonConfig === false) {
         const projectRoot = resolvedConfig?.root ?? process.cwd()
         const openapiPath = path.resolve(projectRoot, typesConfig.openapiPath)

src/js/tests/index.test.ts

@@ -1539,6 +1539,26 @@ describe("litestar-vite-plugin", () => {
       expect(mockNext).not.toHaveBeenCalled()
     })
 
+    it("caches placeholder path probing across placeholder responses", async () => {
+      const appUrl = "http://test.app"
+      process.env.APP_URL = appUrl
+      await setupServer()
+      mockFs(null)
+
+      const existsSpy = vi.spyOn(fs, "existsSync")
+
+      await mockMiddleware({ url: "/index.html", originalUrl: "/index.html" }, mockRes, mockNext)
+      const firstProbeCount = existsSpy.mock.calls.filter(([candidate]) => String(candidate).endsWith("dev-server-index.html")).length
+
+      mockRes.end.mockClear()
+      await mockMiddleware({ url: "/", originalUrl: "/" }, mockRes, mockNext)
+      const totalProbeCount = existsSpy.mock.calls.filter(([candidate]) => String(candidate).endsWith("dev-server-index.html")).length
+
+      expect(totalProbeCount).toBe(firstProbeCount)
+      expect(mockRes.end).toHaveBeenCalledWith(actualPlaceholderContent.replace(/{{ APP_URL }}/g, appUrl))
+      expect(mockNext).not.toHaveBeenCalled()
+    })
+
     it("serves placeholder when index.html is not detected and url is /", async () => {
       // When no index.html exists (hybrid/inertia mode), serve the placeholder at root
       // This helps users who accidentally navigate to the Vite dev server port

src/js/tests/shared/bridge-schema.test.ts

@@ -1,7 +1,7 @@
 import fs from "node:fs"
 import os from "node:os"
 import path from "node:path"
-import { describe, expect, it } from "vitest"
+import { describe, expect, it, vi } from "vitest"
 import { parseBridgeSchema, readBridgeConfig } from "../../src/shared/bridge-schema"
 
 const baseBridgeConfig = {
@@ -98,6 +98,29 @@ describe("bridge schema additive fields", () => {
       fs.rmSync(tmpDir, { recursive: true, force: true })
     }
   })
+
+  it("memoizes bridge file reads until path mtime changes", () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "litestar-bridge-"))
+    const configPath = path.join(tmpDir, ".litestar.json")
+    fs.writeFileSync(configPath, JSON.stringify(baseBridgeConfig))
+    const readSpy = vi.spyOn(fs, "readFileSync")
+
+    try {
+      expect(readBridgeConfig(configPath)?.port).toBe(5173)
+      expect(readBridgeConfig(configPath)?.port).toBe(5173)
+      expect(readSpy).toHaveBeenCalledTimes(1)
+
+      fs.writeFileSync(configPath, JSON.stringify({ ...baseBridgeConfig, port: 5174 }))
+      const mtime = new Date(Date.now() + 1000)
+      fs.utimesSync(configPath, mtime, mtime)
+
+      expect(readBridgeConfig(configPath)?.port).toBe(5174)
+      expect(readSpy).toHaveBeenCalledTimes(2)
+    } finally {
+      readSpy.mockRestore()
+      fs.rmSync(tmpDir, { recursive: true, force: true })
+    }
+  })
 })
 
 describe("bridge schema typegen failOnError", () => {

src/js/tests/shared/typegen-plugin.test.ts

@@ -180,6 +180,23 @@ describe("createLitestarTypeGenPlugin", () => {
     expect(context.error).not.toHaveBeenCalled()
   })
 
+  it("skips buildStart generation when Python assets build already ran typegen", async () => {
+    process.env.LITESTAR_VITE_SKIP_BUILD_TYPEGEN = "1"
+    const plugin = createPlugin()
+    plugin.configResolved?.(createResolvedConfig("build") as never)
+    const context = { error: vi.fn(), warn: vi.fn() }
+
+    try {
+      await plugin.buildStart?.call(context as never)
+    } finally {
+      delete process.env.LITESTAR_VITE_SKIP_BUILD_TYPEGEN
+    }
+
+    expect(mocks.runTypeGeneration).not.toHaveBeenCalled()
+    expect(context.error).not.toHaveBeenCalled()
+    expect(context.warn).not.toHaveBeenCalled()
+  })
+
   it("reruns once when a change arrives during active generation", async () => {
     let resolveFirst: (value: unknown) => void = () => undefined
     const firstRun = new Promise((resolve) => {

src/py/litestar_vite/cli.py

@@ -48,6 +48,20 @@
 ]
 
 
+@contextlib.contextmanager
+def _temporary_env_var(name: str, value: str) -> "Any":
+    """Temporarily set an environment variable."""
+    previous = os.environ.get(name)
+    os.environ[name] = value
+    try:
+        yield
+    finally:
+        if previous is None:
+            os.environ.pop(name, None)
+        else:
+            os.environ[name] = previous
+
+
 def _format_command(command: "list[str] | None") -> str:
     """Join a command list for display.
 
@@ -218,13 +232,19 @@ def _prepare_and_build(config: ViteConfig, root_dir: Path, console: Any, app: "L
         set_environment(config=config)
     os.environ.setdefault("VITE_BASE_URL", config.base_url or "/")
 
-    ext = config.runtime.external_dev_server
-    if isinstance(ext, ExternalDevServer) and ext.enabled:
-        build_cmd = ext.build_command or config.executor.build_command
-        console.print(f"[dim]Running external build: {' '.join(build_cmd)}[/]")
-        config.executor.execute(build_cmd, cwd=root_dir)
-    else:
-        config.executor.execute(config.build_command, cwd=root_dir)
+    env_manager = (
+        _temporary_env_var("LITESTAR_VITE_SKIP_BUILD_TYPEGEN", "1")
+        if generated_assets and isinstance(config.types, TypeGenConfig)
+        else contextlib.nullcontext()
+    )
+    with env_manager:
+        ext = config.runtime.external_dev_server
+        if isinstance(ext, ExternalDevServer) and ext.enabled:
+            build_cmd = ext.build_command or config.executor.build_command
+            console.print(f"[dim]Running external build: {' '.join(build_cmd)}[/]")
+            config.executor.execute(build_cmd, cwd=root_dir)
+        else:
+            config.executor.execute(config.build_command, cwd=root_dir)
 
 
 def _run_vite_build(

src/py/litestar_vite/codegen/__init__.py

@@ -10,7 +10,7 @@
 are kept in private submodules to keep the public API clean.
 """
 
-from litestar_vite.codegen._export import ExportResult, export_integration_assets
+from litestar_vite.codegen._export import ExportResult, export_integration_assets, typegen_outputs_requested
 from litestar_vite.codegen._inertia import (
     InertiaPageMetadata,
     extract_inertia_pages,
@@ -44,5 +44,6 @@
     "generate_routes_json",
     "generate_routes_ts",
     "strip_timestamp_for_comparison",
+    "typegen_outputs_requested",
     "write_if_changed",
 )