# full-stack-fastapi-template: a working FastAPI, React and PostgreSQL starting point

> The template ships a FastAPI backend, a React frontend served on the same domain, SQLModel over PostgreSQL, Traefik with automatic HTTPS and GitHub Actions CI. It is a scaffold to copy, not a library to install, and the parts it leaves open are worth knowing before you commit.

**fastapi/full-stack-fastapi-template** — Production-ready full-stack web app template combining a FastAPI backend, React and TypeScript frontend, PostgreSQL, Docker, JWT auth and automatic HTTPS.

- Repository: https://github.com/fastapi/full-stack-fastapi-template
- Stars: 45,810 · Forks: 9,110
- Language: TypeScript
- License: MIT
- Published: 2026-08-08 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/fastapi-full-stack-fastapi-template

## What full-stack-fastapi-template actually hands you

This is a repository you copy, not a package you add to an existing project. The README's instruction is a single line: click the Use this template button at the top of the page to create a new repository. Everything after that is your code.

The stack is deliberately narrow. FastAPI handles the API, SQLModel handles database access and Pydantic handles validation and settings, PostgreSQL is the database, and React with TypeScript and Vite is the frontend. The frontend is not a separate deployment: the README says it is built into the backend application and served by FastAPI on the same domain as the API. That single decision removes CORS configuration and cookie-domain problems from day one, and it also means your frontend release and backend release are one artifact.

Authentication is included rather than sketched. The README lists secure password hashing by default, JWT authentication, and email-based password recovery. Mailpit is wired in for local email testing, and React Email supplies the templates. For a team that has spent a week wiring password reset flows by hand, that is the real value here: the boring, security-adjacent parts are already assembled and covered by tests.

The audience is specific. A solo developer starting a small product, or a team that wants a Python API with a typed React client and does not want to argue about project layout, fits. Someone who wants a minimal API with no frontend, or who already has strong opinions about a different ORM, will spend more time deleting than building.

## How the pieces talk to each other

The architecture is visible in compose.yml. A proxy service runs traefik:v3.7 with the Docker socket mounted read-only, so Traefik reads labels from other containers. It is started with --providers.docker and --providers.docker.exposedbydefault=false, which means a service is only reachable if it carries an explicit traefik.enable=true label. The entrypoint is named http and listens on port 80.

The db service is postgres:18 with a healthcheck running pg_isready -U postgres -d app, and a named volume app-db-data mounted at /var/lib/postgresql. The backend service declares depends_on db with condition: service_healthy and restart: true, so the API container waits for a database that answers rather than for a container that merely started. That detail matters more than it looks: it is the difference between a clean first boot and a race that fails intermittently.

Adminer is included as a browser database client. It is exposed through a Traefik label with the rule Host(`adminer.${DOMAIN:-localhost}`) and the internal port 8080, so in local development it answers on adminer.localhost. Because exposedbydefault is false, nothing else in the compose file becomes publicly routable by accident.

The backend reads required environment variables with the ${VAR:?Variable not set} form, including PROJECT_NAME, SECRET_KEY and POSTGRES_PASSWORD. That syntax makes Docker Compose refuse to start when a variable is missing, which turns a silent misconfiguration into a startup error. The trade-off is that compose.yml is not runnable on its own; you need the .env file populated first.

## Installing it and getting a first login

There is no install command for the template itself, because the template is a repository. The README says to click Use this template on GitHub, and the repository also lists .env at the top level, so the first real step after cloning is filling that file. The compose file will not start without it: PROJECT_NAME, SECRET_KEY and POSTGRES_PASSWORD are all declared with the required-variable form, and Docker Compose errors out when one is absent.

Once .env has values, the local services come up through Docker Compose. The repository ships compose.yml alongside compose.override.yml, and the override file is the one meant for local work. The README points to development.md for the local FastAPI and Vite workflow, the Docker Compose services and the .env configuration, and that is the file to read before changing how the two run together.

After the containers report healthy, the API and its interactive documentation are served by the backend, and Adminer is routed at the adminer subdomain. With the default DOMAIN value of localhost, that is adminer.localhost. The README lists Mailpit as the local email testing tool, which is where password recovery messages land during development instead of going to a real inbox.

