Refactor with new fastapi-vue utility module to run the server, used in CLI main and devserver to run the main app. Default ports made part of templating, so that --ports can be easily specified to fastapi-vue-setup to customize (respects earlier choices when no --ports is specified). New overall default ports 3100, 3200.

fastapi-vue/README.md

@@ -0,0 +1,47 @@
+# 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.
+
+## Installation
+
+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.
+
+```sh
+uvx fastapi-vue-setup --help
+```
+
+Refer to instructions below for further configuration.
+
+## Usage
+
+```python
+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/"],
+)
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    await frontend.load()
+    yield
+
+app = FastAPI(lifespan=lifespan)
+
+# Add API routes here...
+
+# Final catch-all route for frontend files (keep at end of file)
+frontend.route(app, "/")
+```
+
+## Configuration
+
+- `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`)
+- `zstdlevel`: Compression level (default: 18)

fastapi-vue/fastapi_vue/__init__.py

@@ -0,0 +1,3 @@
+from .staticfiles import Frontend
+
+__all__ = ["Frontend"]

fastapi-vue/fastapi_vue/hostutil.py

@@ -0,0 +1,67 @@
+import contextlib
+import ipaddress
+from urllib.parse import urlparse
+
+
+def parse_endpoint(value: str | None, default_port: int = 0) -> list[dict]:
+    """Parse an endpoint string into uvicorn bind configurations.
+
+    Args:
+        value: Endpoint string to parse
+        default_port: Port to use when not specified
+
+    Returns:
+        List of dicts with uvicorn bind kwargs (host/port or uds).
+
+    Supported forms:
+    - None or empty -> [{host: "localhost", port: default_port}]
+    - port (numeric) -> [{host: "localhost", port: port}]
+    - :port -> [{host: "0.0.0.0", port}, {host: "::", port}] (all interfaces)
+    - host:port -> [{host, port}]
+    - host -> [{host, port: default_port}]
+    - [ipv6]:port -> [{host: ipv6, port}]
+    - ipv6 (unbracketed) -> [{host: ipv6, port: default_port}]
+    - /path or unix:/path -> [{uds: path}]
+    """
+    if not value:
+        return [{"host": "localhost", "port": default_port}]
+
+    # Port only (numeric) -> localhost:port
+    if value.isdigit():
+        return [{"host": "localhost", "port": int(value)}]
+
+    # Leading colon :port -> bind all interfaces (0.0.0.0 + ::)
+    if value.startswith(":") and value != ":":
+        port_part = value[1:]
+        if not port_part.isdigit():
+            raise SystemExit(f"Invalid port in '{value}'")
+        port = int(port_part)
+        return [{"host": "0.0.0.0", "port": port}, {"host": "::", "port": port}]  # noqa: S104
+
+    # UNIX domain socket (unix:/path or just /path)
+    if value.startswith("/"):
+        return [{"uds": value}]
+    if value.startswith("unix:"):
+        uds_path = value[5:] or None
+        if uds_path is None:
+            raise SystemExit("unix: path must not be empty")
+        return [{"uds": uds_path}]
+
+    # Unbracketed IPv6 (cannot safely contain a port) -> detect by multiple colons
+    if value.count(":") > 1 and not value.startswith("["):
+        try:
+            ipaddress.IPv6Address(value)
+        except ValueError as e:
+            raise SystemExit(f"Invalid IPv6 address '{value}': {e}") from e
+        return [{"host": value, "port": default_port}]
+
+    # Use urllib.parse for everything else (host[:port], [ipv6][:port])
+    parsed = urlparse(f"//{value}")  # // prefix lets urlparse treat it as netloc
+    host = parsed.hostname or "localhost"
+    port = parsed.port or default_port
+
+    # Validate IP literals (optional; hostname passes through)
+    with contextlib.suppress(ValueError):
+        ipaddress.ip_address(host)
+
+    return [{"host": host, "port": port}]

fastapi-vue/fastapi_vue/server.py

