litestar-vite-plugin 0.15.0-alpha.3 → 0.15.0-alpha.4

package/README.md

@@ -10,66 +10,83 @@ Litestar Vite connects the Litestar backend to a Vite toolchain. It supports SPA
 - 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.
 
-## Quick start (React TanStack SPA)
+## Quick Start (SPA)
 
 ```bash
 pip install litestar-vite
-litestar assets init --template react-tanstack
-litestar assets install  # installs frontend deps via configured executor
 ```
 
 ```python
+import os
+from pathlib import Path
 from litestar import Litestar
-from litestar_vite import VitePlugin, ViteConfig
+from litestar_vite import VitePlugin, ViteConfig, PathConfig
+
+DEV_MODE = os.getenv("VITE_DEV_MODE", "true").lower() in ("true", "1", "yes")
 
-app = Litestar(plugins=[VitePlugin(config=ViteConfig(dev_mode=True))])  # SPA mode by default
+app = Litestar(
+    plugins=[VitePlugin(config=ViteConfig(
+        dev_mode=DEV_MODE,
+        paths=PathConfig(root=Path(__file__).parent),
+    ))]
+)
 ```
 
 ```bash
-litestar run --reload  # starts Litestar; Vite dev is proxied automatically
+litestar run --reload  # Vite dev server is proxied automatically
 ```
 
-Other templates: `react`, `vue`, `svelte`, `htmx`, `react-inertia`, `vue-inertia`, `svelte-inertia`, `angular`, `angular-cli`, `astro`, `nuxt`, `sveltekit` (see `litestar assets init --help`).
+Scaffold a frontend: `litestar assets init --template vue` (or `react`, `svelte`, `htmx`, `react-inertia`, `vue-inertia`, `angular`, `astro`, `nuxt`, `sveltekit`).
 
 ## Template / HTMX
 
 ```python
+from pathlib import Path
 from litestar import Litestar
 from litestar.contrib.jinja import JinjaTemplateEngine
-from litestar.template.config import TemplateConfig
-from litestar_vite import VitePlugin, ViteConfig
+from litestar.template import TemplateConfig
+from litestar_vite import VitePlugin, ViteConfig, PathConfig
+
+here = Path(__file__).parent
 
 app = Litestar(
-    template_config=TemplateConfig(engine=JinjaTemplateEngine(directory="templates")),
-    plugins=[VitePlugin(config=ViteConfig(mode="template", dev_mode=True))],
+    template_config=TemplateConfig(directory=here / "templates", engine=JinjaTemplateEngine),
+    plugins=[VitePlugin(config=ViteConfig(
+        dev_mode=True,
+        paths=PathConfig(root=here),
+    ))],
 )
 ```
 
 ## Inertia (v2)
 
-Requires session middleware.
+Requires session middleware (32-char secret).
 
 ```python
+import os
+from pathlib import Path
 from litestar import Litestar
 from litestar.middleware.session.client_side import CookieBackendConfig
-from litestar_vite import VitePlugin, ViteConfig
-from litestar_vite.inertia import InertiaPlugin
-from litestar_vite.inertia.config import InertiaConfig
+from litestar_vite import VitePlugin, ViteConfig, PathConfig
+from litestar_vite.inertia import InertiaConfig
 
-session_backend = CookieBackendConfig(secret="dev-secret")
+here = Path(__file__).parent
+SECRET_KEY = os.environ.get("SECRET_KEY", "development-only-secret-32-chars")
+session = CookieBackendConfig(secret=SECRET_KEY.encode("utf-8"))
 
 app = Litestar(
-    middleware=[session_backend.middleware],
-    plugins=[
-        VitePlugin(config=ViteConfig(mode="template", inertia=True, dev_mode=True)),
-        InertiaPlugin(InertiaConfig()),
-    ],
+    middleware=[session.middleware],
+    plugins=[VitePlugin(config=ViteConfig(
+        dev_mode=True,
+        paths=PathConfig(root=here),
+        inertia=InertiaConfig(root_template="index.html"),
+    ))],
 )
 ```
 
