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

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

@@ -125,6 +125,12 @@ export interface AstroTypesConfig {
      * @default false
      */
     generateZod?: boolean;
+    /**
+     * Generate SDK client functions for API calls.
+     *
+     * @default true
+     */
+    generateSdk?: boolean;
     /**
      * Debounce time in milliseconds for type regeneration.
      *

package/dist/js/astro.js

@@ -40,6 +40,7 @@ function resolveConfig(config = {}) {
       openapiPath: "openapi.json",
       routesPath: "routes.json",
       generateZod: false,
+      generateSdk: true,
       debounce: 300
     };
   } else if (typeof config.types === "object" && config.types !== null) {
@@ -49,6 +50,7 @@ function resolveConfig(config = {}) {
       openapiPath: config.types.openapiPath ?? "openapi.json",
       routesPath: config.types.routesPath ?? "routes.json",
       generateZod: config.types.generateZod ?? false,
+      generateSdk: config.types.generateSdk ?? true,
       debounce: config.types.debounce ?? 300
     };
   }
@@ -68,6 +70,9 @@ function createProxyPlugin(config) {
     config() {
       return {
         server: {
+          // Force IPv4 binding for consistency with Python proxy configuration
+          // Without this, Astro might bind to IPv6 localhost which the proxy can't reach
+          host: "127.0.0.1",
           // Set the port from Python config/env to ensure Astro uses the expected port
           // strictPort: true prevents Astro from auto-incrementing to a different port
           ...config.port !== void 0 ? {
@@ -227,12 +232,28 @@ function createTypeGenerationPlugin(typesConfig) {
         return false;
       }
       console.log(colors.cyan("[litestar-astro]"), colors.dim("Generating TypeScript types..."));
-      const args = ["@hey-api/openapi-ts", "-i", typesConfig.openapiPath, "-o", typesConfig.output];
-      if (typesConfig.generateZod) {
-        args.push("--plugins", "zod", "@hey-api/typescript");
+      const projectRoot = process.cwd();
+      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;
+      let args;
+      if (configPath) {
+        console.log(colors.cyan("[litestar-astro]"), colors.dim("Using config:"), configPath);
+        args = ["@hey-api/openapi-ts", "--file", configPath];
+      } else {
+        args = ["@hey-api/openapi-ts", "-i", typesConfig.openapiPath, "-o", typesConfig.output];
+        const plugins = ["@hey-api/typescript", "@hey-api/schemas"];
+        if (typesConfig.generateSdk) {
+          plugins.push("@hey-api/sdk", "@hey-api/client-fetch");
+        }
+        if (typesConfig.generateZod) {
+          plugins.push("zod");
+        }
+        if (plugins.length) {
+          args.push("--plugins", ...plugins);
+        }
       }
       await execAsync(`npx ${args.join(" ")}`, {
-        cwd: process.cwd()
+        cwd: projectRoot
       });
       const routesPath = path.resolve(process.cwd(), typesConfig.routesPath);
       if (fs.existsSync(routesPath)) {
@@ -271,6 +292,14 @@ function createTypeGenerationPlugin(typesConfig) {
       server = devServer;
       console.log(colors.cyan("[litestar-astro]"), colors.dim("Watching for schema changes:"), colors.yellow(typesConfig.openapiPath));
     },
+    async buildStart() {
+      if (typesConfig.enabled) {
+        const openapiPath = path.resolve(process.cwd(), typesConfig.openapiPath);
+        if (fs.existsSync(openapiPath)) {
+          await runTypeGeneration();
+        }
+      }
+    },
     handleHotUpdate({ file }) {
       if (!typesConfig.enabled) {
         return;
@@ -311,12 +340,18 @@ function litestarAstro(userConfig = {}) {
             plugins
           }
         };
-        if (command === "dev" && config.port !== void 0) {
+        if (command === "dev") {
           configUpdate.server = {
-            port: config.port
+            // Force IPv4 binding for consistency with Python proxy configuration
+            host: "127.0.0.1",
+            // Set port from Python config/env if provided
+            ...config.port !== void 0 ? { port: config.port } : {}
           };
           if (config.verbose) {
-            logger.info(`Setting Astro server port to ${config.port}`);
+            logger.info("Setting Astro server host to 127.0.0.1");
+            if (config.port !== void 0) {
+              logger.info(`Setting Astro server port to ${config.port}`);
+            }
           }
         }
         updateConfig(configUpdate);

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

@@ -0,0 +1,68 @@
+/**
+ * Litestar HTMX Extension
+ *
+ * Lightweight JSON templating for HTMX with CSRF support.
+ *
+ * Features:
+ * - `hx-swap="json"` - Client-side JSON templating
+ * - Automatic CSRF token injection
+ * - Template syntax: `ls-for`, `ls-if`, `:attr`, `@event`, `${expr}`
+ *
+ * For typed routes, import from your generated routes file:
+ * ```ts
+ * import { route } from '@/generated/routes'
+ * ```
+ *
+ * @example
+ * ```html
+ * <div hx-get="/api/books" hx-swap="json" hx-ext="litestar">
+ *   <template ls-for="book in $data">
+ *     <article :id="`book-${book.id}`">
+ *       <h3>${book.title}</h3>
+ *       <p>${book.author} • ${book.year}</p>
+ *     </article>
+ *   </template>
+ * </div>
+ * ```
+ *
+ * @module
+ */
+/** Type for route function - matches generated routes.ts */
+type RouteFn = (name: string, params?: Record<string, string | number>) => string;
+declare global {
+    interface Window {
+        htmx?: HtmxApi;
+    }
+}
+interface HtmxApi {
+    defineExtension: (name: string, ext: HtmxExtension) => void;
+    process: (elt: Element) => void;
+}
+interface HtmxExtension {
+    init?: () => void;
+    onEvent?: (name: string, evt: CustomEvent) => boolean | void;
+    transformResponse?: (text: string, xhr: XMLHttpRequest, elt: Element) => string;
+    isInlineSwap?: (swapStyle: string) => boolean;
+    handleSwap?: (swapStyle: string, target: Element, fragment: DocumentFragment | Element) => Element[];
+}
+/** Template context - inherits from data via prototype for direct access */
+interface Ctx {
+    $data: unknown;
+    $parent?: Ctx;
+    $index?: number;
+    $key?: string;
+    $event?: Event;
+    route?: RouteFn;
+    navigate?: (name: string, params?: Record<string, string | number>) => void;
+    [key: string]: unknown;
+}
+export declare function registerHtmxExtension(): void;
+export declare function swapJson(el: Element, data: unknown): void;
+type Handler = (ctx: Ctx, el: Element) => Ctx | false | void;
+interface Dir {
+    match: (a: Attr) => boolean;
+    create: (el: Element, a: Attr) => Handler | null;
+}
+export declare function setDebug(_on: boolean): void;
+export declare function addDirective(dir: Dir): void;
+export {};