QPyServe

One Python command. A real JavaScript frontend. A real FastAPI backend. One origin.

QPyServe connects normal FastAPI applications with plain HTML/JavaScript, React, Vue, or other Vite frontends. It handles local startup, API proxying, frontend dependencies, and production static assets without replacing either framework.

Version 0.3.0: adds development-only QPyServe Trace. For the latest published version see PyPI.

Create an app

Install once:

pip install qpyserve

Create a working HTML + FastAPI app (no Node.js):

qpyserve new hello
cd hello
python main.py

Open http://localhost:1111. Your UI, /api/hello, and /docs share one browser origin. Click Call Python API to see the frontend call your backend.

Prefer React or Vue? Same Python, same command to run:

qpyserve new hello-react --template react
# Or: qpyserve new hello-vue --template vue
cd hello-react
python main.py

React and Vue development require Node.js or a compatible JS runtime/package manager. QPyServe installs missing project dependencies automatically and starts Vite with hot-module replacement (HMR). It does not silently download Node.js.

Built for both humans and AI coding agents

Every generated project is ordinary Python and frontend source code. It also includes a short AGENTS.md describing the API boundary, security expectations, and build commands. No proprietary UI components or code generation at runtime.

For reproducible startup diagnostics:

qpyserve doctor
qpyserve doctor --json  # For AI tools and CI

doctor checks basic development prerequisites and reports actionable errors. It is not a security audit or a load test. It never runs arbitrary project code.

Debug frontend and backend together: QPyServe Trace

Run python main.py and click Trace in the bottom-right corner of your frontend. It shows recent FastAPI requests (HTTP status, route template, request ID, timing and exception type), browser fetch failures, and JavaScript errors in one development panel. Select Copy AI report to copy structured JSON for debugging with an AI assistant. Trace works with plain HTML, React and Vue without changing application code.

Trace is enabled automatically in local development; disabled in production. It does not transmit data to external services, record request/response bodies, capture authorization headers or provide production APM. A copied report should be reviewed before sharing. To opt out, use run(app, trace=False).

Trace documentation · Interactive Trace demo

Integrate into your existing application

You don't need to use a starter. Keep your existing FastAPI application and frontend folder:

from fastapi import FastAPI
from qpyserve import run

app = FastAPI()


@app.get("/api/hello")
def hello():
    return {"message": "Hello from Python"}


if __name__ == "__main__":
    run(app, frontend="frontend", port=1111)

The frontend can call fetch("/api/hello") without a separate browser origin or development CORS workaround.

Existing projects continue to work. QPyServe does not change your FastAPI routes or Vue/React component model. It does not require special npm run dev scripts or a custom framework router.

See the HTML counter and React counter for more examples.

Production

Build the frontend during CI/CD with python main.py --build. Run python main.py --prod with prebuilt assets. Node.js isn't required in the production runtime for static frontends. Plain HTML/JS needs no build.

Place public services behind HTTPS termination, process supervision, and application-specific authentication and rate limiting. QPyServe stays deliberately thin: it does not implement an auth system, database ORM, distributed sessions, a load balancer, or deployment infrastructure.

Optional configuration:

run(
    app,
    frontend="frontend",
    port=1111,
    host="127.0.0.1",
    workers=1,             # Production only
    api_paths=["/ws"],     # Additional API/WebSocket proxy prefixes
    dist="dist",           # Vite output directory
    app_import="main:app", # Only for nonstandard Python entry points
    trace=False,           # Optional: disable local development Trace panel
)

Development mode binds to loopback only, and Vite development must never be exposed as a public production server. External clients use the same /api/* routes as the browser, subject to network and authentication rules. Multi-worker applications must use shared state where appropriate.

Security boundaries

QPyServe blocks common private/development files and escaping symlinks when serving static assets, but anything intentionally placed in a public frontend file can be downloaded. Never place credentials in the frontend; API routes are public unless explicitly protected. A security review of your application is still necessary. See SECURITY.md.

Scope and performance

QPyServe does not claim to be faster than FastAPI or competing frameworks. API and browser performance depend on your application, dependencies, workload, deployment, and caching. It is designed to avoid adding unnecessary abstractions. Benchmark representative workloads before claiming a particular concurrency target.

Supported frontends: plain HTML/JS, React, Vue, and other static Vite projects. Server-rendered Next.js, distributed WebSocket fan-out, and automatic cloud provisioning remain outside scope.

Contributing

python -m pip install -e '.[dev]'
python -m ruff check src tests examples
python -m pytest -q
python -m build

Read CONTRIBUTING.md, AGENTS.md, and RELEASING.md. MIT-licensed.