Determine app module path correctly even when in a submodule. A bit cleaner dev options.

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
+## Quick start
-- **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
 
-## 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
+- project directory: `my-app/`
-uv tool install fastapi-vue-setup
+- Python module: `my_app`
-fastapi-vue-setup --help
+- 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`
+### Production
-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
+Build the Python package (this compiles the Vue frontend) and run the production server:
-
-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.
 
 ```sh
-fastapi-vue-setup .
+uv build && uv run my-app [args]
 ```
 
-### CLI Options
+Once happy with it, publish the package
 
-```
+```sh
-fastapi-vue-setup [project-dir] [options]
+uv build && uv publish
-
-Options:
-  --module-name NAME    Python module name (auto-detected from pyproject.toml)
-  --dry-run             Preview changes without modifying files
 ```
 
-## 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.
+```sh
-
+uvx my-app [args]
-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"] }),
-  ],
-});
 ```
 
-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)
+├── my_app/                      # Python package
-│   ├── __init__.py
 │   ├── __main__.py              # CLI entrypoint
-│   ├── app.py                # FastAPI application
+│   ├── app.py                   # FastAPI app
-│   └── frontend-build/       # Built frontend (gitignored)
+│   └── frontend-build/          # built assets (included in distributions)
-├── scripts/
+├── pyproject.toml
-│   ├── devserver.py          # CLI dev server (only in source tree)
+└── scripts/
-│   └── fastapi-vue/
+    ├── devserver.py             # Run Vite and FastAPI together in dev mode
-│       ├── build-frontend.py
+    └── fastapi-vue/             # Dev utilities (only on the source tree)
-│       └── util.py
+        ├── build-frontend.py
-└── pyproject.toml
+        ├── 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
+ℹ️ 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.
-# 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.

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
+- `fastapi_vue.Frontend`: serves built SPA assets (with SPA support, caching, and optional zstd)
-uvx fastapi-vue-setup --help
+- `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(
+frontend = Frontend(Path(__file__).with_name("frontend-build"), spa=True)
-    Path(__file__).with_name("frontend-build"),
-    spa=True,
-    cached=["/assets/"],
-)
 
 @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
+`Frontend` serves a directory with:
-- `spa`: Enable SPA mode (serve index.html for unknown routes)
+
-- `cached`: Path prefixes for immutable cache headers (browser won't check for changes)
+- RAM caching, with zstd compression when smaller than original
-- `favicon`: Path to serve at `/favicon.ico` (e.g., `"/logo.png"` will be served as `image/png`)
+- 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/fastapi_vue/staticfiles.py

@@ -1,8 +1,10 @@
 """FastAPI static file serving with zstd compression and SPA support."""
 
+from __future__ import annotations
+
+import fnmatch
 import logging
 import mimetypes
-import os
 import time
 from base64 import urlsafe_b64encode
 from functools import partial
@@ -17,29 +19,44 @@ from starlette.exceptions import HTTPException
 from starlette.routing import Route
 from zstandard import ZstdCompressor
 
-# Dev mode: index files but don't load content, return error responses
-_DEVMODE = os.getenv("FASTAPI_VUE_FRONTEND_URL")
-
 logger = logging.getLogger("uvicorn.error")  # Use FastAPI logging style
 
+__all__ = ["Frontend"]
+
+
+class Assets:
+    """Default cached value to /assets/"""
+
+    @staticmethod
+    def parse(cached: str | list[str] | Assets) -> list[str]:
+        match cached:
+            case Assets():
+                return ["/assets/"]
+            case str():
+                return [cached]
+            case list():
+                return cached
+            case _:
+                raise ValueError(f"Invalid cached value: {cached!r}")
+
 
 class Frontend:
     """Static file server with automatic zstd compression and caching.
 
     Features:
     - Automatic zstd compression for compressible files
-    - ETag-based caching with configurable cache headers
+    - ETag-based caching of immutable assets
     - SPA (Single Page Application) support
-    - Favicon handling from hashed assets
+    - /favicon.ico with correct MIME type (image/png etc)
     - Dev mode: indexes files but returns error directing to Vite server
 
     Args:
         directory: Path to the directory containing static files
         index: Name of the index file (default: "index.html")
         spa: Enable SPA mode - serve index.html for unknown routes (default: False)
-        cached: Path prefixes that should have immutable cache headers
+        cached: Path prefixes that are immutable (default: "/assets/")
+        favicon: May use wildcards of full path. E.g. /assets/logo*.png matches logo.hash.png created by Vite
         zstdlevel: Zstd compression level (default: 18)
-        favicon: Path to favicon for automatic /favicon.ico handling
     """
 
     def __init__(
@@ -49,24 +66,18 @@ class Frontend:
         index: str = "index.html",
         spa: bool = False,
         catch_all: bool | None = None,
-        cached: str | list[str] | None = None,
+        cached: str | list[str] | Assets = Assets(),
-        zstdlevel: int = 18,
         favicon: str | None = None,
+        zstdlevel: int = 18,
     ) -> None:
         self.www: dict[str, tuple[bytes, bytes | None, dict]] = {}
         self.base: Path = Path(directory)
         self.index = index
         self.spa = spa
         self._catch_all = spa if catch_all is None else catch_all
-        if cached is None:
+        self.cached_paths = Assets.parse(cached)
-            self.cached_paths = []
-        elif isinstance(cached, str):
-            self.cached_paths = [cached]
-        else:
-            self.cached_paths = cached
         self.zstdlevel = zstdlevel
         self.favicon = favicon
-        self.devmode = bool(_DEVMODE)
         self._app: FastAPI | None = None
         self._mount_path: str = ""
         self._ridx: int = 0
@@ -132,15 +143,11 @@ class Frontend:
                     zstd = None
                 www[name] = data, zstd, headers
         if self.favicon:
-            p = PurePosixPath(self.favicon)
+            if m := fnmatch.filter(www, self.favicon):
-            base = str(p.with_suffix(""))
+                data, zstd, headers = www[m[0]]
-            ext = p.suffix
+                if "immutable" in headers.get("cache-control", ""):
-            hashed_path = next(
+                    headers = {**headers, "cache-control": "max-age=86400"}
-                (path for path in www if path.startswith(base) and path.endswith(ext)),
+                www["/favicon.ico"] = data, zstd, headers
-                None,
-            )
-            if hashed_path:
-                www["/favicon.ico"] = www[hashed_path]
         if not www:
             msg = "Frontend files missing, check your installation.\n"
             www["/"] = (
@@ -154,12 +161,15 @@ class Frontend:
             )
         return www
 
-    async def load(self, *, log=True):
+    async def load(self, *, debug: bool | None = None, log: bool = True):
         """Load or reload static files from disk.
 
-        In dev mode (FASTAPI_VUE_FRONTEND_URL set), only indexes paths without loading content.
+        In debug mode, returns 409 instead of files (avoid accidental use of stale builds)
+        If debug is None, uses app.debug (app passed to frontend.route)
         """
-        if self.devmode:
+        if debug is None:
+            debug = getattr(self._app, "debug", False)
+        if debug:
             # Dev mode: just index paths, no content loading
             self._devmode_paths = await run_in_threadpool(self._index_only)
             self._register_routes()
@@ -180,6 +190,8 @@ class Frontend:
                 f"{self.base.name}: {len(self.www)} files in {1000 * duration:.1f} ms | "
                 f"zstd {len(compfiles)} files {1e-6 * raw:.2f}->{1e-6 * comp:.2f} MB ({ratio:.0f} %)"
             )
+        if self.favicon and "/favicon.ico" not in self.www:
+            logger.warning("Favicon not found: %s", self.favicon)
 
     def route(self, app: FastAPI, mount_path="/"):
         """Register frontend routes with a FastAPI app.
@@ -214,13 +226,14 @@ class Frontend:
         self._routes.clear()
 
         # Get paths and select handler based on mode (checked once, not per request)
-        paths = self._devmode_paths if self.devmode else self.www.keys()
+        debug = getattr(self._app, "debug", False)
-        handler = _devmode_respond if self.devmode else self._respond
+        paths = self._devmode_paths if debug else self.www.keys()
+        handler = _devmode_respond if debug else self._respond
         # Insert at the position where route() was called
         self._app.routes[self._ridx : self._ridx] = self._routes = [
             Route(
                 self._mount_path + p,
-                endpoint=handler if self.devmode else partial(handler, name=p),
+                endpoint=handler if debug else partial(handler, name=p),
                 methods=["GET", "HEAD"],
                 name=f"frontend{p.replace('/', '_')}",
             )
@@ -241,7 +254,8 @@ class Frontend:
     def handle(self, request: Request, path: str):
         """SPA catch-all handler with directory redirects and fallback to index."""
         name = path.removesuffix(self.index)
-        files = self._devmode_paths if self.devmode else self.www
+        debug = getattr(self._app, "debug", False)
+        files = self._devmode_paths if debug else self.www
 
         if name not in files:
             # Friendly redirect for directories missing trailing slash
@@ -254,7 +268,7 @@ class Frontend:
             if name not in files:
                 raise HTTPException(status_code=404)
 
-        return (_devmode_respond if self.devmode else self._respond)(request, name)
+        return (_devmode_respond if debug else self._respond)(request, name)
 
 
 def _devmode_respond(request: Request, name=""):
@@ -262,6 +276,6 @@ def _devmode_respond(request: Request, name=""):
     return JSONResponse(
         status_code=409,
         content={
-            "detail": f"Frontend assets served by Vite in dev mode. Connect via {_DEVMODE} instead."
+            "detail": "[devmode] Not serving frontend files here. Should you connect to Vite instead?"
         },
     )

pyproject.toml

@@ -9,6 +9,7 @@ description = "Tool to create or patch FastAPI+Vue projects with integrated buil
 readme = "README.md"
 requires-python = ">=3.11"
 dependencies = [
+    "ruff>=0.14.13",
     "tomlkit>=0.12.0",
 ]
 
@@ -26,4 +27,7 @@ source = "vcs"
 include = ["fastapi_vue_setup.py", "template/**/*", "_version.py"]
 
 [dependency-groups]
-dev = ["ruff"]
+dev = ["ruff", "fastapi-vue"]
+
+[tool.uv.sources]
+fastapi-vue = { path = "fastapi-vue", editable = true }

template/backend/__main__.py

@@ -1,9 +1,11 @@
 # auto-upgrade@fastapi-vue-setup - remove this if you modify this file
 import argparse
+import os
 
 from fastapi_vue import server
 
 DEFAULT_PORT = TEMPLATE_DEFAULT_PORT
+DEVMODE = os.getenv("ENVPREFIX_DEV") == "1"
 
 
 def main():
@@ -15,10 +17,12 @@ def main():
         help=(f"Endpoint (default: localhost:{DEFAULT_PORT})."),
     )
     args = parser.parse_args()
+    dev = {"reload": True, "reload_dirs": ["paskia"]} if DEVMODE else {}
     server.run(
-        "MODULE_NAME.APP_MODULE:APP_VAR",
+        "APP_MODULE:APP_VAR",
         listen=args.listen,
         default_port=DEFAULT_PORT,
+        **dev,
     )
 
 

template/backend/app.py

@@ -3,9 +3,10 @@ from pathlib import Path
 
 from fastapi import FastAPI
 from fastapi_vue import Frontend
+from MAIN_MODULE import DEVMODE
 
 # Vue Frontend static files
-frontend = Frontend(Path(__file__).with_name("frontend-build"), cached=["/assets/"])
+frontend = Frontend(Path(__file__).with_name("frontend-build"))
 
 
 @asynccontextmanager
@@ -15,7 +16,7 @@ async def lifespan(app: FastAPI):
     yield
 
 
-app = FastAPI(title="PROJECT_TITLE", lifespan=lifespan)
+app = FastAPI(title="PROJECT_TITLE", debug=DEVMODE, lifespan=lifespan)
 
 
 # Add API routes here...

template/frontend/vite-plugin-fastapi.js

@@ -1,17 +1,18 @@
 /**
  * FastAPI-Vue Vite Plugin
+ * auto-upgrade@fastapi-vue-setup -- remove this if you edit the plugin
  *
  * Configures Vite for FastAPI backend integration:
  * - Proxies /api/* requests to the FastAPI backend
  * - Builds to the Python module's frontend-build directory
  *
- * Environment variables (with defaults):
+ * Options:
- *   FASTAPI_VUE_BACKEND_URL=http://localhost:5180 - Backend API URL for proxying
+ *   paths - Array of paths to proxy (default: ["/api"])
  */
 
-const backendUrl = process.env.FASTAPI_VUE_BACKEND_URL || "http://localhost:5180"
-
 export default function fastapiVue({ paths = ["/api"] } = {}) {
+  const backendUrl = process.env.ENVPREFIX_BACKEND_URL || "http://localhost:TEMPLATE_DEV_PORT"
+
   // Build proxy configuration for each path
   const proxy = {}
   for (const path of paths) {
@@ -23,7 +24,7 @@ export default function fastapiVue({ paths = ["/api"] } = {}) {
   }
 
   return {
-    name: "fastapi-vite",
+    name: "vite-plugin-fastapi-MODULE_NAME",
     config: () => ({
       server: { proxy },
       build: {

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
@@ -16,7 +16,7 @@ from devutil import (  # type: ignore
     check_ports_free,
     logger,
     ready,
-    setup_fastapi,
+    setup_cli,
     setup_vite,
 )
 
@@ -24,26 +24,27 @@ DEFAULT_VITE_PORT = TEMPLATE_VITE_PORT
 DEFAULT_DEV_PORT = TEMPLATE_DEV_PORT
 
 
-async def run_devserver(frontend: str, backend: str) -> None:
+async def run_devserver(
+    listen: str, backend: str, extra_args: list[str] | None = None
+) -> None:
     reporoot = Path(__file__).parent.parent
     front = reporoot / "frontend"
     if not (front / "package.json").exists():
         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, uvicorn = setup_fastapi(
+    backurl, MODULE_NAME = setup_cli("PROJECT_CLI", backend, DEFAULT_DEV_PORT)
-        backend, "MODULE_NAME.APP_MODULE:APP_VAR", DEFAULT_DEV_PORT
-    )
 
-    # Tell the everyone where the frontend and backend are (vite proxy, etc)
+    # Tell the everyone by environment (vite proxy and backend devmode use these)
-    os.environ["FASTAPI_VUE_FRONTEND_URL"] = viteurl
+    os.environ["ENVPREFIX_VITE_URL"] = viteurl
-    os.environ["FASTAPI_VUE_BACKEND_URL"] = backurl
+    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)
         await check_ports_free(viteurl, backurl)
-        await pg.spawn(*uvicorn)
+        await pg.spawn(*MODULE_NAME, *(extra_args or []))
         await pg.wait(npm_i, ready(backurl, path="/api/health?from=devserver.py"))
         await pg.spawn(*vite, cwd=front)
 
@@ -55,25 +56,23 @@ def main():
         epilog=HELP_EPILOG,
     )
     parser.add_argument(
-        "frontend",
+        "-l",
-        nargs="?",
+        "--listen",
-        metavar="host:port",
+        metavar="addr",
-        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",
+        metavar="addr",
-        help=f"FastAPI backend endpoint (default: localhost:{DEFAULT_DEV_PORT})",
+        help=f"FastAPI (default: localhost:{DEFAULT_DEV_PORT})",
     )
-    args = parser.parse_args()
+    args, extra_args = parser.parse_known_args()
     with suppress(KeyboardInterrupt):
-        asyncio.run(run_devserver(args.frontend, args.backend))
+        asyncio.run(run_devserver(args.listen, args.backend, extra_args))
 
 
 HELP_EPILOG = """
-  scripts/devserver.py                       # Default ports on localhost
+  Other options are forwarded to PROJECT_CLI [args]
-  scripts/devserver.py 3000                  # Vite on localhost:3000
-  scripts/devserver.py :3000 --backend 8000  # *:3000, localhost:8000
 
   JS_RUNTIME environment variable can be used to select the JS runtime:
   npm, deno, bun, or full path to the runtime executable (node maps to npm).

template/scripts/fastapi-vue/buildutil.py

@@ -134,7 +134,7 @@ def find_dev_tool() -> list[str]:
     Raises RuntimeError if no runtime is found.
     """
     dev_args = {
-        "deno": ("run", "dev", "--"),
+        "deno": ("run", "-A", "npm:vite"),
         "npm": ("--silent", "run", "dev", "--"),
         "bun": ("run", "dev", "--"),
     }

template/scripts/fastapi-vue/devutil.py

@@ -188,3 +188,24 @@ def setup_fastapi(
         "--forwarded-allow-ips=*",
     ]
     return f"http://{host}:{port}", cmd
+
+
+def setup_cli(
+    cli: str, endpoint: str, default_port: int = 8000
+) -> tuple[str, list[str]]:
+    """Parse backend endpoint and build CLI command.
+
+    Returns (url, cli_cmd).
+    Raises SystemExit(1) on invalid config.
+    """
+    endpoints = parse_endpoint(endpoint, default_port)
+
+    if "uds" in endpoints[0]:
+        logger.warning("Unix sockets not supported with vite devserver")
+        raise SystemExit(1)
+
+    host = endpoints[0]["host"]
+    port = endpoints[0]["port"]
+
+    cmd = [cli, f"--listen={host}:{port}"]
+    return f"http://{host}:{port}", cmd