# litestar-fullstack is a copyable Litestar application, not a framework

> The Litestar fullstack reference application shows what a production-shaped Litestar project looks like: a Litestar API with SQLAlchemy through Advanced Alchemy, PostgreSQL, Redis, a SAQ task queue, Vite for the React front end, Granian with uvloop as the server, and a Makefile that drives the whole thing through Docker Compose. It is classified as alpha and versioned 0.3.0, so treat it as a starting point to copy rather than a dependency to install.

**litestar-org/litestar-fullstack** — Litestar Fullstack Reference Application with React, Vite, SQLAlchemy, Docker, Task Queues, and more!

- Repository: https://github.com/litestar-org/litestar-fullstack
- Website: https://fullstack.litestar.dev/
- Stars: 617 · Forks: 88
- Language: Python
- License: MIT
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/litestar-org-litestar-fullstack

## A reference implementation you copy, not a package you install

The repository description calls this a reference application for building a fullstack application with Litestar, with React, Vite, SQLAlchemy, Docker, task queues and more. That framing sets expectations correctly. You read it, copy the parts you want, and delete the rest.

The packaging metadata makes that concrete. The project name is app, the description is a reference application for building a fullstack application with Litestar, and the version is 0.3.0. The keywords list the stack: litestar, sqlalchemy, alembic, fullstack, api, asgi, vite and spa. The console script is registered as app and points at app.__main__:run_cli, which means the application has its own command line entry point rather than relying on a bare uvicorn call.

The repository layout is the shape of the answer. There is a src directory for the application code, a manage.py for project tasks, a tools directory that contains the Docker deployment configuration, a docs directory, a Makefile, a uv.lock for locked dependency versions, a pyproject.toml, an .env.local.example for the environment variables, a pre-commit configuration, a sonar-project.properties file for static analysis, and an editor configuration for Visual Studio Code.

The docs directory is a Sphinx project rather than a folder of markdown files, based on the documentation dependency group, and the live version of the site is published at fullstack.litestar.dev. So the expectation is that you copy the code and read the docs separately.

## The dependency list tells you the whole architecture

The dependencies in pyproject.toml are the clearest description of the architecture, because each one is a deliberate choice about a layer of the stack:

```toml
requires-python = ">=3.11"
dependencies = [
  "litestar[jinja,jwt,structlog,cryptography,pydantic]",
  "advanced-alchemy[uuid,obstore,pwdlib]",
  "redis",
  "psycopg[pool,binary]",
  "python-dotenv",
  "litestar-saq[hiredis]",
  "litestar-vite>=0.15.0b4",
  "litestar-granian[uvloop]",
  "litestar-email[smtp]>=0.3.0",
  "httpx-oauth",
  "pyotp>=2.9.0",
  "qrcode[pil]>=7.4.0",
]
```

The Litestar line is the framework itself, with extras that tell you what is switched on: Jinja for server-side templates, JWT for tokens, structlog for structured logging, cryptography, and Pydantic for data handling. Advanced Alchemy sits on top of SQLAlchemy and brings the ORM layer, with extras for UUID support, obstore for object storage and pwdlib for password hashing.

The infrastructure is explicit rather than implied. Redis is there for caching and for the queue. psycopg with the pool and binary extras is the PostgreSQL driver, so the database is Postgres and the connection is pooled. python-dotenv handles the environment file.

Then the two integrations that make this more than a CRUD skeleton. litestar-saq with hiredis gives you a task queue on top of Redis, which is the standard way this kind of application offloads slow work. litestar-vite integrates the Vite front end build into the Python tooling, and it is the front end side of the React application. litestar-granian with uvloop is the ASGI server, with uvloop as the event loop, which is the performance-conscious choice.

The tail of the list describes account features rather than plumbing: litestar-email with the smtp extra for outbound mail, httpx-oauth for talking to OAuth providers over HTTP, and pyotp together with qrcode for time-based one-time passwords and the QR codes that carry the enrolment secret. That pairing is the fingerprint of a login flow with multi-factor authentication, and it is the kind of detail a reference application is supposed to show you.

One entry deserves a flag rather than praise: litestar-vite is pinned to a version that is itself a beta, 0.15.0b4. A reference application depending on a prerelease of one of its own ecosystem plugins is fine for a template, but it is a reminder that this stack moves.

## Python 3.11 minimum, three supported versions, and typed code

The metadata is precise about the runtime. The project requires Python 3.11 or newer, and the classifiers list support for 3.11, 3.12 and 3.13, plus a generic Python 3 entry. The OS Independent classifier means it is not tied to a platform, and there is a Typing :: Typed classifier, so the package ships type information and the project claims to be typed rather than merely annotated.

The declared development status is the number that matters most for anyone planning to base a product on this. The classifiers include Development Status :: 3 - Alpha. The application is versioned 0.3.0, which by convention means the interfaces may still change.

The dependency management is modern in a way worth copying. There is a uv.lock file, and the Makefile has an install-uv target that fetches the installer from the upstream script, so the intended workflow pins the toolchain rather than relying on whatever pip and a global environment happen to provide.

The dependency groups are split by purpose, which is a pattern worth stealing. The dev group includes the docs, linting and test groups, and each of those is defined separately: docs with Sphinx and its extensions including a mermaid extension, linting with pre-commit, and a test group. The single dev group then pulls the three in, so a contributor installs everything with one command while the groups stay individually usable.

A pyproject.toml with named groups and a lock file is the current shape of a Python project that expects to be developed by more than one person.

## The Makefile is the entry point, and Docker Compose is the environment

Rather than documenting a long list of commands, the project drives everything through a Makefile whose default goal prints help.

