{"id":13691443,"url":"https://github.com/litestar-org/litestar-fullstack","last_synced_at":"2025-05-15T17:08:50.549Z","repository":{"id":60106503,"uuid":"536385962","full_name":"litestar-org/litestar-fullstack","owner":"litestar-org","description":"Litestar Fullstack Reference Application with React, Vite, SQLAlchemy, Docker, Task Queues, and more!","archived":false,"fork":false,"pushed_at":"2025-05-04T17:23:42.000Z","size":17673,"stargazers_count":434,"open_issues_count":17,"forks_count":70,"subscribers_count":18,"default_branch":"main","last_synced_at":"2025-05-04T18:26:20.585Z","etag":null,"topics":["hacktoberfest","litestar","litestar-api","litestar-framework","litestar-template","reactjs","saq","sqlalchemy","starlite","starlite-api","starlite-framework","starlite-template","vite"],"latest_commit_sha":null,"homepage":"https://fullstack.litestar.dev/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/litestar-org.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.rst","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["litestar-org"],"open_collective":"litestar","polar":"litestar-org"}},"created_at":"2022-09-14T02:35:47.000Z","updated_at":"2025-05-03T06:39:40.000Z","dependencies_parsed_at":"2024-01-23T20:14:23.818Z","dependency_job_id":"0791bcbc-4553-42a5-84c2-78beedba6218","html_url":"https://github.com/litestar-org/litestar-fullstack","commit_stats":{"total_commits":350,"total_committers":26,"mean_commits":"13.461538461538462","dds":0.4771428571428571,"last_synced_commit":"43428244b5809d9d0fc75af9a7433717f8770c38"},"previous_names":["litestar-org/litestar-fullstack","cofin/starlite-full-stack-example"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/litestar-org%2Flitestar-fullstack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/litestar-org%2Flitestar-fullstack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/litestar-org%2Flitestar-fullstack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/litestar-org%2Flitestar-fullstack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/litestar-org","download_url":"https://codeload.github.com/litestar-org/litestar-fullstack/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254384989,"owners_count":22062422,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hacktoberfest","litestar","litestar-api","litestar-framework","litestar-template","reactjs","saq","sqlalchemy","starlite","starlite-api","starlite-framework","starlite-template","vite"],"created_at":"2024-08-02T17:00:45.154Z","updated_at":"2025-05-15T17:08:45.537Z","avatar_url":"https://github.com/litestar-org.png","language":"Python","funding_links":["https://github.com/sponsors/litestar-org","https://opencollective.com/litestar","https://polar.sh/litestar-org"],"categories":["Python","Third-Party Extensions","Litestar"],"sub_categories":["Projects","Table of Content"],"readme":"\u003c!-- markdownlint-disable --\u003e\n\u003cp align=\"center\"\u003e\n \u003cimg src=\"https://raw.githubusercontent.com/litestar-org/branding/1dc4635b192d29d864fcee6f3f73ea0ff6fecf10/assets/Branding%20-%20SVG%20-%20Transparent/Fullstack%20-%20Banner%20-%20Inline%20-%20Light.svg#gh-light-mode-only\" alt=\"Litestar Logo - Light\" width=\"100%\" height=\"auto\" /\u003e\n \u003cimg src=\"https://raw.githubusercontent.com/litestar-org/branding/1dc4635b192d29d864fcee6f3f73ea0ff6fecf10/assets/Branding%20-%20SVG%20-%20Transparent/Fullstack%20-%20Banner%20-%20Inline%20-%20Dark.svg#gh-dark-mode-only\" alt=\"Litestar Logo - Dark\" width=\"100%\" height=\"auto\" /\u003e\n\u003c/p\u003e\n\u003c!-- markdownlint-restore --\u003e\n\n\u003cdiv align=\"center\"\u003e\n\u003c!-- prettier-ignore-start --\u003e\n\n| Project | | Status |\n| --------- | :-- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| CI/CD | | [![Tests and Linting](https://github.com/litestar-org/litestar-fullstack/actions/workflows/ci.yaml/badge.svg)](https://github.com/litestar-org/litestar-fullstack/actions/workflows/ci.yaml) [![Documentation Building](https://github.com/litestar-org/litestar-fullstack/actions/workflows/docs.yaml/badge.svg)](https://github.com/litestar-org/litestar-fullstack/actions/workflows/docs.yaml) |\n| Quality | | [![Coverage](https://sonarcloud.io/api/project_badges/measure?project=litestar-org_litestar-fullstack\u0026metric=coverage)](https://sonarcloud.io/summary/new_code?id=litestar-org_litestar) [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=litestar-org_litestar-fullstack\u0026metric=alert_status)](https://sonarcloud.io/summary/new_code?id=litestar-org_litestar) [![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=litestar-org_litestar-fullstack\u0026metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=litestar-org_litestar) [![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=litestar-org_litestar-fullstack\u0026metric=reliability_rating)](https://sonarcloud.io/summary/new_code?id=litestar-org_litestar) [![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=litestar-org_litestar-fullstack\u0026metric=security_rating)](https://sonarcloud.io/summary/new_code?id=litestar-org_litestar) |\n| Community | | [![Reddit](https://img.shields.io/reddit/subreddit-subscribers/litestarapi?label=r%2FLitestar\u0026logo=reddit\u0026labelColor=202235\u0026color=edb641\u0026logoColor=edb641)](https://reddit.com/r/litestarapi) [![Discord](https://img.shields.io/discord/919193495116337154?labelColor=202235\u0026color=edb641\u0026label=chat%20on%20discord\u0026logo=discord\u0026logoColor=edb641)](https://discord.gg/litestar) [![Matrix](https://img.shields.io/badge/chat%20on%20Matrix-bridged-202235?labelColor=202235\u0026color=edb641\u0026logo=matrix\u0026logoColor=edb641)](https://matrix.to/#/#litestar:matrix.org) [![Medium](https://img.shields.io/badge/Medium-202235?labelColor=202235\u0026color=edb641\u0026logo=medium\u0026logoColor=edb641)](https://blog.litestar.dev) [![Twitter](https://img.shields.io/twitter/follow/LitestarAPI?labelColor=202235\u0026color=edb641\u0026logo=twitter\u0026logoColor=edb641\u0026style=flat)](https://twitter.com/LitestarAPI) [![Blog](https://img.shields.io/badge/Blog-litestar.dev-202235?logo=blogger\u0026labelColor=202235\u0026color=edb641\u0026logoColor=edb641)](https://blog.litestar.dev) |\n| Meta | | [![Litestar Project](https://img.shields.io/badge/Litestar%20Org-%E2%AD%90%20Litestar-202235.svg?logo=python\u0026labelColor=202235\u0026color=edb641\u0026logoColor=edb641)](https://github.com/litestar-org/litestar) [![types - Mypy](https://img.shields.io/badge/types-Mypy-202235.svg?logo=python\u0026labelColor=202235\u0026color=edb641\u0026logoColor=edb641)](https://github.com/python/mypy) [![License - MIT](https://img.shields.io/badge/license-MIT-202235.svg?logo=python\u0026labelColor=202235\u0026color=edb641\u0026logoColor=edb641)](https://spdx.org/licenses/) [![Litestar Sponsors](https://img.shields.io/badge/Sponsor-%E2%9D%A4-%23edb641.svg?\u0026logo=github\u0026logoColor=edb641\u0026labelColor=202235)](https://github.com/sponsors/litestar-org) [![linting - Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v2.json\u0026labelColor=202235)](https://github.com/astral-sh/ruff) [![code style - Black](https://img.shields.io/badge/code%20style-black-000000.svg?logo=python\u0026labelColor=202235\u0026logoColor=edb641)](https://github.com/psf/black) [![All Contributors](https://img.shields.io/github/all-contributors/litestar-org/litestar?labelColor=202235\u0026color=edb641\u0026logoColor=edb641)](#contributors-) |\n\n\u003c!-- prettier-ignore-end --\u003e\n\u003c/div\u003e\n\n# Litestar Fullstack Reference Application\n\nThis is a reference application that you can use to get your next Litestar application running quickly.\n\nIt contains most of the boilerplate required for a production web API with features like:\n\n- Latest Litestar configured with best practices\n- Integration with [SQLAlchemy 2.0](https://www.sqlalchemy.org/), [SAQ (Simple Asynchronous Queue)](https://saq-py.readthedocs.io/en/latest/), [Structlog](https://www.structlog.org/en/stable/), and [Granian](\u003c(https://www.structlog.org/en/stable/)](https://github.com/emmett-framework/granian)\u003e)\n- Extends built-in Litestar click CLI\n- Frontend integrated with Vite and includes Jinja2 templates that integrate with Vite websocket/HMR support\n- Multi-stage Docker build using a minimal Python 3.13 runtime image.\n - Optional Multi-stage Distroless Docker build.\n- Pre-configured user model that includes teams and associated team roles\n- Examples of using guards for superuser and team-based auth.\n- Examples using raw SQL for more complex queries\n\nTake what you need and adapt it to your own projects\n\n## Quick Start\n\nTo quickly get a development environment running, run the following:\n\n```shell\nmake install\n. .venv/bin/activate\n```\n\n### Local Development\n\n```bash\ncp .env.local.example .env\nmake start-infra # this starts a database and redis instance only\n# this will start the SAQ worker, Vite development process, and Litestar\nuv run app run\n\n# to stop the database and redis, run\nmake stop-infra\n```\n\n### Docker\n\nIf you want to run the entire development environment containerized, you can run the following:\n\n```bash\ndocker compose up\n```\n\n### Details\n\nWe have documented the process to help you get the repository up and running.\nCheck out the [documentation][docs] for more information.\n\n[//]: # \"links\"\n[docs]: https://docs.fullstack.litestar.dev/\n\n\u003cdetails\u003e\n\n\u003csummary\u003eCommand Examples\u003c/summary\u003e\n\n## App Commands\n\n```bash\n❯ app\n\n Usage: app [OPTIONS] COMMAND [ARGS]...\n\n Litestar CLI.\n\n╭─ Options ────────────────────────────────────────────────────────────────────╮\n│ --app TEXT Module path to a Litestar application (TEXT) │\n│ --app-dir DIRECTORY Look for APP in the specified directory, by adding │\n│ this to the PYTHONPATH. Defaults to the current │\n│ working directory. │\n│ (DIRECTORY) │\n│ --help -h Show this message and exit. │\n╰──────────────────────────────────────────────────────────────────────────────╯\nUsing Litestar app from env: 'app.asgi:app'\nLoading environment configuration from .env\n╭─ Commands ───────────────────────────────────────────────────────────────────╮\n│ assets Manage Vite Tasks. │\n│ database Manage SQLAlchemy database components. │\n│ info Show information about the detected Litestar app. │\n│ routes Display information about the application's routes. │\n│ run Run a Litestar app. │\n│ schema Manage server-side OpenAPI schemas. │\n│ sessions Manage server-side sessions. │\n│ users Manage application users and roles. │\n│ version Show the currently installed Litestar version. │\n│ workers Manage background task workers. │\n╰──────────────────────────────────────────────────────────────────────────────╯\n\n```\n\n## Database Commands\n\nAlembic integration is built directly into the CLI under the `database` command.\n\nThe following shows the commands available with the `database` CLI command.\n\n```bash\n❯ app database\nUsing Litestar app from env: 'app.asgi:create_app'\n\n Usage: app database [OPTIONS] COMMAND [ARGS]...\n\n Manage SQLAlchemy database components.\n\n╭─ Options ────────────────────────────────────────────────────────────────────╮\n│ --help -h Show this message and exit. │\n╰──────────────────────────────────────────────────────────────────────────────╯\n╭─ Commands ───────────────────────────────────────────────────────────────────╮\n│ downgrade Downgrade database to a specific revision. │\n│ init Initialize migrations for the project. │\n│ make-migrations Create a new migration revision. │\n│ merge-migrations Merge multiple revisions into a single new revision. │\n│ show-current-revision Shows the current revision for the database. │\n│ stamp-migration Mark (Stamp) a specific revision as current without │\n│ applying the migrations. │\n│ upgrade Upgrade database to a specific revision. │\n╰──────────────────────────────────────────────────────────────────────────────╯\n\n```\n\n### Upgrading the Database\n\nTo upgrade the database to the latest revision, you can use the following command:\n\n```bash\n❯ app database upgrade\nUsing Litestar app from env: 'app.asgi:create_app'\nStarting database upgrade process ───────────────────────────────────────────────\nAre you sure you you want migrate the database to the \"head\" revision? [y/n]: y\n2023-10-01T19:44:13.536101Z [debug ] Using selector: EpollSelector\n2023-10-01T19:44:13.623437Z [info ] Context impl PostgresqlImpl.\n2023-10-01T19:44:13.623617Z [info ] Will assume transactional DDL.\n2023-10-01T19:44:13.667920Z [info ] Running upgrade -\u003e c3a9a11cc35d, init\n2023-10-01T19:44:13.774932Z [debug ] new branch insert c3a9a11cc35d\n2023-10-01T19:44:13.783804Z [info ] Pool disposed. Pool size: 5 Connections\n in pool: 0 Current Overflow: -5 Current Checked out connections: 0\n2023-10-01T19:44:13.784013Z [info ] Pool recreating\n```\n\n## Worker Commands\n\nThe following shows the commands available with the `worker` CLI command. This controls the `saq` worker processes. However, when using the `SAQ_USE_SERVER_LIFESPAN=True` environment variable, the background workers are automatically started and stopped with the Litestar HTTP server.\n\n```bash\n❯ app worker\nUsing Litestar app from env: 'app.asgi:create_app'\n\n Usage: app worker [OPTIONS] COMMAND [ARGS]...\n\n Manage application background workers.\n\n╭─ Options ────────────────────────────────────────────────────────────────────╮\n│ --help -h Show this message and exit. │\n╰──────────────────────────────────────────────────────────────────────────────╯\n╭─ Commands ───────────────────────────────────────────────────────────────────╮\n│ run Starts the background workers. │\n╰──────────────────────────────────────────────────────────────────────────────╯\n\n```\n\n## Run Commands\n\nTo run the application through Granian (HTTP1 or HTTP2) using the standard Litestar CLI, you can use the following:\n\n```bash\n❯ app run --help\nUsing Litestar app from env: 'app.asgi:app'\nLoading environment configuration from .env\n\n Usage: app run [OPTIONS]\n\n Run a Litestar app.\n The app can be either passed as a module path in the form of \u003cmodule\n name\u003e.\u003csubmodule\u003e:\u003capp instance or factory\u003e, set as an environment variable\n LITESTAR_APP with the same format or automatically discovered from one of\n these canonical paths: app.py, asgi.py, application.py or app/__init__.py.\n When auto-discovering application factories, functions with the name\n ``create_app`` are considered, or functions that are annotated as returning a\n ``Litestar`` instance.\n\n╭─ Options ────────────────────────────────────────────────────────────────────╮\n│ --port -p INTEGER Serve under this port │\n│ (INTEGER) │\n│ [default: 8000] │\n│ --wc,--web-concurrency… -W INTEGER RANGE The number of processes │\n│ [1\u003c=x\u003c=7] to start. │\n│ (INTEGER RANGE) │\n│ [default: 1; 1\u003c=x\u003c=7] │\n│ --threads INTEGER RANGE [x\u003e=1] The number of threads. │\n│ (INTEGER RANGE) │\n│ [default: 1; x\u003e=1] │\n│ --blocking-threads INTEGER RANGE [x\u003e=1] The number of blocking │\n│ threads. │\n│ (INTEGER RANGE) │\n│ [default: 1; x\u003e=1] │\n│ --threading-mode THREADMODES Threading mode to use. │\n│ (THREADMODES) │\n│ --http HTTPMODES HTTP Version to use │\n│ (HTTP or HTTP2) │\n│ (HTTPMODES) │\n│ --opt Enable additional event │\n│ loop optimizations │\n│ --backlog INTEGER RANGE [x\u003e=128] Maximum number of │\n│ connections to hold in │\n│ backlog. │\n│ (INTEGER RANGE) │\n│ [default: 1024; x\u003e=128] │\n│ --host -H TEXT Server under this host │\n│ (TEXT) │\n│ [default: 127.0.0.1] │\n│ --ssl-keyfile FILE SSL key file (FILE) │\n│ --ssl-certificate FILE SSL certificate file │\n│ (FILE) │\n│ --create-self-signed-c… If certificate and key │\n│ are not found at │\n│ specified locations, │\n│ create a self-signed │\n│ certificate and a key │\n│ --http1-buffer-size INTEGER RANGE Set the maximum buffer │\n│ [x\u003e=8192] size for HTTP/1 │\n│ connections │\n│ (INTEGER RANGE) │\n│ [default: 417792; │\n│ x\u003e=8192] │\n│ --http1-keep-alive/--n… Enables or disables │\n│ HTTP/1 keep-alive │\n│ [default: │\n│ http1-keep-alive] │\n│ --http1-pipeline-flush… Aggregates HTTP/1 │\n│ flushes to better │\n│ support pipelined │\n│ responses │\n│ (experimental) │\n│ --http2-adaptive-windo… Sets whether to use an │\n│ adaptive flow control │\n│ for HTTP2 │\n│ --http2-initial-connec… INTEGER Sets the max │\n│ connection-level flow │\n│ control for HTTP2 │\n│ (INTEGER) │\n│ --http2-initial-stream… INTEGER Sets the │\n│ `SETTINGS_INITIAL_WIND… │\n│ option for HTTP2 │\n│ stream-level flow │\n│ control │\n│ (INTEGER) │\n│ --http2-keep-alive-int… OPTIONAL Sets an interval for │\n│ HTTP2 Ping frames │\n│ should be sent to keep │\n│ a connection alive │\n│ (OPTIONAL) │\n│ --http2-keep-alive-tim… INTEGER Sets a timeout for │\n│ receiving an │\n│ acknowledgement of the │\n│ HTTP2 keep-alive ping │\n│ (INTEGER) │\n│ --http2-max-concurrent… INTEGER Sets the │\n│ SETTINGS_MAX_CONCURREN… │\n│ option for HTTP2 │\n│ connections │\n│ (INTEGER) │\n│ --http2-max-frame-size INTEGER Sets the maximum frame │\n│ size to use for HTTP2 │\n│ (INTEGER) │\n│ --http2-max-headers-si… INTEGER Sets the max size of │\n│ received header frames │\n│ (INTEGER) │\n│ --http2-max-send-buffe… INTEGER Set the maximum write │\n│ buffer size for each │\n│ HTTP/2 stream │\n│ (INTEGER) │\n│ --url-path-prefix TEXT URL path prefix the app │\n│ is mounted on │\n│ (TEXT) │\n│ --debug -d Run app in debug mode │\n│ --pdb,--use-pdb -P Drop into PDB on an │\n│ exception │\n│ --respawn-failed-worke… Enable workers respawn │\n│ on unexpected exit │\n│ --reload -r Reload server on │\n│ changes │\n│ --help -h Show this message and │\n│ exit. │\n╰──────────────────────────────────────────────────────────────────────────────╯\n\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flitestar-org%2Flitestar-fullstack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flitestar-org%2Flitestar-fullstack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flitestar-org%2Flitestar-fullstack/lists"}