Operation Modes¶

Litestar Vite supports multiple operation modes to suit different architectural needs.

SPA Mode (Default)¶

The Single Page Application (SPA) mode is designed for modern frontend frameworks like React, Vue, and Svelte.

Key Features:

Serves a standard index.html entry point.
No Jinja2 template engine required.
Automatic injection of configuration and data into HTML.
Proxies requests to Vite dev server in development.
Registers a catch-all vite_spa route for you (no manual / handler needed) when spa_handler is enabled.

Configuration:

VitePlugin(
    config=ViteConfig(
        mode="spa",
        dev_mode=True,
    )
)

Template Mode¶

The Template mode is for traditional server-side rendered applications using Jinja2 templates.

Key Features:

Uses Jinja2 to render HTML.
Provides {{ vite() }} and {{ vite_hmr() }} helpers.
Full control over HTML structure.

Configuration:

VitePlugin(
    config=ViteConfig(
        mode="template",
        dev_mode=True,
    )
)

HTMX Mode¶

The HTMX mode is a specialized template mode optimized for HTMX applications.

Key Features:

Includes HTMX-specific template helpers.
Optimized for partial rendering.

Configuration:

VitePlugin(
    config=ViteConfig(
        mode="htmx",
        dev_mode=True,
    )
)

Hybrid Mode (Inertia.js)¶

The Hybrid mode is designed for Inertia.js applications that combine server-side routing with client-side rendering.

Alias: inertia mode is an alias for hybrid

Key Features:

Combines server-side routing with SPA-like client-side transitions.
Inertia.js protocol support (partial reloads, shared data, etc.).
Can use either Jinja2 templates or SPA mode (HTML transformation).

Configuration:

from litestar_vite import ViteConfig, VitePlugin
from litestar_vite.inertia import InertiaConfig

VitePlugin(
    config=ViteConfig(
        mode="hybrid",  # Or "inertia" (alias)
        dev_mode=True,
        inertia=InertiaConfig(),
    )
)

Framework Mode¶

Framework mode is for meta-frameworks like Nuxt, SvelteKit, or Astro that render on the server.

Aliases: ssr and ssg are aliases for framework mode.

Key Features:

Server-side rendering with hydration.
Proxy mode set to "proxy" (blacklist) by default.
SSR bundle management.

Configuration:

VitePlugin(
    config=ViteConfig(
        mode="framework",  # Or aliases: "ssr" / "ssg"
        dev_mode=True,
        runtime=RuntimeConfig(
            proxy_mode="proxy",
        ),
    )
)

External Mode¶

The External mode is for non-Vite frameworks (Angular CLI, Create React App, etc.) with their own build system.

Key Features:

Auto-serves bundle_dir in production.
No Vite manifest dependency.
External dev server configuration support.

Configuration:

from litestar_vite import ViteConfig, VitePlugin, RuntimeConfig
from litestar_vite.config import ExternalDevServer

VitePlugin(
    config=ViteConfig(
        mode="external",
        dev_mode=True,
        runtime=RuntimeConfig(
            external_dev_server=ExternalDevServer(
                target="http://localhost:4200",
                command=["ng", "serve"],
                build_command=["ng", "build"],
            ),
        ),
    )
)

Mode Aliases¶

For backward compatibility and semantic clarity, some modes have aliases:

Primary Mode	Alias	Notes
`hybrid`	`inertia`	Both refer to Inertia.js integration
`framework`	`ssr` / `ssg`	Aliases for framework proxy mode