litestar-org/litestar-skills/litestar

Litestar Core Framework & Ecosystem Hub

Use this skill for all core Litestar framework subsystems (application composition, routing, controllers, parameters, DTOs, OpenAPI, dependency injection, Dishka integration, authentication/guards, middleware, exception handling, plugin protocols, WebSockets, Channels/SSE, typed settings, and CRUD data services/pagination) and to route to standalone Litestar ecosystem skills.

This guidance targets the released Litestar 2.25.0 contract. Do not copy unreleased main APIs into consumer examples.

Code Style Rules

• Prefer first-party Litestar ecosystem packages (litestar-granian, advanced-alchemy, sqlspec, msgspec, litestar-saq, litestar-queues, litestar-vite, litestar-autowire, litestar-security, litestar-email, litestar-mcp, litestar-htmx) and match the project's existing stack.
• Keep Litestar(...) app setup and route handlers thin: group domain routes into Controller / Router hierarchies, and centralize application wiring in create_app() -> Litestar.
• Use explicit parameter and body annotations (FromPath, FromQuery, JSONBody, NamedDependency). Avoid untyped reserved kwargs (such as data: MyDTO without a body marker) and deprecated litestar.params.Dependency.
• Define explicit msgspec.Struct (camelCase wire format via rename="camel") or DTO boundary contracts (dto and return_dto) on routes and controllers; never expose raw ORM models directly without a write-safe DTO.
• Enforce authentication via middleware or litestar-security, and enforce authorization in Guard functions or security decorators — never inside route handler bodies.
• Prefer built-in middleware configs (CORSConfig, CSRFConfig, AllowedHostsConfig, RateLimitConfig, CompressionConfig) over custom middleware.
• Raise domain-specific exceptions in services and map them to HTTP responses in exception_handlers.
• Use async I/O for all request handlers, WebSocket/SSE streams, service methods, stores, and external clients.

Quick Reference

Core Framework Subsystems (This Skill)

Standalone Ecosystem Skills

<workflow>

Workflow

1. Detect the project stack first: inspect pyproject.toml, litestar.toml, existing domain packages, DI setup (Provide vs Dishka), data layer (advanced-alchemy vs sqlspec), settings (dataclass vs pydantic-settings), and auth (JWTAuth/SessionAuth vs litestar-security).
2. Open the matching core reference in references/*.md for any Litestar framework concern:

• Routing, controllers, parameters, or domain layout -> handlers.md, parameters.md, layout.md
• DTOs, request/response schemas, or OpenAPI docs -> dtos.md, openapi.md
• Dependency injection or Dishka providers -> di-and-dishka.md
• Auth backends, guards, middleware, or exception handlers -> auth-and-guards.md, middleware.md, exceptions.md
• Plugins, WebSockets, Channels/SSE, settings, or CRUD services/filters -> plugins.md, websockets.md, channels-and-sse.md, settings.md, filters-and-pagination.md, services-and-repos.md
• App composition, CLI, logging/metrics/tracing, or stores/caching -> app-and-lifecycle.md, cli-and-config.md, logging-and-observability.md, stores-and-caching.md

1. Open standalone ecosystem skills when working on dedicated first-party packages (advanced-alchemy, sqlspec, msgspec, litestar-vite, litestar-htmx, litestar-saq, litestar-queues, litestar-security, litestar-autowire, litestar-email, litestar-mcp, litestar-granian, litestar-testing, polyfactory, pytest-databases, litestar-build, litestar-deployment).
2. Keep the stack consistent across the feature: never mix two persistence layers, two DI containers, or two settings paradigms unless the repository already bridges them intentionally.

</workflow>

<guardrails>

Guardrails

• Do not infer a new stack from examples — always match the current project's data layer, DI pattern, settings style, and auth mechanism first.
• Do not put authentication, authorization, SQL queries, environment parsing, or heavy background work directly inside route handlers; delegate to Guard callables, services/repositories, cached settings factories, and task queues.
• Do not use deprecated StaticFilesConfig, litestar.contrib.* plugins, litestar.repository, litestar.params.Dependency, or implicit dependency parameters.
• Do not expose ORM models directly in dto / return_dto without exclude / include field rules that prevent mass assignment and hidden relationship lazy-loads.
• Do not call os.getenv() inside request handlers or module-level code outside the settings module, and never hardcode secrets in source files.
• Do not call start_subscription(..., history=N) on Channels backends that do not implement history (RedisChannelsPubSubBackend, AsyncPgChannelsBackend, PsycoPgChannelsBackend).

</guardrails>

<validation>

Validation Checkpoint