Vite asset management for FastAPI with Jinja2 templates

Navigation

Verified details

These details have been verified by PyPI
Project links
GitHub Statistics
Maintainers
Avatar for jkupcho from gravatar.com jkupcho

Unverified details

These details have not been verified by PyPI
Meta
  • License: MIT License (MIT)
  • Author: Jonathan Kupcho
  • Tags assets , fastapi , frontend , hmr , jinja2 , vite
  • Requires: Python >=3.10
  • Provides-Extra: dev
Classifiers
Report project as malware

Project description

FastAPI Vite Integration

Seamless Vite asset management for FastAPI applications with Jinja2 templates. Features automatic manifest path derivation and production-ready asset serving.

Features

  • 🔥 Hot Module Replacement (HMR) in development
  • 📦 Automatic manifest parsing for production builds
  • 🎯 Simple API - single function call to setup
  • ⚡ Fast - leverages Vite's speed in development
  • 🔧 Auto-configured - manifest path derived from assets path
  • 🔧 Configurable - customize paths and behavior
  • 🎨 Framework agnostic - works with any Vite frontend setup
  • ✅ Production validation - catches missing assets early
  • 📝 Comprehensive logging - debug issues easily
  • 🔒 Type-safe - full type hints for IDE support
  • 🚀 CI/CD ready - automated releases with GitHub Actions

Installation

# Using uv
uv add fastapi-vite-assets

# Using pip
pip install fastapi-vite-assets

Quick Start

1. Configure Vite

In your vite.config.ts:

import { defineConfig } from "vite";

export default defineConfig({
  build: {
    manifest: true,
    rollupOptions: {
      input: ["src/main.ts", "src/style.css"],
    },
  },
});

2. Setup FastAPI

from pathlib import Path
from fastapi import FastAPI, Request
from fastapi.responses import HTMLResponse
from fastapi.templating import Jinja2Templates
from fastapi_vite_assets import ViteConfig, setup_vite

app = FastAPI()
templates = Jinja2Templates(directory="templates")

# Configure Vite integration
# New: manifest_path is auto-derived from assets_path
vite_config = ViteConfig(
    assets_path="web/dist",
    # manifest_path auto-derived: "web/dist/.vite/manifest.json"
)
setup_vite(app, templates, vite_config)

@app.get("/", response_class=HTMLResponse)
async def index(request: Request):
    return templates.TemplateResponse("index.html", {"request": request})

3. Create Templates

In templates/base.html:

<!DOCTYPE html>
<html>
<head>
    <title>My App</title>
    {{ vite_hmr_client() }}
    {{ vite_asset("src/style.css") }}
</head>
<body>
    {% block content %}{% endblock %}
    {{ vite_asset("src/main.ts") }}
</body>
</html>

Configuration

ViteConfig Options

ViteConfig(
    # Path to Vite build output directory
    assets_path: str = "dist",

    # Path to Vite manifest.json (auto-derived if None)
    manifest_path: Optional[str] = None,

    # Vite dev server URL
    dev_server_url: str = "http://localhost:5173",

    # URL prefix for static assets in production
    static_url_prefix: str = "/static",

    # Auto-detect dev mode from ENV variable
    auto_detect_dev: bool = True,

    # Force dev/prod mode (overrides auto-detection)
    force_dev_mode: Optional[bool] = None,

    # Base path to resolve relative paths
    base_path: Optional[Path] = None,

    # Validate configuration during setup
    validate_on_setup: bool = True,

    # Warn if assets missing in production
    warn_on_missing_assets: bool = True,

    # Warn if manifest missing in production
    warn_on_missing_manifest: bool = True,

    # Raise exceptions instead of warnings
    strict_mode: bool = False,
)

New in v0.2.0:

  • manifest_path is now optional and auto-derived from assets_path as {assets_path}/.vite/manifest.json
  • Added validation flags to catch configuration issues early
  • Added strict_mode for fail-fast behavior in production

Environment Variables

  • ENV - Set to "production" for production mode (default: "development")
  • VITE_HOST - Override Vite dev server host (default: from dev_server_url)
  • VITE_PORT - Override Vite dev server port (default: from dev_server_url)

Template Functions

vite_hmr_client()

Injects the Vite HMR client script tag in development mode. Does nothing in production.

{{ vite_hmr_client() }}

vite_asset(path)

Injects the appropriate asset tag(s) for the given entry point.

Development mode: Points to Vite dev server

<script type="module" src="http://localhost:5173/src/main.ts"></script>

Production mode: Reads from manifest and includes all dependencies

<script type="module" src="/static/assets/main-abc123.js"></script>
<link rel="stylesheet" href="/static/assets/main-def456.css">

