/litestar

name: litestar
description: "Use when working with Litestar, Controller, Router, @get/@post, FromPath, MsgspecDTO, OpenAPIConfig, Provide, FromDishka, Guard, ASGIMiddleware, HTTPException, ChannelsPlugin, or WebSocket. Not for standalone libs."

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)

| Subsystem | Key Symbols / Patterns | Reference | | --- | --- | --- | | App Composition & Lifecycle | `Litestar(...)`, `AppConfig`, `ApplicationCore`, `lifespan`, `State`, `ImmutableState`, 2.22–2.25 contracts | [app-and-lifecycle.md](references/app-and-lifecycle.md) | | CLI & Project Config | Autodiscovery, `LITESTAR_*` env vars, `litestar run`/`info`/`routes`/`schema`/`sessions`, `CLIPlugin`, `litestar.toml` | [cli-and-config.md](references/cli-and-config.md) | | Route Handlers & Controllers | `@get`/`@post`/`@put`/`@patch`/`@delete`, `Controller`, `Router`, layered config inheritance | [handlers.md](references/handlers.md) | | Parameters & Request Bodies | `FromPath`, `FromQuery`, `FromHeader`, `FromCookie`, `JSONBody`, `RequestBody`, `MsgPackBody`, `MultipartBody`, `URLEncodedBody`, `RawBody`, `QueryParams`, `RequestCookies`, `UploadFile` | [parameters.md](references/parameters.md) | | Domain Package Layout | `domains/<name>/` structure, sub-controllers, full-stack domain wiring | [layout.md](references/layout.md) | | DTOs & Boundary Contracts | `MsgspecDTO`, `SQLAlchemyDTO`, `DataclassDTO`, `PydanticDTO`, `DTOConfig`, `DTOData[T]`, `DTOField`, `Mark` | [dtos.md](references/dtos.md) | | OpenAPI & Schema UI | `OpenAPIConfig`, Scalar/Swagger/Redoc/Stoplight/RapiDoc plugins, `ResponseSpec`, `Operation`, security schemes | [openapi.md](references/openapi.md) | | Dependency Injection & Dishka | `Provide`, `NamedDependency[T]`, `SkipValidation[T]`, generator cleanup, `FromDishka[T]`, `setup_dishka` | [di-and-dishka.md](references/di-and-dishka.md) | | Authentication & Guards | `Guard` callables, `ASGIConnection`, `JWTAuth`, `JWTCookieAuth`, `SessionAuth`, OAuth2, RBAC & tenant guards | [auth-and-guards.md](references/auth-and-guards.md) | | Middleware & HTTP Security | `ASGIMiddleware`, `DefineMiddleware`, `CORSConfig`, `CSRFConfig`, `AllowedHostsConfig`, `CompressionConfig`, `RateLimitConfig` | [middleware.md](references/middleware.md) | | Exceptions & Problem Details | `HTTPException` hierarchy, `ApplicationError` mapping, `exception_handlers`, `after_exception`, RFC 9457 | [exceptions.md](references/exceptions.md) | | Plugin Protocols | `InitPlugin`, `CLIPluginProtocol`, `SerializationPluginProtocol`, `OpenAPISchemaPluginProtocol`, `DIPlugin`, `PydanticPlugin` | [plugins.md](references/plugins.md) | | WebSockets | `@websocket`, `WebSocket` lifecycle, `@websocket_listener`, `@websocket_stream`, WS Dishka DI, WS guards, `stream_pubsub` | [websockets.md](references/websockets.md) | | Channels & Server-Sent Events | `ChannelsPlugin` (`Memory`, `Redis`, `AsyncPg`, `PsycoPg`, `SQLSpec`), `ServerSentEvent`, `Stream`, `RealtimeEvent`, `RealtimePublisher` | [channels-and-sse.md](references/channels-and-sse.md) | | Typed Settings & Env Config | `dataclass` + `get_env` vs `pydantic-settings`, `@lru_cache` factories, plugin config builders | [settings.md](references/settings.md) | | Filters & Pagination | `create_filter_dependencies`, `FilterTypes`, `OffsetPagination`, `ClassicPagination`, cursor pagination, custom search | [filters-and-pagination.md](references/filters-and-pagination.md) | | Data Services & Repositories | `SQLAlchemyAsyncRepositoryService` (`advanced-alchemy`) and `SQLSpecAsyncService` (`sqlspec`) CRUD services | [services-and-repos.md](references/services-and-repos.md) | | Logging & Observability | `LoggingConfig`, `StructlogPlugin`, `OpenTelemetryPlugin`, `PrometheusConfig`, `PrometheusController` | [logging-and-observability.md](references/logging-and-observability.md) | | Stores & Response Caching | `StoreRegistry`, `MemoryStore`, `FileStore`, `RedisStore`, `ValkeySto