Metadata-Version: 2.4
Name: litestar-vite
Version: 0.28.0
Summary: Vite plugin for Litestar
Project-URL: Changelog, https://litestar-org.github.io/litestar-vite/latest/changelog
Project-URL: Discord, https://discord.gg/X3FJqy8d2j
Project-URL: Documentation, https://litestar-org.github.io/litestar-vite/latest/
Project-URL: Homepage, https://litestar-org.github.io/litestar-vite/latest/
Project-URL: Issue, https://github.com/litestar-org/litestar-vite/issues/
Project-URL: Source, https://github.com/litestar-org/litestar-vite
Author-email: Cody Fincher <cody.fincher@gmail.com>
License: MIT
License-File: LICENSE
Keywords: litestar,vite
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Database
Classifier: Topic :: Database :: Database Engines/Servers
Classifier: Topic :: Software Development
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.24.1
Requires-Dist: litestar>=2.22.0
Requires-Dist: typing-extensions
Requires-Dist: websockets>=12.0
Provides-Extra: http2
Requires-Dist: h2>=4.0.0; extra == 'http2'
Provides-Extra: jinja
Requires-Dist: jinja2; extra == 'jinja'
Provides-Extra: nodeenv
Requires-Dist: nodeenv; extra == 'nodeenv'
Description-Content-Type: text/markdown

# Litestar Vite

Litestar Vite connects the Litestar backend to a Vite toolchain. It supports SPA, Template, Inertia, and meta-framework workflows, and it can proxy Vite dev traffic through your ASGI port or run Vite directly.

## Features

- One-port dev: proxies Vite HTTP + WS/HMR through Litestar on a single ASGI port by default.
- Framework-mode support: use `mode="framework"` (alias `mode="ssr"`) for Astro, Nuxt, and SvelteKit. Litestar proxies everything except your API routes.
- Production assets: reads the Vite manifest from `public/manifest.json` (configurable) and serves under `asset_url`.
- Type-safe frontends: optional OpenAPI/routes export plus `@hey-api/openapi-ts` via the Vite plugin.
- Inertia support: Inertia v2/v3 protocol support with session middleware, script-element bootstrap by default, and optional SSR.

## Install

```bash
pip install litestar-vite
npm install litestar-vite-plugin
```

## Quick Start

```python
from litestar import Litestar
from litestar_vite import VitePlugin

app = Litestar(plugins=[VitePlugin()])
```

```bash
litestar assets init --template vue
litestar assets install
litestar run --reload
```

`VitePlugin()` detects development and production behavior without manual `VITE_DEV_MODE` parsing. The effective
`litestar run --host/--port` values are also passed to the frontend environment and `.litestar.json` bridge.

### Optional Granian native static serving

Granian 0.16+ can serve eligible production bundle files before the request enters Python:

```python
from litestar import Litestar
from litestar_granian import GranianPlugin
from litestar_vite import VitePlugin

app = Litestar(
    plugins=[
        VitePlugin(),
        GranianPlugin(static="auto"),
    ]
)
```

This is an optimization, not a separate application configuration. The Litestar static route stays registered, so
Uvicorn and other ASGI servers serve the same files. Granian automatically falls back to Litestar when assets are
protected, customized, missing, or otherwise unsafe to intercept.

Native hits bypass ASGI middleware, guards, compression, custom headers, and Python access logging. Keep protected or
customized assets on the Litestar fallback path. See the
[production guide](https://litestar-org.github.io/litestar-vite/latest/usage/production.html) for the server matrix and
advanced configuration.

## Documentation

- Get started: <https://litestar-org.github.io/litestar-vite/latest/usage/index.html>
- Framework guides: <https://litestar-org.github.io/litestar-vite/latest/frameworks/index.html>
- Inertia: <https://litestar-org.github.io/litestar-vite/latest/frameworks/inertia/index.html>
- API reference: <https://litestar-org.github.io/litestar-vite/latest/reference/index.html>
- Changelog: <https://litestar-org.github.io/litestar-vite/latest/changelog.html>

## Common Commands

- `litestar assets init --template <name>`: scaffold a frontend or framework app
- `litestar assets install`: install frontend dependencies with the configured executor
- `litestar assets build`: build production assets
- `litestar assets serve`: run the frontend toolchain directly
- `litestar assets generate-types`: export OpenAPI, routes, and Inertia page-prop metadata
- `litestar assets doctor`: inspect and optionally repair config drift

## Development

```bash
# Install Python, docs, and JS dependencies; build package artifacts
make install && make build

# Run an example app
uv run litestar --app-dir examples/vue-inertia assets install
uv run litestar --app-dir examples/vue-inertia run
```

Replace `vue-inertia` with any other example app: `vue`, `react`, `svelte`, `react-inertia`, `htmx`, `angular`, `astro`, `nuxt`, or `sveltekit`.

litestar-vite now defaults Inertia apps to script-element bootstrap. Inertia v3 clients use that transport automatically; if you pin Inertia v2, keep `createInertiaApp({ defaults: { future: { useScriptElementForInitialPage: true } } })` aligned in the browser entry and SSR entry when `ssr=True` is enabled, or opt back into the legacy `data-page` path with `InertiaConfig(use_script_element=False)`.

## Links

- Docs: <https://litestar-org.github.io/litestar-vite/latest/>
- Examples: `examples/` (React, Vue, Svelte, HTMX, Inertia, Astro, Nuxt, SvelteKit, Angular)
- Real-world example: [litestar-fullstack](https://github.com/litestar-org/litestar-fullstack)
- Issues: <https://github.com/litestar-org/litestar-vite/issues/>