@@ -0,0 +1,78 @@
+import asyncio
+import logging
+import os
+from contextlib import suppress
+
+import uvicorn
+from uvicorn import Config, Server
+
+from .hostutil import parse_endpoint
+
+logger = logging.getLogger(__name__)
+
+
+def run(
+    app: str,
+    *,
+    listen: str | list[str] | None = None,
+    default_port: int = 8000,
+    reload: bool = False,
+    workers: int | None = None,
+    **uvicorn_config,
+):
+    """Run uvicorn server(s) for the given app.
+
+    Args:
+        app: The ASGI application path (e.g., "myapp.main:app")
+        listen: Endpoint string(s) (see parse_endpoint for formats).
+        default_port: Port to use when not specified in listen args.
+        reload: Enable auto-reload (requires uvicorn.run, single endpoint only).
+        workers: Number of worker processes (requires uvicorn.run, single endpoint only).
+        **uvicorn_config: Additional uvicorn config options (overrides all other settings).
+    """
+    if listen is None:
+        listen = [f"localhost:{default_port}"]
+    elif isinstance(listen, str):
+        listen = [listen]
+    endpoints: list[dict] = []
+    for ep in listen:
+        endpoints.extend(parse_endpoint(ep, default_port))
+
+    conf: dict[str, object] = {"app": app, "reload": reload, "workers": workers}
+    proxy = os.getenv("FORWARDED_ALLOW_IPS", "127.0.0.1,::1")
+    if proxy:
+        conf["proxy_headers"] = True
+        conf["forwarded_allow_ips"] = proxy
+    conf.update(uvicorn_config)
+
+    with suppress(KeyboardInterrupt):
+        if reload or workers:
+            serve_multiprocess(endpoints, **conf)
+        else:
+            asyncio.run(serve(endpoints, **conf))
+
+
+async def serve(endpoints: list[dict], **kwargs) -> None:
+    """Serve the given endpoints in current process/loop. Does not spawn extra processes."""
+    forbidden = {"reload", "workers"} & {k for k, v in kwargs.items() if v}
+    if forbidden:
+        logger.warning(
+            "Options %s have no effect in simple mode (multiple endpoints)",
+            ", ".join(sorted(forbidden)),
+        )
+    await asyncio.gather(*(Server(Config(**kwargs, **ep)).serve() for ep in endpoints))
+
+
+def serve_multiprocess(endpoints: list[dict], **kwargs) -> None:
+    """Serve using uvicorn.run() for reload/workers support. Only first endpoint is used."""
+    if len(endpoints) > 1:
+        eps = [
+            ep["uds"] if "uds" in ep else f"{ep['host']}:{ep['port']}"
+            for ep in endpoints
+        ]
+        logger.warning(
+            "Current mode supports only one endpoint. Listening: %s, skipped: %s",
+            eps[0],
+            " ".join(eps[1:]),
+        )
+    uvicorn.run(**kwargs, **endpoints[0])

fastapi-vue/fastapi_vue/staticfiles.py