Development vs Production

Development

# Terminal 1 - Start Vite dev server
cd web && npm run dev

# Terminal 2 - Start FastAPI
fastapi dev app/main.py

Production

# Build Vite assets
cd web && npm run build

# Run FastAPI with production environment
ENV=production uvicorn app.main:app

Docker Deployment

See the example Dockerfile in the repository for a multistage build setup.

Logging and Debugging

fastapi-vite-assets uses Python's standard logging. Configure it to see what's happening:

import logging

# Enable debug logging for detailed output
logging.basicConfig(level=logging.DEBUG)

# Or configure just this package
logging.getLogger("fastapi_vite_assets").setLevel(logging.INFO)

Log levels:

  • DEBUG: Configuration details, manifest loading, path resolution
  • INFO: Static file mounting, setup completion
  • WARNING: Missing assets, manifest issues, configuration problems
  • ERROR: Critical failures like malformed JSON

Production Validation

Catch configuration errors before they cause runtime issues:

Default Behavior (Warnings)

By default, validation runs during setup_vite() and logs warnings:

vite_config = ViteConfig(assets_path="web/dist")
setup_vite(app, templates, vite_config)
# Logs warnings if assets missing in production

Strict Mode (Fail Fast)

Use strict mode to raise exceptions for misconfigurations:

vite_config = ViteConfig(
    assets_path="web/dist",
    strict_mode=True  # Raises ValueError if assets missing
)
setup_vite(app, templates, vite_config)

Disable Validation

If you prefer to handle validation yourself:

vite_config = ViteConfig(
    assets_path="web/dist",
    validate_on_setup=False
)
setup_vite(app, templates, vite_config)

# Run validation manually later
issues = vite_config.validate()
if issues:
    for issue in issues:
        print(f"Warning: {issue}")

Migration from v0.1.x

If you're upgrading from an earlier version, your existing code continues to work:

# v0.1.x - Still works in v0.2.0
vite_config = ViteConfig(
    assets_path="web/dist",
    manifest_path="web/dist/.vite/manifest.json",  # Explicit
)

# v0.2.0 - Simpler (recommended)
vite_config = ViteConfig(
    assets_path="web/dist",
    # manifest_path auto-derived
)

Examples

Check out the packages/example directory for a complete working example.

License

MIT

Project details

Verified details

These details have been verified by PyPI
Project links
GitHub Statistics
Maintainers
Avatar for jkupcho from gravatar.com jkupcho

Unverified details

These details have not been verified by PyPI
Meta
  • License: MIT License (MIT)
  • Author: Jonathan Kupcho
  • Tags assets , fastapi , frontend , hmr , jinja2 , vite
  • Requires: Python >=3.10
  • Provides-Extra: dev
Classifiers

Release history Release notifications | RSS feed

This version

0.2.0

0.1.0

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

fastapi_vite_assets-0.2.0.tar.gz (14.7 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

fastapi_vite_assets-0.2.0-py3-none-any.whl (11.0 kB view details)

Uploaded Python 3

File details

Details for the file fastapi_vite_assets-0.2.0.tar.gz.

File metadata

  • Download URL: fastapi_vite_assets-0.2.0.tar.gz
  • Upload date:
  • Size: 14.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for fastapi_vite_assets-0.2.0.tar.gz
Algorithm Hash digest
SHA256 cef0cc06918690b789ab8d9fc6e72f385bc1689a78c2558066d6ac3d989108df
MD5 2fb33b71b848b75373f3ddf24cf39d61
BLAKE2b-256 da84d362590e4368745271ec307503b8bb2138853600ea2a3ff73f17de71ea85

See more details on using hashes here.

Provenance

The following attestation bundles were made for fastapi_vite_assets-0.2.0.tar.gz:

Publisher: publish.yml on jkupcho/fastapi-vite-assets

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file fastapi_vite_assets-0.2.0-py3-none-any.whl.

File metadata

File hashes

Hashes for fastapi_vite_assets-0.2.0-py3-none-any.whl
Algorithm Hash digest
SHA256 f27d136ef228117279b010a24fcbd942d970b3d5332c48d7ffec73273bcd0a71
MD5 6e2a1cd43e3917d2673fb0e4ebcc4850
BLAKE2b-256 e40e26457eeb7c11a7fae820666cb347a4a5dbd8d1b8f9d73407486a1ee405b6

See more details on using hashes here.

Provenance

The following attestation bundles were made for fastapi_vite_assets-0.2.0-py3-none-any.whl:

Publisher: publish.yml on jkupcho/fastapi-vite-assets

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page