Frontend work runs through the root package.json, which is a Bun workspace covering frontend and packages/*. The scripts are short and worth reading before you invent your own. The dev script filters to the frontend package, test runs the frontend tests, test:ui opens the Playwright UI, and email:dev starts the React Email preview for template work.

## Where the template stops helping

The repository is a scaffold, and scaffolds go stale in the places they do not touch. There is no migration tool in the listed stack. SQLModel is named for database interactions, but nothing in the README mentions Alembic or any other schema migration path, so the moment your models change in production you are choosing and wiring that yourself. For a template that ships CI and deployment documentation, the absence is conspicuous.

Local development depends on Docker. compose.yml, compose.override.yml and compose.deploy.yml are the described paths for services and self-hosted deployment, and the backend service expects a healthy Postgres and a populated .env before it will start. If your machine or your CI runner cannot run containers, this template is the wrong shape. The README does not document a non-Docker development route.

The database choice is effectively fixed. The compose file pins postgres:18 and the Adminer service is configured for it. People search for a MySQL variant, and the repository gives no indication that one exists; swapping engines would mean rewriting the service definitions and revalidating the SQLModel layer, not editing a variable.

Finally, the template is opinionated about where the frontend lives. Because React is built into the backend and served from the same domain, splitting the two later into separate deployments is a restructuring project, not a configuration change. Teams that expect to scale the frontend independently should decide that before they build on this layout.

## Alternatives and how they differ

The closest comparison is doing it yourself from the FastAPI documentation. FastAPI's own docs give you the application framework and the dependency injection model, and nothing else. You would add an ORM, a database driver, a frontend build, a reverse proxy, a test setup and a CI pipeline, and you would make each of those decisions in isolation. The template's contribution is that those decisions are already made and already consistent with each other: the JWT auth, the password recovery flow, the generated frontend client and the Playwright tests all assume the same project shape.

A second alternative is a heavier, batteries-included Python web framework with an admin panel and a built-in ORM migration story. That gets you migrations and an admin interface out of the box, at the cost of a single framework owning the request lifecycle, the ORM and the templating. This template keeps FastAPI as the API layer and React as the UI, which means two languages and two toolchains, but also means your frontend engineers are not writing against a Python templating system.

There is no competitor named in the repository, and the README does not position the template against anything. The honest framing is that the alternative is almost always the same stack assembled by hand, and the question is whether the assembled version would include the auth flows, the email templates, the reverse proxy configuration and the test scaffolding that this one already contains.

## Maintenance, upgrades and the MIT licence

The last push to the default branch was on 2026-08-12, and the most recent release, 0.12.0, carries the same date. Version 0.11.1 and 0.11.0 landed the day before. That release cadence is recent enough that the project is not abandoned, and the repository is not archived.

Upgrade cost is the part templates usually hide. Because you copy the repository rather than depend on a published package, there is no version to bump. Upstream changes arrive as commits you either merge or ignore, and the longer you build on top, the more of those merges conflict with your own work. A team that has rewritten the auth layer will find little value in an upstream auth fix and real pain in the merge. The practical approach is to treat upstream as a source of ideas and security fixes you cherry-pick, not a branch you track continuously.

Dependency drift is the other cost. The compose file pins traefik:v3.7 and postgres:18, and the root pyproject.toml declares a dev dependency group containing prek, typer and zizmor, plus a github-actions group with smokeshow, under a uv workspace with backend as its member. Those pins age. Nothing in the repository schedules that work for you.

The licence is MIT, stated in the README and shipped as a LICENSE file at the top level. MIT is permissive and places few conditions on reuse, but the repository is a template rather than a library, so the practical question is not whether you may reuse it. It is whether the code you inherit still matches the versions of FastAPI, SQLModel and React you intend to run. That is a question for your own review, not for the licence text.

## Conclusion

Adopt it if you want a FastAPI and React codebase that already has JWT auth, password recovery, a generated frontend client, Playwright tests and CI wired together, and you are willing to read backend/README.md, frontend/README.md and development.md rather than guess. Do not adopt it if your team has no Docker, because compose.yml is the local and self-hosted path, or if you need MySQL, since the compose file pins postgres:18 and nothing in the repository suggests a swap. Before writing product code, verify the .env variables the backend requires, confirm which compose file you are running, and pick your deployment route between FastAPI Cloud and Docker Compose, because the two are documented separately and lead to different operational shapes.

## FAQ

### How do I use full-stack-fastapi-template?

The README says to click the Use this template button at the top of the repository page to create a new repository, then populate the .env file, since compose.yml requires PROJECT_NAME, SECRET_KEY and POSTGRES_PASSWORD before the services will start. From there, development.md covers the local FastAPI and Vite workflow.

### Can I deploy full-stack-fastapi-template for free?

The README lists two documented routes, FastAPI Cloud in deployment.md and self-hosted deployment with Docker Compose in deployment-docker-compose.md. The repository does not state pricing for either, so cost depends on the host you choose rather than on the template.

### Does FastAPI still support templates?

FastAPI itself is the backend framework here, and the frontend is React rather than server-rendered templates. The README states the React frontend is built into the backend application and served by FastAPI on the same domain as the API.

### Is FastAPI still the best choice for this stack?

The repository does not rank FastAPI against other frameworks. It pairs FastAPI with SQLModel, Pydantic and PostgreSQL on the backend, and the README presents that combination as the stack rather than as a comparison.

### Is there a cheat sheet for full-stack-fastapi-template?

The repository does not ship one. The closest equivalents are development.md, which the README says covers the local FastAPI and Vite workflow, the Docker Compose services and the .env configuration, plus backend/README.md and frontend/README.md.

## Sources

- [Official README](https://github.com/fastapi/full-stack-fastapi-template#readme)
- [Project repository](https://github.com/fastapi/full-stack-fastapi-template)
- [Release notes](https://github.com/fastapi/full-stack-fastapi-template/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/fastapi-full-stack-fastapi-template