-## SSR Frameworks (Astro, Nuxt, SvelteKit)
+## Meta-frameworks (Astro, Nuxt, SvelteKit)
 
-For SSR frameworks that handle their own routing, use `proxy_mode="ssr"`:
+Use `proxy_mode="ssr"` to proxy non-API routes to the framework's dev server:
 
 ```python
 import os
@@ -77,17 +94,15 @@ from pathlib import Path
 from litestar import Litestar
 from litestar_vite import VitePlugin, ViteConfig, PathConfig, RuntimeConfig
 
+here = Path(__file__).parent
 DEV_MODE = os.getenv("VITE_DEV_MODE", "true").lower() in ("true", "1", "yes")
 
 app = Litestar(
     plugins=[
         VitePlugin(config=ViteConfig(
             dev_mode=DEV_MODE,
-            paths=PathConfig(root=Path(__file__).parent),
-            runtime=RuntimeConfig(
-                proxy_mode="ssr" if DEV_MODE else None,  # Proxy in dev, static in prod
-                spa_handler=not DEV_MODE,  # Serve built files in production
-            ),
+            paths=PathConfig(root=here),
+            runtime=RuntimeConfig(proxy_mode="ssr"),
         ))
     ],
 )
@@ -99,29 +114,28 @@ app = Litestar(
 |------|-------|----------|
 | `vite` | - | SPAs - proxies Vite assets only (default) |
 | `direct` | - | Two-port dev - expose Vite port directly |
-| `proxy` | `ssr` | SSR frameworks - proxies everything except API routes |
+| `proxy` | `ssr` | Meta-frameworks - proxies everything except API routes |
 
 ### Production Deployment
 
-**Static Build (recommended):** Build your SSR framework to static files, then serve with Litestar:
+**Astro (static):** Astro generates static HTML by default. Build and serve with Litestar:
 
 ```bash
-# Build frontend
-cd examples/astro && npm run build
-
-# Run in production mode
+litestar --app-dir examples/astro assets install
+litestar --app-dir examples/astro assets build
 VITE_DEV_MODE=false litestar --app-dir examples/astro run
 ```
 
-Configure `bundle_dir` to match your framework's build output:
+**Nuxt/SvelteKit (SSR):** These run their own Node servers. Deploy as two services:
 
-| Framework | Default Output | PathConfig |
-|-----------|---------------|------------|
-| Astro | `dist/` | `bundle_dir=Path("dist")` |
-| Nuxt | `.output/public/` | `bundle_dir=Path(".output/public")` |
-| SvelteKit | `build/` | `bundle_dir=Path("build")` |
+```bash
+# Terminal 1: SSR server
+litestar --app-dir examples/nuxt assets build
+litestar --app-dir examples/nuxt assets serve
 
