Usage¶

The usage documentation is for end users of the library. It provides a high-level overview of what features are available and how to use them.

Core Features¶

Getting Started¶

1. Installation¶

Install litestar-vite using your preferred package manager:

pip install litestar-vite

Note: Nodeenv support is optional and off by default. To have litestar-vite provision Node inside your virtualenv, install with litestar-vite[nodeenv] and enable nodeenv detection (for example runtime.detect_nodeenv=True or make install NODEENV=1). Otherwise, ensure you already have Node/npm installed.

2. Basic Configuration¶

The plugin executes in one of two modes:

Hot Reloading: The plugin will start a Vite dev server and serve assets from it. When developing, this is the typical setting you would use. When using this, Vite is started using the port from the dev_server_port option. A websocket connection is established to the dev server from the Jinja templates to enable hot reloading.
Production Mode: The plugin will bundle assets and serve them from the specified bundle directory. When this mode is active, assets are served from the bundle_dir option. You must ensure that there is a manifest.json file in the bundle_dir directory. This file is generated by Vite when you build the runtime assets.

Configure your Litestar application with the Vite plugin:

from litestar import Litestar
from litestar_vite import ViteConfig, VitePlugin

app = Litestar(
    plugins=[
        VitePlugin(config=ViteConfig(dev_mode=True))
    ]
)

3. Bootstrap the Typescript Environment¶

If you do not have an existing vite application, you can create a new one for your Litestar application with the following command:

litestar assets init
# Inertia (resources/) example
litestar assets init --template react-inertia
# Non-Inertia (src/) example under custom frontend dir
litestar assets init --template react --frontend-dir web
litestar assets install

For more detailed information about specific features, refer to the sections in the sidebar.