@@ -0,0 +1,267 @@
+"""FastAPI static file serving with zstd compression and SPA support."""
+
+import logging
+import mimetypes
+import os
+import time
+from base64 import urlsafe_b64encode
+from functools import partial
+from pathlib import Path, PurePath, PurePosixPath
+from wsgiref.handlers import format_date_time
+
+from blake3 import blake3
+from fastapi import FastAPI, Request, Response
+from fastapi.concurrency import run_in_threadpool
+from fastapi.responses import JSONResponse, RedirectResponse
+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
+
+
+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
+    - SPA (Single Page Application) support
+    - Favicon handling from hashed assets
+    - 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
+        zstdlevel: Zstd compression level (default: 18)
+        favicon: Path to favicon for automatic /favicon.ico handling
+    """
+
+    def __init__(
+        self,
+        directory: Path | str,
+        *,
+        index: str = "index.html",
+        spa: bool = False,
+        catch_all: bool | None = None,
+        cached: str | list[str] | None = None,
+        zstdlevel: int = 18,
+        favicon: str | None = None,
+    ) -> 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 = []
+        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
+        self._routes: list[Route] = []
+
+    def _index_only(self) -> set[str]:
+        """Index file paths without loading content (for dev mode)."""
+        paths: set[str] = set()
+        if not self.base.exists():
+            return paths
+        queue = [PurePath()]
+        while queue:
+            current = self.base / queue.pop(0)
+            for p in current.iterdir():
+                rel = p.relative_to(self.base)
+                if p.is_dir():
+                    queue.append(rel)
+                    continue
+                name = "/" + rel.as_posix()
+                name = name.removesuffix(self.index)
+                paths.add(name)
+        if self.favicon:
+            p = PurePosixPath(self.favicon)
+            base = str(p.with_suffix(""))
+            ext = p.suffix
+            if any(path.startswith(base) and path.endswith(ext) for path in paths):
+                paths.add("/favicon.ico")
+        return paths
+
+    def _load(self):
+        """Load static files from disk with compression."""
+        www: dict[str, tuple[bytes, bytes | None, dict]] = {}
+        if not self.base.exists():
+            raise ValueError(f"Frontend folder {self.base} not found (try uv build)")
+        paths = [PurePath()]
+        while paths:
+            current = self.base / paths.pop(0)
+            for p in current.iterdir():
+                rel = p.relative_to(self.base)
+                if p.is_dir():
+                    paths.append(rel)
+                    continue
+                # Read file
+                name = "/" + rel.as_posix()
+                mime = mimetypes.guess_type(name)[0] or "application/octet-stream"
+                name = name.removesuffix(self.index)
+                data = p.read_bytes()
+                etag = urlsafe_b64encode(blake3(data).digest(9)).decode()
+                if mime.startswith("text/"):
+                    mime += "; charset=UTF-8"
+                mtime = p.stat().st_mtime
+                cached = any(name.startswith(prefix) for prefix in self.cached_paths)
+                headers = {
+                    "etag": f'"{etag}"',
+                    "last-modified": format_date_time(mtime),
+                    "cache-control": (
+                        "max-age=31536000, immutable" if cached else "no-cache"
+                    ),
+                    "content-type": mime,
+                }
+                zstd = ZstdCompressor(self.zstdlevel).compress(data)
+                if len(zstd) >= len(data):
+                    zstd = None
+                www[name] = data, zstd, headers
+        if self.favicon:
+            p = PurePosixPath(self.favicon)
+            base = str(p.with_suffix(""))
+            ext = p.suffix
+            hashed_path = next(
+                (path for path in www if path.startswith(base) and path.endswith(ext)),
+                None,
+            )
+            if hashed_path:
+                www["/favicon.ico"] = www[hashed_path]
+        if not www:
+            msg = "Frontend files missing, check your installation.\n"
+            www["/"] = (
+                msg.encode(),
+                None,
+                {
+                    "etag": "error",
+                    "content-type": "text/plain",
+                    "cache-control": "no-store",
+                },
+            )
+        return www
+
+    async def load(self, *, log=True):
+        """Load or reload static files from disk.
+
+        In dev mode (FASTAPI_VUE_FRONTEND_URL set), only indexes paths without loading content.
+        """
+        if self.devmode:
+            # Dev mode: just index paths, no content loading
+            self._devmode_paths = await run_in_threadpool(self._index_only)
+            self._register_routes()
+            return
+
+        start = time.perf_counter()
+        self.www = await run_in_threadpool(self._load)
+        self._register_routes()
+        duration = time.perf_counter() - start
+        if not log:
+            return
+        compfiles = [(len(d), len(z)) for d, z, _ in self.www.values() if z]
+        raw = sum(v[0] for v in compfiles)
+        comp = sum(v[1] for v in compfiles)
+        ratio = comp / raw * 100 if raw else 100.0
+        if log and self.www:
+            logger.info(
+                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} %)"
+            )
+
+    def route(self, app: FastAPI, mount_path="/"):
+        """Register frontend routes with a FastAPI app.
+
+        In SPA/catch-all mode, this must only be called only after all other routes.
+
+        The calling position determines routing priority, although in regular mode the
+        routes are actually added only after load() is called.
+
+        Args:
+            app: FastAPI application instance
+            mount_path: Path where the frontend should be mounted (default: "/")
+        """
+        self._app = app
+        self._mount_path = mount_path.rstrip("/")
+        self._ridx = len(app.routes)
+
+        if self._catch_all:
+            # Register catch-all immediately (works without load)
+            path = self._mount_path + "{path:path}"
+            app.api_route(path, methods=["GET", "HEAD"], name="frontend")(self.handle)
+
+    def _register_routes(self):
+        """Register individual routes for each loaded file (non-catch_all mode)."""
+        if self._app is None or self._catch_all:
+            return
+
+        # Remove previously registered routes (for reload support)
+        for route in list(self._routes):
+            if route in self._app.routes:
+                self._app.routes.remove(route)
+        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()
+        handler = _devmode_respond if self.devmode 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),
+                methods=["GET", "HEAD"],
+                name=f"frontend{p.replace('/', '_')}",
+            )
+            for p in paths
+        ]
+
+    def _respond(self, request: Request, name: str):
+        """Serve a static file with ETag and compression support."""
+        data, zstd, headers = self.www[name]
+        if request.headers.get("if-none-match") == headers["etag"]:
+            return Response(status_code=304, headers=headers)
+        if zstd and "zstd" in request.headers.get("accept-encoding", ""):
+            return Response(
+                content=zstd, headers={**headers, "content-encoding": "zstd"}
+            )
+        return Response(content=data, headers=headers)
+
+    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
+
+        if name not in files:
+            # Friendly redirect for directories missing trailing slash
+            if name and f"{name}/" in files:
+                return RedirectResponse(request.url.path + "/")
+            # SPA support: serve / for unknown paths if the browser wants HTML
+            if self.spa and "text/html" in request.headers.get("accept", ""):
+                name = "/"
+            # 404 for everything else
+            if name not in files:
+                raise HTTPException(status_code=404)
+
+        return (_devmode_respond if self.devmode else self._respond)(request, name)
+
+
+def _devmode_respond(request: Request, name=""):
+    """Return error response directing to Vite server."""
+    return JSONResponse(
+        status_code=409,
+        content={
+            "detail": f"Frontend assets served by Vite in dev mode. Connect via {_DEVMODE} instead."
+        },
+    )

fastapi-vue/pyproject.toml

@@ -0,0 +1,23 @@
+[project]
+name = "fastapi-vue"
+dynamic = ["version"]
+description = "Serves Vue assets on a FastAPI app. Use fastapi-vue-setup tool to add Vue build to your package."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "fastapi>=0.115.0",
+    "zstandard>=0.23.0",
+    "blake3>=1.0.8",
+]
+
+[project.urls]
+Homepage = "https://git.zi.fi/LeoVasanko/fastapi-vue"
+Repository = "https://github.com/LeoVasanko/fastapi-vue"
+
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+source = "vcs"
+raw-options.root = ".."

fastapi_vue_setup.py

@@ -7,6 +7,7 @@ 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
 """
 
