97 lines
3.5 KiB
Markdown
97 lines
3.5 KiB
Markdown
# fastapi-vue-setup
|
||
|
||
Create or patch a FastAPI + Vue project with an integrated dev/build workflow.
|
||
|
||
- Development: one command runs Vite + FastAPI (reloads)
|
||
- Production: `uv build` bakes the built Vue assets into the Python package (no Node/JS runtime needed to *run* the installed package)
|
||
|
||
## Quick start
|
||
|
||
Install [UV](https://docs.astral.sh/uv/) and any JS runtime (node, deno, or bun).
|
||
|
||
This README uses `my-app` as the example project name:
|
||
|
||
- project directory: `my-app/`
|
||
- Python module: `my_app`
|
||
- env prefix: `MY_APP`
|
||
- CLI command: `my-app`
|
||
|
||
Create a new project in `./my-app`:
|
||
|
||
```sh
|
||
uvx fastapi-vue-setup my-app
|
||
```
|
||
|
||
Once in your source tree, you will typically use `.` for the path. If there is an existing project, `fastapi-vue-setup` will do its best to find and patch a backend module and create or patch a Vue project in `frontend/`. The integration can be upgraded by running a new version of `fastapi-vue-setup` on it, preserving earlier default ports and user customizations.
|
||
|
||
## In your project
|
||
|
||
ℹ️ Everything below is meant to be run within your project source tree.
|
||
|
||
The setup creates a CLI entry for your package, so that it becomes a command to run, not a Python module nor `fastapi myapp...`. The CLI main can be customized, although --listen should be kept for devserver compatibility.
|
||
|
||
You can choose the JS runtime with environment `JS_RUNTIME` (e.g. `node`, `deno`, `bun`, or path to one). This is used by the build and the devserver scripts. By default any available runtime on the system is chosen.
|
||
|
||
### Development server (Vite + FastAPI)
|
||
|
||
```sh
|
||
uv run scripts/devserver.py [args]
|
||
```
|
||
|
||
ℹ️ Arguments are forwarded to the main CLI, except that `--listen` controls where Vite listens, and `--backend` is passed to main CLI as `--listen`.
|
||
|
||
### Production
|
||
|
||
Build the Python package (this compiles the Vue frontend) and run the production server:
|
||
|
||
```sh
|
||
uv build && uv run my-app [args]
|
||
```
|
||
|
||
Once happy with it, publish the package
|
||
|
||
```sh
|
||
uv build && uv publish
|
||
```
|
||
|
||
Afterwards, you can easily run it anywhere, no JS runtimes required:
|
||
|
||
```sh
|
||
uvx my-app [args]
|
||
```
|
||
|
||
ℹ️ Instead of `uvx` you may consider `uv tool install`, oldskool `pip install` or whatever best suits you.
|
||
|
||
### Vite plugin
|
||
|
||
The generated Vite plugin lives in `frontend/vite-plugin-fastapi.js` and defaults to proxying `/api`.
|
||
|
||
It reads `MY_APP_BACKEND_URL` to know where to proxy; if unset it falls back to your configured default backend port.
|
||
|
||
## Project layout (typical)
|
||
|
||
```
|
||
my-app/
|
||
├── frontend/ # Vue app (Vite)
|
||
│ ├── src/
|
||
│ ├── vite-plugin-fastapi.js
|
||
│ └── package.json
|
||
├── my_app/ # Python package
|
||
│ ├── __main__.py # CLI entrypoint
|
||
│ ├── app.py # FastAPI app
|
||
│ └── frontend-build/ # built assets (included in distributions)
|
||
├── pyproject.toml
|
||
└── scripts/
|
||
├── devserver.py # Run Vite and FastAPI together in dev mode
|
||
└── fastapi-vue/ # Dev utilities (only on the source tree)
|
||
├── buildhook.py
|
||
├── buildutil.py
|
||
└── devutil.py
|
||
```
|
||
|
||
## The fastapi-vue runtime module
|
||
|
||
The backend runs the FastAPI app and serves the frontend build using the companion package in [fastapi-vue/README.md](fastapi-vue/README.md). Your project will depend on Fastapi and this lightweight module.
|
||
|
||
ℹ️ Development functionality is in `scripts/fastapi-vue/` directly in your source tree, and is not to be confused with this runtime module. Only the runtime is installed with your package.
|