-**Two-Service:** For dynamic SSR, run the Node server alongside Litestar behind a reverse proxy.
+# Terminal 2: Litestar API
+VITE_DEV_MODE=false litestar --app-dir examples/nuxt run --port 8001
+```
 
 ## Type generation
 
@@ -151,5 +165,5 @@ litestar assets generate-types  # one-off or CI
 ## Links
 
 - Docs: <https://litestar-org.github.io/litestar-vite/>
-- Examples: `examples/` (basic, inertia, react)
+- Examples: `examples/` (react, vue, svelte, react-inertia, vue-inertia, astro, nuxt, sveltekit, htmx)
 - Issues: <https://github.com/litestar-org/litestar-vite/issues/>

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

@@ -20,5 +20,5 @@
  *
  * @module
  */
-export { getCsrfToken, csrfHeaders, csrfFetch } from "./csrf.js";
-export { route, getRoutes, toRoute, currentRoute, isRoute, isCurrentRoute, getRelativeUrlPath, LITESTAR, type RouteDefinition, type RoutesMap, type LitestarHelpers, } from "./routes.js";
+export { csrfFetch, csrfHeaders, getCsrfToken } from "./csrf.js";
+export { currentRoute, getRelativeUrlPath, getRoutes, isCurrentRoute, isRoute, LITESTAR, type LitestarHelpers, type RouteDefinition, type RoutesMap, route, toRoute, } from "./routes.js";

package/dist/js/helpers/index.js

@@ -21,6 +21,6 @@
  * @module
  */
 // CSRF utilities
-export { getCsrfToken, csrfHeaders, csrfFetch } from "./csrf.js";
+export { csrfFetch, csrfHeaders, getCsrfToken } from "./csrf.js";
 // Route utilities
-export { route, getRoutes, toRoute, currentRoute, isRoute, isCurrentRoute, getRelativeUrlPath, LITESTAR, } from "./routes.js";
+export { currentRoute, getRelativeUrlPath, getRoutes, isCurrentRoute, isRoute, LITESTAR, route, toRoute, } from "./routes.js";

package/dist/js/index.d.ts

@@ -1,4 +1,3 @@
-import { type ConfigEnv, type Plugin, type UserConfig } from "vite";
 import { type Config as FullReloadConfig } from "vite-plugin-full-reload";
 /**
  * Configuration for TypeScript type generation.
@@ -162,15 +161,13 @@ interface RefreshConfig {
     paths: string[];
     config?: FullReloadConfig;
 }
-interface LitestarPlugin extends Plugin {
-    config: (config: UserConfig, env: ConfigEnv) => UserConfig;
-}
 type DevServerUrl = `${"http" | "https"}://${string}:${number}`;
 export declare const refreshPaths: string[];
 /**
  * Litestar plugin for Vite.
  *
  * @param config - A config object or relative path(s) of the scripts to be compiled.
+ * @returns An array of Vite plugins. Return type is `any[]` to avoid cross-version type conflicts.
  */
-export default function litestar(config: string | string[] | PluginConfig): [LitestarPlugin, ...Plugin[]];
+export default function litestar(config: string | string[] | PluginConfig): any[];
 export {};

package/dist/js/index.js

@@ -42,7 +42,7 @@ async function findIndexHtmlPath(server, pluginConfig) {
   }
   return null;
 }