@@ -24,6 +25,10 @@ import tomlkit
 # Template directory
 TEMPLATE_DIR = Path(__file__).parent / "template"
 
+# Default ports: (default, vite, dev)
+# If vite == dev, dev is incremented by 100
+DEFAULT_PORTS = (3100, 3100, 3200)
+
 # Marker comment indicating file can be auto-upgraded
 # Users should remove this line to prevent automatic updates
 UPGRADE_MARKER = "auto-upgrade@fastapi-vue-setup"
@@ -117,6 +122,80 @@ Next steps:
 # =============================================================================
 
 
+def parse_ports(ports_str: str | None) -> tuple[int, int, int]:
+    """Parse comma-separated port string into (default, vite, dev) tuple.
+
+    If dev == vite, dev is incremented by 100 to avoid conflicts.
+    """
+    if not ports_str:
+        return DEFAULT_PORTS
+
+    parts = ports_str.split(",")
+    if len(parts) == 1:
+        default = int(parts[0])
+        vite = default
+        dev = default + 100
+    elif len(parts) == 2:
+        default = int(parts[0])
+        vite = int(parts[1])
+        dev = vite + 100 if vite == default else default + 100
+    elif len(parts) == 3:
+        default = int(parts[0])
+        vite = int(parts[1])
+        dev = int(parts[2])
+    else:
+        raise ValueError(f"Invalid ports format: {ports_str}")
+
+    # Auto-adjust dev if it conflicts with vite
+    if dev == vite:
+        dev = vite + 100
+
+    return default, vite, dev
+
+
+def extract_existing_ports(project_dir: Path) -> tuple[int, int, int] | None:
+    """Extract existing port configuration from project files.
+
+    Returns (default, vite, dev) or None if not found.
+    """
+    module_name = find_module_name(project_dir)
+    if not module_name:
+        return None
+
+    default_port = None
+    vite_port = None
+    dev_port = None
+
+    # Try to extract DEFAULT_PORT from __main__.py
+    main_file = project_dir / module_name / "__main__.py"
+    if main_file.exists():
+        content = main_file.read_text("UTF-8")
+        match = re.search(r"DEFAULT_PORT\s*=\s*(\d+)", content)
+        if match:
+            default_port = int(match.group(1))
+
+    # Try to extract ports from devserver.py
+    devserver_file = project_dir / "scripts" / "devserver.py"
+    if devserver_file.exists():
+        content = devserver_file.read_text("UTF-8")
+        match = re.search(r"DEFAULT_VITE_PORT\s*=\s*(\d+)", content)
+        if match:
+            vite_port = int(match.group(1))
+        match = re.search(r"DEFAULT_DEV_PORT\s*=\s*(\d+)", content)
+        if match:
+            dev_port = int(match.group(1))
+
+    # Return only if we found at least one port
+    if default_port is not None or vite_port is not None or dev_port is not None:
+        return (
+            default_port or DEFAULT_PORTS[0],
+            vite_port or DEFAULT_PORTS[1],
+            dev_port or DEFAULT_PORTS[2],
+        )
+
+    return None
+
+
 def load_template(path: str) -> str:
     """Load a template file from the template directory."""
     return (TEMPLATE_DIR / path).read_text("UTF-8")
