127 lines
4.0 KiB
Markdown
127 lines
4.0 KiB
Markdown
# fastapi-vue-setup
|
|
|
|
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](https://docs.astral.sh/uv/getting-started/installation/), then:
|
|
|
|
```sh
|
|
uv tool install fastapi-vue-setup
|
|
fastapi-vue-setup --help
|
|
```
|
|
|
|
Or run directly:
|
|
|
|
```sh
|
|
uvx fastapi-vue-setup my-app
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Create a new project
|
|
|
|
```sh
|
|
fastapi-vue-setup my-app
|
|
```
|
|
|
|
This will:
|
|
|
|
1. Run `uv init my-app`
|
|
2. Run `create-vue frontend` (interactive - choose your Vue options)
|
|
3. Patch the project with FastAPI integration
|
|
4. 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:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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
|