Production Builds, Granian Native Static & CDN Deployment¶

Moving a Litestar Vite application from development to production swaps the live Vite dev proxy for pre-compiled, content-hashed bundles (manifest.json), optional Rust-level static serving with Granian (StaticPlacement.NATIVE), and one-command cloud storage uploads (litestar assets deploy).

Building Production Bundles¶

Run litestar assets build during your container or CI build stage:

$ litestar assets build
✓ Exported .litestar.json, openapi.json, and routes.json
✓ Running vite build...
public/.vite/manifest.json                0.42 kB
public/assets/main-D4f1A9.css            12.84 kB │ gzip:  3.12 kB
public/assets/main-B9x8K2.js            148.20 kB │ gzip: 46.50 kB
✓ Built in 1.42s

This command:

1. Exports .litestar.json, openapi.json, routes.json, and inertia-pages.json so TypeScript types are up to date before bundling.
2. Runs vite build (and vite build --ssr when SSR is enabled) using your configured RuntimeConfig.executor (node, bun, deno, pnpm, yarn).
3. Emits hashed assets (assets/main-B9x8K2.js, assets/main-D4f1A9.css) and <bundle_dir>/.vite/manifest.json (or manifest.json).

Production Configuration & Granian Static Serving¶

In production (dev_mode=False), ViteAssetLoader reads manifest.json once at startup and resolves asset tags with O(1) dictionary lookups.

When paired with litestar-granian (GranianPlugin(static="auto")), VitePlugin exposes a StaticServerConfig contract (StaticPlacement.NATIVE) so Granian's Rust HTTP worker serves hashed bundle files directly before the request ever enters Python or ASGI:

"""Production asset serving, Granian native static placement, and CDN deployment."""

from __future__ import annotations

from pathlib import Path

from litestar import Litestar

from litestar_vite import (
    DeployConfig,
    PathConfig,
    RuntimeConfig,
    StaticPlacement,
    StaticServerConfig,
    StaticServerMount,
    ViteConfig,
)


def create_production_config(bundle_dir: Path) -> ViteConfig:
    """Build a production ``ViteConfig`` with CDN prefix and Granian static offload."""
    return ViteConfig(
        mode="spa",
        dev_mode=False,
        paths=PathConfig(bundle_dir=bundle_dir, asset_url="https://cdn.example.com/assets/"),
        deploy=DeployConfig(
            enabled=True,
            storage_backend="s3://my-app-assets-prod/assets",
            asset_url="https://cdn.example.com/assets/",
            delete_orphaned=True,
        ),
        runtime=RuntimeConfig(start_dev_server=False),
    )


def create_static_server_config() -> StaticServerConfig:
    """Configure Granian Rust-level static file serving with native placement."""
    return StaticServerConfig(
        placement=StaticPlacement.NATIVE, mounts=(StaticServerMount(route="/static", directory=Path("public/build")),)
    )


def main() -> None:
    """Verify production ``ViteConfig`` and ``StaticServerConfig`` settings."""
    cfg = create_production_config(Path("public/build"))
    static_cfg = create_static_server_config()
    assert cfg.dev_mode is False
    assert cfg.asset_url == "https://cdn.example.com/assets/"
    assert static_cfg.placement == StaticPlacement.NATIVE
    assert Litestar is not None


__all__ = ("create_production_config", "create_static_server_config", "main")

Server & Static Placement Matrix¶

Asset Headers, Preloading, SRI, and CSP¶

Production HTML and asset responses served by Litestar apply browser-facing performance and security optimizations controlled by RuntimeConfig and ViteAssetLoader:

Internal build metadata (manifest.json, .vite/manifest.json, ssr-manifest.json, .litestar.json, and the hot file) returns 404 from the Litestar static route regardless of these settings.

Deploying Bundles to S3, GCS, or Cloudflare R2¶

When DeployConfig is configured (or --storage / VITE_DEPLOY_STORAGE is set), litestar assets deploy runs vite build (unless --no-build is passed), uploads your compiled bundle_dir to any fsspec storage backend, and prunes orphaned files:

litestar assets deploy --storage s3://my-app-assets-prod/assets --storage-option region_name=us-east-1

Use --dry-run in CI pull requests to preview which hashed files would be uploaded or deleted without mutating remote storage:

litestar assets deploy --dry-run