@@ -943,10 +1022,31 @@ def cmd_setup(args: argparse.Namespace) -> int:
 
     print(f"📦 Module: {module_name}")
 
+    # Determine port configuration
+    # Priority: --ports argument > existing project values > defaults
+    if args.ports:
+        default_port, vite_port, dev_port = parse_ports(args.ports)
+        ports_note = "(--ports)"
+    else:
+        existing_ports = extract_existing_ports(project_dir)
+        if existing_ports:
+            default_port, vite_port, dev_port = existing_ports
+            ports_note = "(kept for upgrade)"
+        else:
+            default_port, vite_port, dev_port = DEFAULT_PORTS
+            ports_note = "(--ports to override)"
+
+    print(
+        f"📡 Ports: default={default_port}, vite={vite_port}, dev={dev_port} {ports_note}"
+    )
+
     # Template variables
     tpl_vars = {
         "MODULE_NAME": module_name,
         "PROJECT_TITLE": project_title,
+        "TEMPLATE_DEFAULT_PORT": str(default_port),
+        "TEMPLATE_VITE_PORT": str(vite_port),
+        "TEMPLATE_DEV_PORT": str(dev_port),
     }
 
     module_dir = project_dir / module_name
@@ -1137,7 +1237,15 @@ def cmd_setup(args: argparse.Namespace) -> int:
         print("✅ Created .gitignore")
 
     # === Add dependencies using uv ===
-    uv_add_main = ["uv", "add", "-q", "-U", "--no-sync", "fastapi[standard]", "fastapi-vue"]
+    uv_add_main = [
+        "uv",
+        "add",
+        "-q",
+        "-U",
+        "--no-sync",
+        "fastapi[standard]",
+        "fastapi-vue",
+    ]
     uv_add_dev = ["uv", "add", "-q", "-U", "--group", "dev", "httpx"]
     if dry_run:
         print(f"[DRY RUN] Would run: {' '.join(uv_add_main)}")
