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 for data access (advanced-alchemy vs sqlspec), DI (Provide vs Dishka), settings (dataclass vs pydantic-settings), background jobs (litestar-saq vs litestar-queues), and Channels backend (Memory, Redis, AsyncPg/PsycoPg, SQLSpec).
• Keep Litestar(...) app setup and route handlers thin: group domain routes into Controller / Router hierarchies (urls.py + controllers/ + services.py + schemas.py + dependencies.py + guards.py), and centralize multi-domain wiring in ApplicationCore(InitPluginProtocol, CLIPluginProtocol) + create_app() -> Litestar (litestar-fullstack / litestar-sqlstack pattern).
• Use Litestar 2.22–2.25 explicit annotations: FromPath[T], FromQuery[T], FromHeader[T], FromCookie[T] (or PathParameter, QueryParameter, HeaderParameter, CookieParameter when constraints or wire names are needed), JSONBody[T], RequestBody[T], MsgPackBody[T], MultipartBody[T], URLEncodedBody[T], RawBody, QueryParams, RequestCookies, NamedDependency[T], and SkipValidation[T]. Never introduce implicit dependencies, untyped reserved kwargs (data: MyDTO without a body marker or body: bytes), or deprecated litestar.params.Dependency.
• Define explicit msgspec.Struct (camelCase wire format via rename="camel") or MsgspecDTO / SQLAlchemyDTO / DataclassDTO boundary contracts (dto and return_dto) on routes and controllers; never expose raw ORM models directly without a write-safe DTO.
• Enforce authentication via AbstractAuthenticationMiddleware or first-party JWTAuth / JWTCookieAuth / SessionAuth, and enforce authorization in Guard functions (connection: ASGIConnection, route_handler: BaseRouteHandler) -> None | Awaitable[None] or litestar-security decorators — never inside route handler bodies.
• Prefer built-in middleware configs (CORSConfig, CSRFConfig, AllowedHostsConfig, CompressionConfig, RateLimitConfig, ResponseCacheConfig, LoggingMiddlewareConfig) over custom middleware, and subclass ASGIMiddleware (litestar.middleware.ASGIMiddleware) with scopes and exclude filters for custom cross-cutting concerns.
• Raise domain-specific ApplicationError subclasses in services and map them to HTTP responses (or RFC 9457 Problem Details) in exception_handlers; import OpenTelemetry, Prometheus, Structlog, and template plugins from litestar.plugins.* (never deprecated litestar.contrib.*).
• Use async I/O for all request handlers, WebSocket/SSE streams, service/repository methods, stores, and external clients.