Litestar Fullstack Reference Application

The Litestar Fullstack Reference Application provides a production-ready boilerplate for web APIs. Key features include:

• Backend: Latest Litestar configured with best practices, integrated with SQLAlchemy 2.0, SAQ (Simple Asynchronous Queue), Structlog, and Granian.
• Frontend: Vite-integrated SPA mode and React Email templates compiled to static HTML.
• Authentication: JWT auth with refresh tokens, MFA, OAuth, and admin surfaces.
• Architecture: Team and role management using service/repository patterns and Advanced Alchemy filters.
• Deployment: Multi-stage Docker builds using minimal Python 3.13 runtime images (including distroless variants).

Litestar Fullstack is a reference repository for building production-ready, large-scale fullstack web applications. It provides a complete architecture that you can use in its entirety or extract specific components from.

Key features included out of the box:

• Frontend: A Single Page Application (SPA) built with React 19 and Vite (using litestar-vite).
• Authentication: JWT authentication supporting refresh tokens, Multi-Factor Authentication (MFA), OAuth, and administrative tooling.
• Data Layer: Implementation of the Service/Repository pattern using UUIDv7 primary keys and Advanced Alchemy.
• Background Processing: Background jobs managed via SAQ.
• Observability: Structured logging using structlog.
• Deployment: Dockerized workflows for both development and production environments.
• Testing: A comprehensive test suite for backend features.

In file-based routing, the root layout is defined in src/routes/__root.tsx. The createRootRoute function defines the structure that wraps all routes. Use the <Outlet /> component to specify where the child route content should be rendered.

import { Outlet, createRootRoute } from '@tanstack/react-router'
import { TanStackRouterDevtools } from '@tanstack/react-router-devtools'
import { Link } from "@tanstack/react-router";

export const Route = createRootRoute({
  component: () => (
    <>
      <header>
        <nav>
          <Link to="/">Home</Link>
          <Link to="/about">About</Link>
        </nav>
      </header>
      <Outlet />
      <TanStackRouterDevtools />
    </>
  ),
})

To run the application in development mode, install dependencies and start the development server using npm:

npm install
npm run start

When contributing code to litestar-fullstack, follow this standard workflow:

1. Fork the repository on GitHub.
2. Clone your fork locally.
3. Set up the environment (see Set up the local development environment).
4. Make changes to the code.
5. Lint (Optional): Run make lint to manually run linters and formatters. Note that these are automatically executed by git hooks before commits.
6. Commit your changes using the Conventional Commit format.
7. Push to your fork.
8. Open a Pull Request with a descriptive title (e.g., fix: <description> or feat: <description>).

# Manually run linters and formatters
make lint

To run the application in development mode with Hot Module Replacement (HMR) and the Vite dev server enabled, set the VITE_DEV_MODE environment variable to true and use the uv run app run command. This process starts the Litestar API, SAQ workers (if SAQ_USE_SERVER_LIFESPAN is enabled), and the Vite dev server. Assets are served under /static/web/ by default.

export VITE_DEV_MODE=true
uv run app run

Use the Litestar CLI via uv to manage database migrations:

Generate new migrations:

uv run app database make-migrations

Upgrade database to the latest revision:

uv run app database upgrade

To create a production build of the application, run:

npm run build

The application requires environment variables for proper operation. Start by copying the provided example configuration file to .env.

Key configuration settings include:

• SECRET_KEY: A secure key for the application.
• DATABASE_URL: The connection string for your database.
• APP_URL: The base URL of the application.
• ALLOWED_CORS_ORIGINS: A list of origins allowed to access the API via CORS.

cp .env.local.example .env

To run the entire development environment in a containerized setup, use Docker Compose:

docker compose up