@@ -1215,6 +1323,7 @@ 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)
 """,
     )
     parser.add_argument(
@@ -1224,6 +1333,11 @@ Examples:
         help="Project directory (use . for current directory)",
     )
     parser.add_argument("--module-name", help="Python module name (auto-detected)")
+    parser.add_argument(
+        "--ports",
+        metavar="DEFAULT,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"
     )

scripts/release.py

@@ -0,0 +1,35 @@
+#!/usr/bin/env -S uv run
+"""Build and release both fastapi-vue and fastapi-vue-setup packages."""
+
+import shutil
+import subprocess
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+DIST = ROOT / "dist"
+FASTAPI_VUE = ROOT / "fastapi-vue"
+
+
+def main():
+    # Clear the dist directory
+    if DIST.exists():
+        shutil.rmtree(DIST)
+    DIST.mkdir()
+
+    # Build fastapi-vue (subdirectory) to root dist
+    subprocess.run(
+        ["uv", "build", "--out-dir", str(DIST)],
+        cwd=FASTAPI_VUE,
+        check=True,
+    )
+
+    # Build fastapi-vue-setup (root)
+    subprocess.run(
+        ["uv", "build", "--out-dir", str(DIST)],
+        cwd=ROOT,
+        check=True,
+    )
+
+
+if __name__ == "__main__":
+    main()

template/backend/__main__.py

@@ -1,44 +1,25 @@
 # auto-upgrade@fastapi-vue-setup - remove this if you modify this file
 import argparse
-import asyncio
-import os
 
-from fastapi_vue.hostutil import parse_endpoint
+from fastapi_vue import server
-from uvicorn import Config, Server
 
-DEFAULT_PORT = 5080
+DEFAULT_PORT = TEMPLATE_DEFAULT_PORT
-
-
-def run_server(endpoints: list[dict], *, proxy=""):
-    conf: dict[str, object] = {"app": "MODULE_NAME.APP_MODULE:APP_VAR"}
-    if proxy:
-        conf["proxy_headers"] = True
-        conf["forwarded_allow_ips"] = proxy
-
-    async def serve_all():
-        async with asyncio.TaskGroup() as tg:
-            for ep in endpoints:
-                tg.create_task(Server(Config(**conf, **ep)).serve())
-
-    asyncio.run(serve_all())
 
 
 def main():
     parser = argparse.ArgumentParser(description="Run the MODULE_NAME server.")
     parser.add_argument(
-        "endpoint",
+        "-l",
-        nargs="?",
+        "--listen",
-        help=(
+        action="append",
-            f"Endpoint (default: localhost:{DEFAULT_PORT}). "
+        help=(f"Endpoint (default: localhost:{DEFAULT_PORT})."),
-            "Forms: host:port | :port | [ipv6]:port | ip | host | unix:/path.sock"
-        ),
     )
     args = parser.parse_args()
-    proxy = os.getenv("FORWARDED_ALLOW_IPS", "127.0.0.1,::1")
+    server.run(
-    try:
+        "MODULE_NAME.APP_MODULE:APP_VAR",
-        run_server(parse_endpoint(args.endpoint, DEFAULT_PORT), proxy=proxy)
+        listen=args.listen,
-    except KeyboardInterrupt:
+        default_port=DEFAULT_PORT,
-        pass
+    )
 
 
 if __name__ == "__main__":

template/scripts/devserver.py

@@ -9,6 +9,8 @@ import os
 import sys
 from pathlib import Path
 
+from fastapi_vue import server
+
 # Import util.py from scripts/fastapi-vue (not a package, so we adjust sys.path)
 sys.path.insert(0, str(Path(__file__).with_name("fastapi-vue")))
 from devutil import (  # type: ignore
@@ -20,6 +22,9 @@ from devutil import (  # type: ignore
     setup_vite,
 )
 
+DEFAULT_VITE_PORT = TEMPLATE_VITE_PORT
+DEFAULT_DEV_PORT = TEMPLATE_DEV_PORT
+
 
 async def run_devserver(frontend: str, backend: str) -> None:
     reporoot = Path(__file__).parent.parent
@@ -28,8 +33,10 @@ async def run_devserver(frontend: str, backend: str) -> None:
         logger.warning("Frontend source not found at %s", front)
         raise SystemExit(1)
 
-    viteurl, npm_install, vite = setup_vite(frontend)
+    viteurl, npm_install, vite = setup_vite(frontend, DEFAULT_VITE_PORT)
-    backurl, fastapi = setup_fastapi(backend, "MODULE_NAME.APP_MODULE:APP_VAR")
+    backurl, module, backend_config = setup_fastapi(
+        backend, "MODULE_NAME.APP_MODULE:APP_VAR", DEFAULT_DEV_PORT
+    )
 
     # Tell the everyone where the frontend and backend are (vite proxy, etc)
     os.environ["FASTAPI_VUE_FRONTEND_URL"] = viteurl
@@ -38,13 +45,10 @@ async def run_devserver(frontend: str, backend: str) -> None:
     async with ProcessGroup() as pg:
         npm_i = await pg.spawn(*npm_install, cwd=front)
         await check_ports_free(viteurl, backurl)
-        await pg.spawn(
+
-            *fastapi,
+        # Run backend in a thread (server.run is blocking)
-            "--reload",
+        loop = asyncio.get_event_loop()
-            "--reload-dir=MODULE_NAME",  # Don't reload on frontend changes
+        loop.run_in_executor(None, lambda: server.run(module, **backend_config))
-            "--forwarded-allow-ips=*",
-            cwd=reporoot,
-        )
 
         # Wait for both install and backend to be ready
         await pg.wait(npm_i, ready(backurl, path="/api/health?from=devserver.py"))
@@ -63,12 +67,12 @@ def main():
         "frontend",
         nargs="?",
         metavar="host:port",
-        help="Vite frontend endpoint (default: localhost:5173)",
+        help=f"Vite frontend endpoint (default: localhost:{DEFAULT_VITE_PORT})",
     )
     parser.add_argument(
         "--backend",
         metavar="host:port",
-        help="FastAPI backend endpoint (default: localhost:5180)",
+        help=f"FastAPI backend endpoint (default: localhost:{DEFAULT_DEV_PORT})",
     )
     args = parser.parse_args()
     with contextlib.suppress(KeyboardInterrupt):

template/scripts/fastapi-vue/devutil.py

@@ -3,6 +3,7 @@
 import asyncio
 import subprocess
 from collections.abc import Coroutine
+from contextlib import suppress
 from pathlib import Path
 from typing import Any
 
@@ -10,9 +11,6 @@ import httpx
 from buildutil import find_dev_tool, find_install_tool, logger
 from fastapi_vue.hostutil import parse_endpoint
 
-DEFAULT_VITE_PORT = 5173
-DEFAULT_BACKEND_PORT = 5180
-
 
 class ProcessGroup:
     """Manage async subprocesses with automatic cleanup, like TaskGroup for processes."""
@@ -58,14 +56,7 @@ class ProcessGroup:
 
     async def __aexit__(self, exc_type, *_):
         """Wait for one process to exit, terminate others, then wait for all."""
-        cleanup_task = asyncio.create_task(
+        await self._cleanup(immediate=exc_type is not None)
-            self._cleanup(immediate=exc_type is not None)
-        )
-        try:
-            await asyncio.shield(cleanup_task)
-        except asyncio.CancelledError:
-            # Shield was cancelled but cleanup_task continues - wait for it
-            await cleanup_task
 
     async def _cleanup(self, immediate: bool = False):
         running = [p for p in self._procs if p.returncode is None]
@@ -74,51 +65,49 @@ class ProcessGroup:
 
         if not immediate:
             # Wait for any one process to exit
-            await asyncio.wait(
+            with suppress(asyncio.CancelledError):
-                [asyncio.create_task(p.wait()) for p in running],
+                await asyncio.wait(
-                return_when=asyncio.FIRST_COMPLETED,
+                    [asyncio.create_task(p.wait()) for p in running],
-            )
+                    return_when=asyncio.FIRST_COMPLETED,
+                )
 
         # Terminate remaining processes
         for p in self._procs:
             if p.returncode is None:
-                try:
+                with suppress(ProcessLookupError):
                     p.terminate()
-                except ProcessLookupError:
-                    pass
 
-        # Wait for all to finish (with overall timeout)
+        # Wait for all to finish (with overall timeout), shielded from cancellation
         still_running = [p for p in self._procs if p.returncode is None]
         if still_running:
-            try:
+            with suppress(asyncio.CancelledError):
-                await asyncio.wait_for(
+                try:
-                    asyncio.gather(*[p.wait() for p in still_running]),
+                    await asyncio.shield(
-                    timeout=10,
+                        asyncio.wait_for(
-                )
+                            asyncio.gather(*[p.wait() for p in still_running]),
-            except TimeoutError:
+                            timeout=10,
-                for p in self._procs:
+                        )
-                    if p.returncode is None:
+                    )
-                        try:
+                except TimeoutError:
-                            p.kill()
+                    for p in self._procs:
-                        except ProcessLookupError:
+                        if p.returncode is None:
-                            pass
+                            with suppress(ProcessLookupError):
-                        await p.wait()
+                                p.kill()
+                            await p.wait()
 
 
 async def check_ports_free(*urls: str) -> None:
     """Verify URLs are not responding (ports are free). Raise SystemExit if any respond."""
+
+    async def check(client: httpx.AsyncClient, url: str) -> None:
+        with suppress(httpx.RequestError):
+            res = await client.get(url, timeout=0.1)
+            server = res.headers.get("server", "server")
+            logger.warning("Conflicting %s already running at %s", server, url)
+            raise SystemExit(1)
+
     async with httpx.AsyncClient() as client:
-        for url in urls:
+        await asyncio.gather(*[check(client, url) for url in urls])
-            try:
-                res = await client.get(url, timeout=0.1)
-                logger.warning(
-                    "Conflicting %s already running at %s",
-                    res.headers.get("server", "server"),
-                    url,
-                )
-                raise SystemExit(1)
-            except httpx.RequestError:
-                pass  # Expected - port is free
 
 
 async def ready(url: str, path: str = "") -> None:
@@ -142,13 +131,15 @@ async def ready(url: str, path: str = "") -> None:
                 await asyncio.sleep(0.1)
 
 
-def setup_vite(endpoint: str) -> tuple[str, list[str], list[str]]:
+def setup_vite(
+    endpoint: str, default_port: int = 5173
+) -> tuple[str, list[str], list[str]]:
     """Parse frontend endpoint and build commands.
 
     Returns (url, install_cmd, dev_cmd).
     Raises SystemExit(1) on invalid config.
     """
-    endpoints = parse_endpoint(endpoint, DEFAULT_VITE_PORT)
+    endpoints = parse_endpoint(endpoint, default_port)
 
     if "uds" in endpoints[0]:
         logger.warning("Unix sockets not supported with vite devserver")
@@ -161,18 +152,17 @@ def setup_vite(endpoint: str) -> tuple[str, list[str], list[str]]:
     dev_cmd = find_dev_tool()
     if host != "localhost":
         dev_cmd.append("--host" if len(endpoints) > 1 else f"--host={host}")
-    if port != 5173:
+    dev_cmd.append(f"--port={port}")
-        dev_cmd.append(f"--port={port}")
 
     return f"http://{host}:{port}", install_cmd, dev_cmd
 
 
 def setup_fastapi(
-    endpoint: str, module: str, default_port: int = DEFAULT_BACKEND_PORT
+    endpoint: str, module: str, default_port: int = 8000
-) -> tuple[str, list[str]]:
+) -> tuple[str, str, dict]:
-    """Parse backend endpoint and build fastapi dev command.
+    """Parse backend endpoint and build server.run() config.
 
-    Returns (url, cmd).
+    Returns (url, module, config_dict).
     Raises SystemExit(1) on invalid config.
     """
     endpoints = parse_endpoint(endpoint, default_port)
@@ -184,14 +174,10 @@ def setup_fastapi(
     host = endpoints[0]["host"]
     port = endpoints[0]["port"]
 
-    cmd = [
+    config = {
-        "fastapi",
+        "listen": f"{host}:{port}",
-        "dev",
+        "reload": True,
-        "--entrypoint",
+        "reload_dirs": [module.split(".")[0]],  # Don't reload on frontend changes
-        module,
+        "forwarded_allow_ips": "*",
-        "--host",
+    }
-        host,
+    return f"http://{host}:{port}", module, config
-        "--port",
-        str(port),
-    ]
-    return f"http://{host}:{port}", cmd