-function normalizeAppUrl(appUrl, fallbackPort) {
+function normalizeAppUrl(appUrl, _fallbackPort) {
   if (!appUrl || appUrl === "__litestar_app_url_missing__") {
     return { url: null, note: "APP_URL missing" };
   }
@@ -160,7 +160,7 @@ function resolveLitestarPlugin(pluginConfig) {
       const hint = pluginConfig.types !== false ? pluginConfig.types.routesPath : void 0;
       litestarMeta = await loadLitestarMeta(resolvedConfig, hint);
     },
-    transform(code, id) {
+    transform(code, _id) {
       if (resolvedConfig.command === "serve" && code.includes("__litestar_vite_placeholder__")) {
         const transformedCode = code.replace(/__litestar_vite_placeholder__/g, viteDevServerUrl);
         return pluginConfig.transformOnServe(transformedCode, viteDevServerUrl);
@@ -304,7 +304,7 @@ function ensureCommandShouldRunInEnvironment(command, env) {
     );
   }
 }
-function pluginVersion() {
+function _pluginVersion() {
   try {
     return JSON.parse(fs.readFileSync(path.join(dirname(), "../package.json")).toString())?.version;
   } catch {
@@ -375,8 +375,8 @@ function resolvePluginConfig(config) {
       debounce: 300
     };
   } else if (typeof resolvedConfig.types === "object" && resolvedConfig.types !== null) {
-    const userProvidedOpenapi = Object.prototype.hasOwnProperty.call(resolvedConfig.types, "openapiPath");
-    const userProvidedRoutes = Object.prototype.hasOwnProperty.call(resolvedConfig.types, "routesPath");
+    const userProvidedOpenapi = Object.hasOwn(resolvedConfig.types, "openapiPath");
+    const userProvidedRoutes = Object.hasOwn(resolvedConfig.types, "routesPath");
     typesConfig = {
       enabled: resolvedConfig.types.enabled ?? true,
       output: resolvedConfig.types.output ?? "src/generated/types",
@@ -409,7 +409,7 @@ function resolvePluginConfig(config) {
     executor: resolvedConfig.executor ?? pythonDefaults?.executor
   };
 }
-function resolveBase(config, assetUrl) {
+function resolveBase(_config, assetUrl) {
   if (process.env.NODE_ENV === "development") {
     return assetUrl;
   }

package/dist/js/inertia-helpers/index.d.ts

@@ -6,7 +6,7 @@
  *
  * @module
  */
-export { getCsrfToken, csrfHeaders, csrfFetch, route, getRoutes, toRoute, currentRoute, isRoute, isCurrentRoute, getRelativeUrlPath, type RouteDefinition, type RoutesMap, } from "litestar-vite-plugin/helpers";
+export { csrfFetch, csrfHeaders, currentRoute, getCsrfToken, getRelativeUrlPath, getRoutes, isCurrentRoute, isRoute, type RouteDefinition, type RoutesMap, route, toRoute, } from "litestar-vite-plugin/helpers";
 /**
  * Unwrap page props that may have content nested under "content" key.
  *

package/dist/js/inertia-helpers/index.js

@@ -8,11 +8,11 @@
  */
 // Re-export all helpers from the main helpers module
 // Note: Using package path instead of relative import to ensure proper build output structure
-export { 
+export { csrfFetch, csrfHeaders, currentRoute, 
 // CSRF utilities
-getCsrfToken, csrfHeaders, csrfFetch, 
+getCsrfToken, getRelativeUrlPath, getRoutes, isCurrentRoute, isRoute, 
 // Route utilities
-route, getRoutes, toRoute, currentRoute, isRoute, isCurrentRoute, getRelativeUrlPath, } from "litestar-vite-plugin/helpers";
+route, toRoute, } from "litestar-vite-plugin/helpers";
 /**
  * Unwrap page props that may have content nested under "content" key.
  *

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "litestar-vite-plugin",
-  "version": "0.15.0-alpha.3",
+  "version": "0.15.0-alpha.4",
   "type": "module",
   "description": "Litestar plugin for Vite.",
-  "keywords": ["litestar", "vite", "vite-plugin"],
+  "keywords": [
+    "litestar",
+    "vite",
+    "vite-plugin"
+  ],
   "homepage": "https://github.com/litestar-org/litestar-vite",
   "repository": {
     "type": "git",
@@ -40,7 +44,10 @@
     }
   },
   "types": "./dist/js/index.d.ts",
-  "files": ["dist/js/**/*", "tools/clean.js"],
+  "files": [
+    "dist/js/**/*",
+    "tools/clean.js"
+  ],
   "bin": {
     "clean-orphaned-assets": "tools/clean.js"
   },
@@ -56,7 +63,7 @@
     "test": "vitest --config ./src/js/vitest.config.ts run"
   },
   "devDependencies": {
-    "@biomejs/biome": "1.9.4",
+    "@biomejs/biome": "2.0.6",
     "@types/node": "^22.15.3",
     "@vitest/coverage-v8": "^3.2.4",
     "esbuild": "0.25.3",
@@ -66,7 +73,7 @@
     "vitest": "^3.1.2"
   },
   "peerDependencies": {
-    "vite": "^5.0.0 || ^6.0.0 || ^7.0.0"
+    "vite": "^6.0.0 || ^7.0.0"
   },
   "engines": {
     "node": "^20.19.0 || >=22.12.0"

package/tools/clean.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { existsSync, readFileSync, readdirSync, unlinkSync } from "node:fs"
+import { existsSync, readdirSync, readFileSync, unlinkSync } from "node:fs"
 import { dirname } from "node:path"
 
 /*