# 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