Tool to create or patch FastAPI project with a Vue frontend, with integrated build and development systems. Only building the package needs JS runtime and Vue. Additionally, a devmode setup using Vite dev server with hot auto reloads is available via the scripts/devserver.py script (only intended to be used on the source repo, not included in installed package).

Features

No JavaScript: Your Python package can be installed and used without any JS runtime
Create new projects with uv init + create-vue (interactive)
Patch existing projects with build hooks and dev server scripts
Integrated build system: Vue frontend builds into Python package during uv build
Development server: Single command runs Vite + FastAPI with hot-reload
Optimized static serving: zstd compression, ETag caching, SPA support

Installation

Install uv, then:

uv tool install fastapi-vue-setup
fastapi-vue-setup --help

Or run directly:

uvx fastapi-vue-setup my-app

Usage

Create a new project

fastapi-vue-setup my-app

This will:

Run uv init my-app
Run create-vue frontend (interactive - choose your Vue options)
Patch the project with FastAPI integration
Install dependencies via uv add

Patch an existing project

If you have an existing project with pyproject.toml or frontend/, run without arguments to see the safety prompt, then confirm with:

cd /path/to/project
fastapi-vue-setup .

CLI Options

fastapi-vue-setup [project-dir] [options]

Options:
  --module-name NAME    Python module name (auto-detected from pyproject.toml)
  --vite-port PORT      Vite dev server port (default: 5173)
  --backend-port PORT   Backend API port in dev mode (default: 5180)
  --prod-port PORT      Production server port (default: 5080)
  --dry-run             Preview changes without modifying files

Port options can be used to reconfigure an already-patched project.

Port Configuration

The tool uses three distinct ports:

Port	Purpose	Used by
5173	Vite dev server (HMR)	`npm run dev` via devserver.py
5180	FastAPI in dev mode	uvicorn via devserver.py
5080	Production server	`uv run my-app`

In development, you access the app at http://localhost:5173. Vite proxies /api/* requests to FastAPI at port 5180.

In production, FastAPI serves both the API and static files from port 5080.

Project Structure

After patching, your project will have:

my-app/
├── frontend/                 # Vue.js application
│   ├── src/
│   ├── vite.config.ts       # Builds to ../my_app/frontend-build
│   └── package.json
├── my_app/                  # Python package
│   ├── __init__.py
│   ├── __main__.py          # CLI entry point
│   ├── app.py               # FastAPI application
│   └── frontend-build/      # Built frontend (gitignored)
├── scripts/
│   ├── devserver.py         # Development server
│   └── fastapi-vue/         # Build utilities
└── pyproject.toml           # Project configuration

The script finds your existing fastpi app module (even if not named app.py) and other files and patches them with minimal changes to enable the Vue-FastAPI interconnection.

Development Workflow

# Start dev server (runs both Vite and FastAPI)
uv run scripts/devserver.py

# Build for production
uv build

# Run production server
uv run my-app

Static File Serving

The Frontend class provides:

Automatic zstd compression at level 18
Smart caching: Content-hashed assets get immutable cache headers
ETag support: 304 Not Modified responses for cached content
SPA routing: Falls back to index.html for client-side routes
Favicon handling: Automatic /favicon.ico from hashed assets