README

README.md

@@ -1,137 +1,96 @@
 # fastapi-vue-setup
 
-Tool to create or patch FastAPI project with a Vue frontend, with integrated build and development systems. The Python package will not need any JS runtime because it includes a prebuilt Vue frontend in it. For development (Vite and FastAPI auto reloads) and building the package one of npm, deno or bun is required (node is recommended due to bugs in deno and bun).
+Create or patch a FastAPI + Vue project with an integrated dev/build workflow.
 
-## Features
+- 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)
 
-- **No JavaScript**: Your Python package can be installed and used without any JS runtime
-- **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**: Caching, zstd compression and SPA support
+## Quick start
 
-## Installation
+Install [UV](https://docs.astral.sh/uv/) and any JS runtime (node, deno, or bun).
 
-Install [uv](https://docs.astral.sh/uv/getting-started/installation/), then:
+This README uses `my-app` as the example project name:
 
-```sh
-uv tool install fastapi-vue-setup
-fastapi-vue-setup --help
-```
+- project directory: `my-app/`
+- Python module: `my_app`
+- env prefix: `MY_APP`
+- CLI command: `my-app`
 
-Or run directly:
+Create a new project in `./my-app`:
 
 ```sh
 uvx fastapi-vue-setup my-app
 ```
 
-## Usage
+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.
 
-The script may be used to create an all new project folder or to patch or update an existing project to use this framework. It autodetects the project folder given and performs the appropriate actions.
+## In your project
 
-### Create a new 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
-fastapi-vue-setup my-app
+uv run scripts/devserver.py [args]
 ```
 
-This will:
+ℹ️ Arguments are forwarded to the main CLI, except that `--listen` controls where Vite listens, and `--backend` is passed to main CLI as `--listen`.
 
-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`
+### Production
 
-### Patch an existing project
-
-You should have your pyproject.toml at the current working directory, and Vue with its package.json under `frontend/`. If either one is missing, new applications will be initialised. Otherwise we only patch what can be patched without breaking your existing projects.
+Build the Python package (this compiles the Vue frontend) and run the production server:
 
 ```sh
-fastapi-vue-setup .
+uv build && uv run my-app [args]
 ```
 
-### CLI Options
+Once happy with it, publish the package
 
-```
-fastapi-vue-setup [project-dir] [options]
-
-Options:
-  --module-name NAME    Python module name (auto-detected from pyproject.toml)
-  --dry-run             Preview changes without modifying files
+```sh
+uv build && uv publish
 ```
 
-## Port Configuration
+Afterwards, you can easily run it anywhere, no JS runtimes required:
 
-In development, you access the Vite dev server at `http://localhost:5173`. Vite proxies `/api/*` requests to FastAPI at port 5180. Ports and hosts of Vite and FastAPI are configurable by `devserver.py` arguments.
-
-In production, FastAPI serves both the API and static files at `http://localhost:5080`. Configurable by `host:port` argument with defaults set in `__main__.py`
-
-## Main CLI
-
-If your project didn't already have `__main__.py`, we create one that runs the FastAPI app with richer configuration than what the FastAPI CLI offers. Running your module starts it in production mode, and optionally host:port may be given as argument to specify where it listens.
-
-If you are running behind a reverse proxy like [Caddy](https://caddyserver.com/) on localhost, your app will trust the proxy headers it sends. However, if you need to configure another proxy host or IP, set `FORWARDED_ALLOW_IPS` env variable before running the server.
-
-The devserver script depends on this CLI entry for running the backend. You will have to modify the `devserver.py` script if your app has its own incompatible main module. Note that we set FastAPI debug mode and Uvicorn reload when configured via `FASTAPI_VUE_BACKEND_URL` env variable (set by `devserver.py`), while for normal production use these stay disabled. The same variable also controls static files serving (disabled in dev mode).
-
-
-## Vite Plugin Configuration
-
-The `fastapiVue()` plugin in `vite.config.ts` accepts options to customize proxy behavior:
-
-```js
-import fastapiVue from "./vite-plugin-fastapi.js";
-
-export default defineConfig({
-  plugins: [
-    vue(),
-    // Default: proxies only /api
-    fastapiVue(),
-
-    // Or specify custom paths to proxy to backend
-    fastapiVue({ paths: ["/api", "/auth", "/ws"] }),
-  ],
-});
+```sh
+uvx my-app [args]
 ```
 
-The plugin reads environment `FASTAPI_VUE_BACKEND_URL` (default: `http://localhost:5180`) to determine where to proxy requests. This is set automatically by `devserver.py`.
+ℹ️ Instead of `uvx` you may consider `uv tool install`, oldskool `pip install` or whatever best suits you.
 
-## Project Structure
+### 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 application
+├── frontend/                    # Vue app (Vite)
 │   ├── src/
 │   ├── vite-plugin-fastapi.js
-│   ├── vite.config.js
 │   └── package.json
-├── my_app/                   # Python module (files included in sdist)
-│   ├── __init__.py
+├── my_app/                      # Python package
 │   ├── __main__.py              # CLI entrypoint
-│   ├── app.py                # FastAPI application
-│   └── frontend-build/       # Built frontend (gitignored)
-├── scripts/
-│   ├── devserver.py          # CLI dev server (only in source tree)
-│   └── fastapi-vue/
-│       ├── build-frontend.py
-│       └── util.py
-└── pyproject.toml
+│   ├── 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)
+        ├── build-frontend.py
+        ├── buildutil.py
+        └── devutil.py
 ```
 
-The project directory tree looks roughly like this after project creation or patching. The script finds your existing app module and other files and patches them with minimal changes to enable the Vue-FastAPI interconnection. New Python and Vue projects are created automatically if none exist.
+## The fastapi-vue runtime module
 
-## Development Workflow
+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.
 
-```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
-```
-
-## Frontend serving
-
-Your FastAPI app will use [fastapi-vue](https://git.zi.fi/LeoVasanko/fastapi-vue) to serve the frontend files. Refer to that package's documentation for further configuration.
+ℹ️ 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.

fastapi-vue/README.md

@@ -1,29 +1,25 @@
 # fastapi-vue
 
-Implements Single-Page-App serving at site root with FastAPI, that the standard StaticFiles module cannot handle. This also caches and zstd compresses the files for lightning-fast operation. This is primarily meant for use with Vue frontend, but technically can host any static files in a similar manner.
+Runtime helpers for FastAPI + Vite/Vue projects.
 
-## Installation
+## Overview
 
-Script [fastapi-vue-setup](https://git.zi.fi/LeoVasanko/fastapi-vue-setup) should normally be used to convert or create a project with connection between FastAPI and Vue. The target project will depend on this package to serve its static files.
+This package provides:
 
-```sh
-uvx fastapi-vue-setup --help
-```
+- `fastapi_vue.Frontend`: serves built SPA assets (with SPA support, caching, and optional zstd)
+- `fastapi_vue.server.run`: a small Uvicorn runner with convenient `listen` endpoint parsing
 
-Refer to instructions below for further configuration.
+## Quickstart
 
-## Usage
+Serve built frontend assets from `frontend-build/`:
 
 ```python
+from pathlib import Path
 from contextlib import asynccontextmanager
 from fastapi import FastAPI
 from fastapi_vue import Frontend
 
-frontend = Frontend(
-    Path(__file__).with_name("frontend-build"),
-    spa=True,
-    cached=["/assets/"],
-)
+frontend = Frontend(Path(__file__).with_name("frontend-build"), spa=True)
 
 @asynccontextmanager
 async def lifespan(app: FastAPI):
@@ -38,10 +34,35 @@ app = FastAPI(lifespan=lifespan)
 frontend.route(app, "/")
 ```
 
-## Configuration
+## Frontend
 
-- `directory`: Path to static files directory
-- `spa`: Enable SPA mode (serve index.html for unknown routes)
-- `cached`: Path prefixes for immutable cache headers (browser won't check for changes)
-- `favicon`: Path to serve at `/favicon.ico` (e.g., `"/logo.png"` will be served as `image/png`)
+`Frontend` serves a directory with:
+
+- RAM caching, with zstd compression when smaller than original
+- Browser caching: ETag + Last-Modified, Immutable assets
+- Favicon mapping (serve PNG or other images there instead)
+- SPA routing (serve browsers index.html at all paths not otherwise handled)
+
+Dev-mode behavior with `FastAPI(debug=True)`: requests error HTTP 409 with a message telling you to use the Vite dev server instead. Avoids accidentally using outdated `frontend-build` during development.
+
+- `directory`: Path on local filesystem
+- `index`: Index file name (default: `index.html`)
+- `spa`: Serve index at any path (default: `False`)
+- `catch_all`: Register a single catch-all handler instead of a route to each file; default for SPA
+- `cached`: Path prefixes treated as immutable (default: `/assets/`)
+- `favicon`: Optional path or glob (e.g. `/assets/logo*.png`)
 - `zstdlevel`: Compression level (default: 18)
+
+ℹ️ Even when your page has a meta tag giving favicon location, browsers still try loading `/favicon.ico` whenever looking at something else. We find it more convenient to simply serve the image where the browser expects it, with correct MIME type. This also allows having a default favicon for your application that can be easily overriden at the reverse proxy (Caddy, Nginx) to serve the company branding if needed in deployment.
+
+## Server runner
+
+When you need more flexibility than `fastapi` CLI can provide (e.g. CLI arguments to your own program), you may use this convenience to run FastAPI app with Uvicorn startup on given `listen` endpoints. Runs in the same process if possible but delegates to `uvicorn.run()` for auto-reloads and multiple workers. This would typically be called from your CLI main, which can set its own env variables to pass information to the FastAPI instances that run (Python imports only work in same-process mode).
+
+```python
+from fastapi_vue import server
+
+server.run("my_app.app:app", listen=["localhost:8000"])
+```
+
+- As a deployment option, environment `FORWARDED_ALLOW_IPS` controls `X-Forwarded` trusted IPs (default: `127.0.0.1,::1`).

fastapi_vue_setup.py

@@ -8,11 +8,12 @@ Usage:
 Options:
     --module-name NAME      Python module name (auto-detected from pyproject.toml)
     --ports DEFAULT,VITE,DEV  Port configuration (default: 3100,3100,3200)
-    --dry-run               Show what would be done without making changes
+    --dry                   Show what would be done without making changes
 """
 
 import argparse
 import ast
+import importlib.metadata
 import os
 import re
 import shutil
@@ -23,6 +24,8 @@ from textwrap import indent
 
 import tomlkit
 
+version = importlib.metadata.version("fastapi-vue-setup")
+
 # Track Python files written/patched for ruff formatting
 _python_files_to_format: list[Path] = []
 
@@ -30,19 +33,27 @@ _python_files_to_format: list[Path] = []
 TEMPLATE_DIR = Path(__file__).parent / "template"
 
 
-def ruff_sort_imports(files: list[Path], dry_run: bool = False) -> None:
+def print_boxed(text: str) -> None:
+    """Print text in a Unicode rounded box."""
+    width = len(text) + 2
+    print(f"╭{'─' * width}╮")
+    print(f"│ {text} │")
+    print(f"╰{'─' * width}╯")
+
+
+def ruff_sort_imports(files: list[Path], dry: bool = False) -> None:
     """Run ruff to sort imports in the given Python files."""
     if not files:
         return
     py_files = [str(f) for f in files if f.suffix == ".py" and f.exists()]
     if not py_files:
         return
-    if dry_run:
+    if dry:
         print(f"🔧 Would run ruff import sorting on {len(py_files)} files")
         return
     print("🔧 Ruff isort on modified files")
     subprocess.run(
-        ["ruff", "check", "--select", "I", "--fix", *py_files],
+        [sys.executable, "-m", "ruff", "check", "--select", "I", "--fix", *py_files],
         stdout=subprocess.DEVNULL,
     )
 
@@ -115,7 +126,7 @@ const backendStatus = ref<'checking' | 'connected' | 'error'>('checking')
 
 onMounted(async () => {
   try {
-    const res = await fetch('/api/health')
+    const res = await fetch('/api/health?from=frontend')
     backendStatus.value = res.ok ? 'connected' : 'error'
   } catch {
     backendStatus.value = 'error'
@@ -131,7 +142,7 @@ const backendStatus = ref('checking')
 
 onMounted(async () => {
   try {
-    const res = await fetch('/api/health')
+    const res = await fetch('/api/health?from=frontend')
     backendStatus.value = res.ok ? 'connected' : 'error'
   } catch {
     backendStatus.value = 'error'
@@ -150,17 +161,16 @@ STATUS_SPAN_TEMPLATE = """\
 """
 
 # Setup complete message template
-SETUP_COMPLETE_MESSAGE = """
-Next steps:
+SETUP_COMPLETE_MESSAGE = """\
+## Development server: (live reloads, debug)
+CD_CMDuv run scripts/devserver.py
 
-1. Build for production:
-   CD_CMDuv build
+## Production build:
+CD_CMDuv build && uv run SCRIPT_NAME
 
-2. Start development server:
-   CD_CMDuv run scripts/devserver.py
-
-3. Run production server:
-   CD_CMDuv run SCRIPT_NAME
+## Release Python package, run anywhere:
+CD_CMDuv build && uv publish
+uvx SCRIPT_NAME  # No Node required
 """
 
 
@@ -482,7 +492,7 @@ def render_template(template: str, **kwargs) -> str:
 
 
 def patch_app_file(
-    path: Path, module_name: str, app_var: str, dry_run: bool = False
+    path: Path, module_name: str, app_var: str, dry: bool = False
 ) -> bool:
     """Patch an existing app.py with frontend integration.
 
@@ -640,7 +650,7 @@ def patch_app_file(
         print(f"⚠️  Skipping {path} (no changes needed)")
         return False
 
-    if dry_run:
+    if dry:
         print(f"✅ Would patch {path}")
         return True
 
@@ -669,7 +679,7 @@ def patch_app_file(
 def patch_vite_config(
     path: Path,
     module_name: str,
-    dry_run: bool = False,
+    dry: bool = False,
 ) -> bool:
     """Patch an existing vite.config.js/ts by adding fastapi-vue plugin.
 
@@ -731,7 +741,7 @@ def patch_vite_config(
         print(f"ℹ️  Skipping {path} (no changes needed)")
         return False
 
-    if dry_run:
+    if dry:
         print(f"✅ Would patch {path}")
         return True
 
@@ -740,7 +750,7 @@ def patch_vite_config(
     return True
 
 
-def patch_frontend_health_check(frontend_dir: Path, dry_run: bool = False) -> bool:
+def patch_frontend_health_check(frontend_dir: Path, dry: bool = False) -> bool:
     """Patch Vue app to include FastAPI backend health check.
 
     Tries HelloWorld.vue first (full demo), then falls back to App.vue (minimal).
@@ -831,7 +841,7 @@ def patch_frontend_health_check(frontend_dir: Path, dry_run: bool = False) -> bo
         print(f"ℹ️  Skipping {target_file} (no changes needed)")
         return False
 
-    if dry_run:
+    if dry:
         print(f"✅ Would patch {target_file}")
         return True
 
@@ -842,12 +852,12 @@ def patch_frontend_health_check(frontend_dir: Path, dry_run: bool = False) -> bo
 
 # SHA-256 of old vite-plugin-fastapi.js (before auto-upgrade marker was added)
 # with module name replaced by MODULE_NAME in the outDir path
-_OLD_VITE_PLUGIN_SHA256 = "93713e879c15a25c750a70ce1de684adeaf11b0c723c38da56e5e7ba207f6632"
+_OLD_VITE_PLUGIN_SHA256 = (
+    "93713e879c15a25c750a70ce1de684adeaf11b0c723c38da56e5e7ba207f6632"
+)
 
 
-def _upgrade_old_vite_plugin(
-    path: Path, module_name: str, dry_run: bool = False
-) -> None:
+def _upgrade_old_vite_plugin(path: Path, module_name: str, dry: bool = False) -> None:
     """Remove old vite-plugin-fastapi.js that lacks auto-upgrade marker.
 
     Old versions didn't have the upgrade marker, so write_file skips them as
@@ -861,11 +871,13 @@ def _upgrade_old_vite_plugin(
         return  # Already new format, write_file handles it
     import hashlib
 
-    normalized = content.replace(f"../{module_name}/frontend-build", "../MODULE_NAME/frontend-build")
+    normalized = content.replace(
+        f"../{module_name}/frontend-build", "../MODULE_NAME/frontend-build"
+    )
     digest = hashlib.sha256(normalized.encode()).hexdigest()
     if digest != _OLD_VITE_PLUGIN_SHA256:
         return  # Modified by user, don't touch
-    if dry_run:
+    if dry:
         print(f"🔄 Would upgrade old {path}")
         return
     path.unlink()
@@ -880,7 +892,7 @@ def write_file(
     path: Path,
     content: str,
     overwrite: bool = True,
-    dry_run: bool = False,
+    dry: bool = False,
     executable: bool = False,
     fallback_path: Path | None = None,
     force: bool = False,
@@ -909,12 +921,12 @@ def write_file(
             if fallback_path is not None:
                 # Write to fallback path instead
                 return _write_fallback_file(
-                    path, fallback_path, content, dry_run, executable
+                    path, fallback_path, content, dry, executable
                 )
             print(f"ℹ️  Skipping {path} (customized by user)")
             return False
 
-    if dry_run:
+    if dry:
         action = "overwrite" if exists else "create"
         print(f"✅ Would {action} {path}")
         return True
@@ -934,7 +946,7 @@ def _write_fallback_file(
     original_path: Path,
     fallback_path: Path,
     content: str,
-    dry_run: bool,
+    dry: bool,
     executable: bool,
 ) -> bool:
     """Write content to a fallback .new.py file when original can't be overwritten."""
@@ -944,7 +956,7 @@ def _write_fallback_file(
             print(f"✔️  {fallback_path} (already up to date)")
             return False
 
-    if dry_run:
+    if dry:
         print(f"✅ Would create {fallback_path} (original customized by user)")
         _new_files_written.append((fallback_path, original_path))
         return True
@@ -1081,13 +1093,13 @@ def find_js_runtime() -> tuple[str, str] | None:
     return None
 
 
-def ensure_python_project(project_dir: Path, dry_run: bool = False) -> bool:
+def ensure_python_project(project_dir: Path, dry: bool = False) -> bool:
     """Ensure pyproject.toml exists, run uv init if needed."""
     pyproject = project_dir / "pyproject.toml"
     if pyproject.exists():
         return True
 
-    if dry_run:
+    if dry:
         print(f"📦 Would run: uv init {project_dir}")
         return True
 
@@ -1107,7 +1119,7 @@ def ensure_python_project(project_dir: Path, dry_run: bool = False) -> bool:
     return True
 
 
-def ensure_frontend(project_dir: Path, dry_run: bool = False) -> bool:
+def ensure_frontend(project_dir: Path, dry: bool = False) -> bool:
     """Ensure frontend directory exists with a Vue project, run create-vue if needed."""
     frontend_dir = project_dir / "frontend"
     package_json = frontend_dir / "package.json"
@@ -1131,7 +1143,7 @@ def ensure_frontend(project_dir: Path, dry_run: bool = False) -> bool:
     }
     create_cmd = create_vue_commands[js_name]
 
-    if dry_run:
+    if dry:
         print(f"🎨 Would run: {' '.join(create_cmd)}")
         return True
 
@@ -1171,11 +1183,15 @@ def cmd_setup(args: argparse.Namespace) -> int:
         project_dir = Path.cwd() / project_path
 
     project_dir = project_dir.resolve()
-    dry_run = args.dry_run
+    dry = args.dry
+
+    print_boxed(f"fastapi-vue-setup {version}")
+    if dry:
+        print("🏃 DRY RUN MODE - no changes will be made\n")
 
     # Create project directory if it doesn't exist
     if not project_dir.exists():
-        if dry_run:
+        if dry:
             print(f"✅ Would create directory: {project_dir}")
         else:
             project_dir.mkdir(parents=True)
@@ -1183,15 +1199,12 @@ def cmd_setup(args: argparse.Namespace) -> int:
 
     print(f"🔧 Setting up project: {project_dir}")
 
-    if dry_run:
-        print("\n🏃 DRY RUN MODE - no changes will be made\n")
-
     # Step 1: Ensure frontend exists (do this first so cancellation doesn't leave partial setup)
-    if not ensure_frontend(project_dir, dry_run):
+    if not ensure_frontend(project_dir, dry):
         return 1
 
     # Step 2: Ensure Python project exists
-    if not ensure_python_project(project_dir, dry_run):
+    if not ensure_python_project(project_dir, dry):
         return 1
 
     # Detect module name
@@ -1257,7 +1270,7 @@ def cmd_setup(args: argparse.Namespace) -> int:
         tpl_vars["APP_MODULE"] = "app"
 
     # Create directories
-    if not dry_run:
+    if not dry:
         if not module_dir.exists():
             module_dir.mkdir(parents=True)
         fastapi_vue_scripts.mkdir(parents=True, exist_ok=True)
@@ -1269,7 +1282,7 @@ def cmd_setup(args: argparse.Namespace) -> int:
     # Remove obsolete util.py if present
     obsolete_util = fastapi_vue_scripts / "util.py"
     if obsolete_util.exists():
-        if dry_run:
+        if dry:
             print(f"🗑️ Would remove obsolete {obsolete_util}")
         else:
             obsolete_util.unlink()
@@ -1286,7 +1299,7 @@ def cmd_setup(args: argparse.Namespace) -> int:
                 dest_path,
                 content,
                 overwrite=True,
-                dry_run=dry_run,
+                dry=dry,
                 force=True,  # Internal files, always overwrite
             )
 
@@ -1299,7 +1312,7 @@ def cmd_setup(args: argparse.Namespace) -> int:
         devserver_path,
         content,
         overwrite=True,
-        dry_run=dry_run,
+        dry=dry,
         executable=True,
         fallback_path=devserver_fallback,
     )
@@ -1307,7 +1320,7 @@ def cmd_setup(args: argparse.Namespace) -> int:
     # === Handle app module ===
     if app_file:
         # Existing app: patch with import, route, and try to patch lifespan
-        patch_app_file(app_file, module_name, app_var, dry_run=dry_run)
+        patch_app_file(app_file, module_name, app_var, dry=dry)
     else:
         # No app: create full app.py
         # Create __init__.py if missing
@@ -1315,13 +1328,13 @@ def cmd_setup(args: argparse.Namespace) -> int:
         if not init_file.exists():
             template = load_template("backend/__init__.py")
             content = render_template(template, **tpl_vars)
-            write_file(init_file, content, overwrite=False, dry_run=dry_run)
+            write_file(init_file, content, overwrite=False, dry=dry)
 
         # Create app.py
         app_file_path = module_dir / "app.py"
         template = load_template("backend/app.py")
         content = render_template(template, **tpl_vars)
-        write_file(app_file_path, content, overwrite=False, dry_run=dry_run)
+        write_file(app_file_path, content, overwrite=False, dry=dry)
 
     # === Handle __main__.py ===
     main_file = module_dir / "__main__.py"
@@ -1338,7 +1351,7 @@ def cmd_setup(args: argparse.Namespace) -> int:
             main_file,
             main_content,
             overwrite=True,
-            dry_run=dry_run,
+            dry=dry,
             fallback_path=main_fallback,
         )
     elif not existing_cli:
@@ -1347,7 +1360,7 @@ def cmd_setup(args: argparse.Namespace) -> int:
             main_file,
             main_content,
             overwrite=False,
-            dry_run=dry_run,
+            dry=dry,
         )
     else:
         # No file but has existing entrypoint - don't create (user has custom CLI setup)
@@ -1359,25 +1372,25 @@ def cmd_setup(args: argparse.Namespace) -> int:
         # Install the vite plugin file (always update)
         plugin_file = frontend_dir / "vite-plugin-fastapi.js"
         # Upgrade old plugin versions that lack the auto-upgrade marker
-        _upgrade_old_vite_plugin(plugin_file, module_name, dry_run)
+        _upgrade_old_vite_plugin(plugin_file, module_name, dry)
         template = load_template("frontend/vite-plugin-fastapi.js")
         content = render_template(template, **tpl_vars)
-        write_file(plugin_file, content, overwrite=True, dry_run=dry_run)
+        write_file(plugin_file, content, overwrite=True, dry=dry)
 
         # Find existing vite config (prefer .ts, fall back to .js)
         vite_config_ts = frontend_dir / "vite.config.ts"
         vite_config_js = frontend_dir / "vite.config.js"
 
         if vite_config_ts.exists():
-            patch_vite_config(vite_config_ts, module_name, dry_run)
+            patch_vite_config(vite_config_ts, module_name, dry)
         elif vite_config_js.exists():
-            patch_vite_config(vite_config_js, module_name, dry_run)
+            patch_vite_config(vite_config_js, module_name, dry)
         else:
             print("⚠️  No vite.config.ts or vite.config.js found in frontend/")
             print("   Run create-vue first to generate a Vite config to patch.")
 
         # Patch Vue app with backend health check
-        patch_frontend_health_check(frontend_dir, dry_run)
+        patch_frontend_health_check(frontend_dir, dry)
 
     # === Update pyproject.toml ===
     pyproject_path = project_dir / "pyproject.toml"
@@ -1398,7 +1411,7 @@ def cmd_setup(args: argparse.Namespace) -> int:
 
         if new_content == old_content:
             print(f"✔️  {pyproject_path} (already up to date)")
-        elif dry_run:
+        elif dry:
             print(f"✅ Would update {pyproject_path}")
         else:
             pyproject_path.write_text(new_content, "UTF-8", newline="\n")
@@ -1411,7 +1424,7 @@ def cmd_setup(args: argparse.Namespace) -> int:
         gitignore_content = gitignore_path.read_bytes()
         if b"frontend-build" in gitignore_content:
             print("✔️  .gitignore (frontend-build already ignored)")
-        elif dry_run:
+        elif dry:
             print(f"✅ Would add {gitignore_entry} to .gitignore")
         else:
             nl = b"\r\n" if b"\r\n" in gitignore_content else b"\n"
@@ -1420,15 +1433,15 @@ def cmd_setup(args: argparse.Namespace) -> int:
                 gitignore_content + suffix + gitignore_entry.encode() + nl
             )
             print(f"✅ Added {gitignore_entry} to .gitignore")
-    elif dry_run:
+    elif dry:
         print(f"✅ Would create .gitignore with {gitignore_entry}")
     else:
         gitignore_path.write_text(f"{gitignore_entry}\n", "UTF-8", newline="\n")
         print("✅ Created .gitignore")
 
     # === Add dependencies using uv ===
-    ruff_sort_imports(_python_files_to_format, dry_run=dry_run)
-    if dry_run:
+    ruff_sort_imports(_python_files_to_format, dry=dry)
+    if dry:
         print("📦 Would add: fastapi[standard], fastapi-vue, httpx (dev only)")
     else:
         print("📦 Dependencies")
@@ -1436,12 +1449,10 @@ def cmd_setup(args: argparse.Namespace) -> int:
         uv_add_packages(["httpx"], cwd=project_dir, group="dev")
 
     print()
-    print("=" * 60)
-    print("✅ Setup complete!")
-    print("=" * 60)
+    print_boxed("Setup complete!")
 
     # Show cd command only if project is not in current directory
-    cd_cmd = "" if project_dir == Path.cwd() else f"cd {project_dir}\n   "
+    cd_cmd = "" if project_dir == Path.cwd() else f"cd {project_dir}; "
     script_name = module_name.replace("_", "-")
 
     message = SETUP_COMPLETE_MESSAGE.replace("CD_CMD", cd_cmd).replace(
@@ -1465,11 +1476,6 @@ def cmd_setup(args: argparse.Namespace) -> int:
     return 0
 
 
-# =============================================================================
-# Main entry point
-# =============================================================================
-
-
 def is_uninitialized_folder(path: Path) -> bool:
     """Check if a folder appears to be completely uninitialized."""
     return (
@@ -1492,14 +1498,14 @@ def is_already_patched(path: Path) -> bool:
 
 def main() -> int:
     parser = argparse.ArgumentParser(
-        description="Set up FastAPI+Vue projects with integrated build/dev systems",
+        description=f"fastapi-vue-setup {version} - FastAPI + Vue project setup tool",
         formatter_class=argparse.RawDescriptionHelpFormatter,
         epilog="""
 Examples:
   fastapi-vue-setup my-new-project     Create a new project from scratch
   fastapi-vue-setup .                  Set up integration in current directory
-  fastapi-vue-setup . --dry-run        Preview what would be done
-  fastapi-vue-setup . --ports 8000,5173,8080  Custom ports (default,vite,dev)
+  fastapi-vue-setup . --dry            Preview what would be done
+  fastapi-vue-setup . --ports=8000,5173,8080  Change default ports (backend, vite dev, backend dev)
 """,
     )
     parser.add_argument(
@@ -1508,14 +1514,15 @@ Examples:
         default=None,
         help="Project directory (use . for current directory)",
     )
+    parser.add_argument("--version", action="version", version=version)
     parser.add_argument("--module-name", help="Python module name (auto-detected)")
     parser.add_argument(
         "--ports",
-        metavar="DEFAULT,VITE,DEV",
+        metavar="BACKEND,VITE,DEV",
         help="Port configuration as comma-separated values (default: 3100,3100,3200)",
     )
     parser.add_argument(
-        "--dry-run", action="store_true", help="Show what would be done"
+        "--dry", "--dry-run", action="store_true", help="Show what would be done"
     )
 
     args = parser.parse_args()

template/backend/__main__.py

@@ -5,7 +5,7 @@ import os
 from fastapi_vue import server
 
 DEFAULT_PORT = TEMPLATE_DEFAULT_PORT
-DEVMODE = bool(os.getenv("ENVPREFIX_FRONTEND_URL"))
+DEVMODE = bool(os.getenv("ENVPREFIX_DEV") == "1")
 
 
 def main():
@@ -17,11 +17,12 @@ def main():
         help=(f"Endpoint (default: localhost:{DEFAULT_PORT})."),
     )
     args = parser.parse_args()
+    dev = {"reload": True, "reload_dirs": ["MODULE_NAME"]}
     server.run(
         "MODULE_NAME.APP_MODULE:APP_VAR",
         listen=args.listen,
         default_port=DEFAULT_PORT,
-        reload=DEVMODE,
+        **(dev if DEVMODE else {}),
     )
 
 

template/scripts/devserver.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env -S uv run
 # auto-upgrade@fastapi-vue-setup - remove this if you modify this file
-"""Run Vite development server for frontend and FastAPI backend with auto-reload."""
+"""Run Vite development server for Vue app and FastAPI backend with auto-reload."""
 
 import argparse
 import asyncio
@@ -25,7 +25,7 @@ DEFAULT_DEV_PORT = TEMPLATE_DEV_PORT
 
 
 async def run_devserver(
-    frontend: str, backend: str, extra_args: list[str] | None = None
+    listen: str, backend: str, extra_args: list[str] | None = None
 ) -> None:
     reporoot = Path(__file__).parent.parent
     front = reporoot / "frontend"
@@ -33,12 +33,13 @@ async def run_devserver(
         logger.warning("Frontend source not found at %s", front)
         raise SystemExit(1)
 
-    viteurl, npm_install, vite = setup_vite(frontend, DEFAULT_VITE_PORT)
+    viteurl, npm_install, vite = setup_vite(listen, DEFAULT_VITE_PORT)
     backurl, MODULE_NAME = setup_cli("PROJECT_CLI", backend, DEFAULT_DEV_PORT)
 
-    # Tell the everyone where the frontend and backend are (vite proxy, etc)
-    os.environ["ENVPREFIX_FRONTEND_URL"] = viteurl
+    # Tell the everyone by environment (vite proxy and backend devmode use these)
+    os.environ["ENVPREFIX_VITE_URL"] = viteurl
     os.environ["ENVPREFIX_BACKEND_URL"] = backurl
+    os.environ["ENVPREFIX_DEV"] = "1"
 
     async with ProcessGroup() as pg:
         npm_i = await pg.spawn(*npm_install, cwd=front)
@@ -55,19 +56,18 @@ def main():
         epilog=HELP_EPILOG,
     )
     parser.add_argument(
-        "frontend",
-        nargs="?",
+        "-l", "--listen",
         metavar="host:port",
-        help=f"Vite frontend endpoint (default: localhost:{DEFAULT_VITE_PORT})",
+        help=f"Vite (default: localhost:{DEFAULT_VITE_PORT})",
     )
     parser.add_argument(
         "--backend",
         metavar="host:port",
-        help=f"FastAPI backend endpoint (default: localhost:{DEFAULT_DEV_PORT})",
+        help=f"FastAPI (default: localhost:{DEFAULT_DEV_PORT})",
     )
     args, extra_args = parser.parse_known_args()
     with suppress(KeyboardInterrupt):
-        asyncio.run(run_devserver(args.frontend, args.backend, extra_args))
+        asyncio.run(run_devserver(args.listen, args.backend, extra_args))
 
 
 HELP_EPILOG = """

template/scripts/fastapi-vue/devutil.py

@@ -207,10 +207,5 @@ def setup_cli(
     host = endpoints[0]["host"]
     port = endpoints[0]["port"]
 
-    cmd = [
-        sys.executable,
-        "-m",
-        cli,
-        f"--listen={host}:{port}",
-    ]
+    cmd = [cli, f"--listen={host}:{port}"]
     return f"http://{host}:{port}", cmd