The Makefile is written for bash, with shell command chaining enabled, all variables exported to sub-processes, and no directory printing, which keeps the output readable. The help target is implemented with awk and prints one line per target taken from the comment field, so the target list is generated from the file itself.

The Docker topology is defined at the top of the file. The compose directory is tools/deploy/docker, and there are two compose files: docker-compose.infra.yml for the infrastructure and docker-compose.yml for the application itself. The compose project name is set to fullstack-spa, which tells you the front end is a single page application in the setup. The variables are named so that a target can build the infrastructure stack separately from the app stack, which is the arrangement you want when the database and Redis are long lived and the app container is rebuilt often.

The developer utility targets are explicit about their tools. There is an install-uv target that installs the latest version of uv by piping the upstream install script, and an install-bun target for Bun, which is the JavaScript runtime the front end tooling uses, matching the Vite and React side of the stack.

So the intended first run is: install the two runtimes, bring up the infrastructure, build the front end, and start the application through the app compose file. Every one of those steps is a make target, which means the sequence is the same for everyone on the team.

## Alpha status, and quality tooling that shows the intent

The badge table at the top of the README is where the project's engineering process is visible, and it is the only prose the README has, since the rest of the file is badges and links.

There is a CI/CD row with a Tests and Linting workflow badge. There is a Quality row with SonarCloud badges for coverage, quality gate status, maintainability rating, reliability rating and security rating. There is a Community row with links to the project's Reddit community, Discord, Matrix, Medium, Twitter and blog. And there is a Meta row pointing at the main Litestar project and a mypy typing badge.

The SonarCloud set is the informative one. A quality gate badge implies that the build fails when a metric regresses, and the coverage badge points at the summary for new code, which is the stricter measurement, since it ignores what is already tested. For a reference application, that matters more than usual: the value of the project is that its patterns are sound, and a gate on new code is how a template keeps that property as it evolves.

The repository contents back this up. There is a pre-commit configuration, so formatting and lint checks run before a commit rather than only in CI. There is a sonar-project.properties file to configure the analysis. There is a .prettierrc in the tree as well, which covers the front end side. And the top level has an .editorconfig and a .dockerignore.

The maintenance position is easy to read from the record. The repository is not archived, the last push was on 2026-10-10, and it publishes no GitHub releases, so there is no version tag to pin and no changelog release list to track. For a template, that is an acceptable trade, but it does mean the app you copy is whatever the main branch holds on the day you copy it.

## What a reference application cannot tell you

Three limitations are worth keeping in mind when you copy this project.

The first is that it shows happy paths. Every reference application demonstrates the intended way to do something: how to define a route, how to run a query through the ORM, how to enqueue a job, how to send an email. What it does not show is how the project you are building will handle the awkward cases, because those are specific to your domain. Treat the patterns as patterns and write your own failure handling, retries, timeouts and observability.

The second is that the versions will drift. Version 0.3.0 with an alpha development status means the structure of the example changes over time. If you copy it, you own that copy, and you will be the one dealing with the Litestar, SQLAlchemy or Vite upgrade that breaks it. The value of the example decays as the framework moves, and it moved quickly here, since one of the dependencies is itself a beta release.

The third is that the front end is the part you will replace. The project is a React and Vite single page application, which is a sensible default, but the React choice is not derived from anything about your problem, and the same is true of the choice of a relational database with a Postgres driver. The parts worth copying are the ones where the choices are hard to make well, which here means the task queue integration, the password and multi-factor handling, the OAuth flow, the structured logging and the environment handling.

One more practical note. The presence of manage.py alongside a project whose console script is registered as app suggests two entry points into the same project, and the README does not explain the division of labour between them. Read both before you decide which one drives your workflows.

## Conclusion

litestar-fullstack fits a team starting a new Litestar service that wants a working database, task queue, front end build and container setup to copy instead of assembling from documentation. It does not fit a team that wants a library to depend on, since the package is named app and carries an alpha development status. Before you copy it, check the Python version you have against the 3.11 minimum, note that the front end build depends on a beta release of litestar-vite, and expect the layout to change, since the project is at version 0.3.0. The last push was on 2026-10-10 and the repository publishes no GitHub releases.

## FAQ

### What is the litestar-fullstack repository?

It is a reference application for building a fullstack application with Litestar, with React, Vite, SQLAlchemy, Docker and task queues. The package is named app, is versioned 0.3.0, is MIT licensed, and its console script is registered as app pointing at app.__main__:run_cli.

### What database and task queue does litestar-fullstack use?

The dependency list shows PostgreSQL through the psycopg driver with pooling, Redis, and Advanced Alchemy on top of SQLAlchemy. Background work is handled by litestar-saq with hiredis, which puts the queue on Redis.

### Which Python versions does litestar-fullstack support?

The project metadata requires Python 3.11 or newer, and the classifiers list Python 3.11, 3.12 and 3.13. The development status classifier is Development Status :: 3 - Alpha.

### How is the local environment set up in litestar-fullstack?

Through a Makefile whose default goal prints help and whose targets include install-uv and install-bun. The Docker setup lives in tools/deploy/docker with a separate compose file for infrastructure and one for the application, and the compose project name is fullstack-spa.

## Sources

- [Issues](https://github.com/litestar-org/litestar-fullstack/issues)
- [License: MIT](https://github.com/litestar-org/litestar-fullstack/blob/main/LICENSE)
- [litestar-org/litestar-fullstack on GitHub](https://github.com/litestar-org/litestar-fullstack)
- [Project website](https://fullstack.litestar.dev/)
- [README](https://github.com/litestar-org/litestar-fullstack/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/litestar-org-litestar-fullstack