litestar-skills

Configure Litestar plugin architecture and ecosystem integrations, including custom Init/DI/serialization/route plugins, SQLAlchemy plugin stacks, Pydantic plugin surfaces, Piccolo DTO usage, and model-bound transport support for dataclasses, msgspec, attrs, and TypedDict. Use when selecting, wiring, or debugging plugin-driven behavior at application boundaries. Do not use for unrelated framework setup that does not involve Litestar plugin protocols, plugin registration, or plugin-backed transport/model integration.

Configure Litestar stores and the store registry for caching, server-side sessions, rate limiting, and other key-value state with explicit backend selection, bytes-safe data handling, TTL and renewal policy, namespacing, registry wiring, and lifecycle cleanup. Use when a Litestar app depends on `MemoryStore`, `FileStore`, `RedisStore`, `ValkeyStore`, or `StoreRegistry`. Do not use for relational persistence, domain repositories, or response-caching policy details that belong in database or caching-focused skills.

Apply Litestar request lifecycle hooks with `before_request`, `after_request`, and `after_response` for request enrichment, short-circuiting, response mutation, post-send side effects, and layered cross-cutting behavior around handler execution. Use when logic should run immediately before the handler, after the response object is resolved, or after the response has been sent. Do not use for startup/shutdown ownership, `before_send` / `after_exception` / `on_app_init`, decoupled event fanout, or raw ASGI wrapping that belongs in app setup, events, or middleware.

Configure Litestar response caching with route-level `cache` controls, app-level `ResponseCacheConfig`, store selection, TTL strategy, cache key design, and `cache_response_filter` rules. Use when optimizing read-heavy or polling-heavy Litestar endpoints without breaking correctness for tenant-, locale-, or auth-scoped responses. Do not use for write-heavy or immediately consistent workflows unless cache invalidation or versioning is designed explicitly.

Build HTMX-driven Litestar flows with `HTMXPlugin`, `HTMXRequest`, `request.htmx`, `HTMXTemplate`, and HTMX response classes such as `HXLocation`, `PushUrl`, `ReplaceUrl`, `Reswap`, `Retarget`, `TriggerEvent`, `ClientRedirect`, `ClientRefresh`, and `HXStopPolling`. Use when implementing server-rendered partial updates, progressive enhancement, polling, redirects, or history-aware HTML interactions. Do not use for SPA-only JSON APIs that do not exchange HTML or HTMX headers.

Serve static assets in Litestar with `create_static_files_router()`, explicit mount paths, HTML mode, cache-control policy, URL reversal, custom file systems, and symlink-safe directory boundaries. Use when exposing JS, CSS, images, downloadable artifacts, or static HTML from controlled directories. Do not use for upload ingestion, user-writable file publication, or arbitrary file-download endpoints that need per-request authorization logic.

Design cache-aware Advanced Alchemy usage, including deterministic read paths, SQLAlchemy statement-cache-safe custom type configuration, and framework-level response caching around repository and service queries. Use when repeated read workloads need performance tuning without corrupting data semantics, or when custom types or filters interfere with cacheability. Do not use as a substitute for correctness in repository or service design.

Use Advanced Alchemy's CLI for migrations, revision management, inspection, branching, fixture dumping, and framework CLI integration. Use when setting up or operating Alembic migrations through `alchemy`, `litestar database`, or `flask database`, or when embedding the commands into Click or Typer applications. Do not use for runtime repository or service logic.

Seed databases and load fixtures with Advanced Alchemy using JSON fixture files, sync or async helpers, repository bulk operations, and framework startup hooks. Use when creating development or test seed data, loading initial reference data, or dumping and restoring fixture-backed tables. Do not use for schema migrations or general runtime CRUD handling.

Integrate Advanced Alchemy with FastAPI using the extension, request-scoped session dependencies, repository and service providers, typed response models, and router composition. Use when building FastAPI CRUD APIs backed by Advanced Alchemy or replacing handwritten SQLAlchemy session handling with its extension patterns. Do not use for non-FastAPI framework integrations.

Integrate Advanced Alchemy with Flask using sync or async configs, Flask session access helpers, multiple binds, FlaskServiceMixin, JSON serialization helpers, and Flask CLI database commands. Use when adding Advanced Alchemy persistence to Flask applications or refactoring Flask SQLAlchemy code toward repository and service patterns. Do not use for framework-agnostic repository or model work.

Set up Advanced Alchemy in a new or existing Python service, including package installation, sync or async SQLAlchemy config selection, first model and repository wiring, and framework selection for Litestar, FastAPI, Flask, or standalone SQLAlchemy. Use when bootstrapping Advanced Alchemy, validating prerequisites, or choosing the initial integration shape. Do not use for detailed framework-specific implementation that belongs in the dedicated integration skills.

Integrate Advanced Alchemy with Litestar using the SQLAlchemy plugin, session injection, service and repository providers, DTO-friendly models, CLI database commands, and optional session backends. Use when building or refactoring Litestar applications that persist data through Advanced Alchemy. Do not use for generic Litestar work that does not depend on Advanced Alchemy.

Design Advanced Alchemy SQLAlchemy models using its base classes, mixins, unique-record helpers, relationship patterns, and declarative base customization. Use when building or refactoring database models, choosing UUID or bigint key strategies, adding slugs or audit columns, or simplifying deduplicated many-to-many workflows. Do not use for repository or HTTP endpoint logic.

Build Advanced Alchemy repository layers with sync or async repositories, slug-aware repositories, query repositories, bulk operations, filtering, and pagination. Use when implementing database access patterns, replacing handwritten CRUD, or standardizing query logic around SQLAlchemy models. Do not use for business-rule orchestration that belongs in services or for framework routing concerns.

Implement Advanced Alchemy-backed CRUD routing patterns with separate read and write contracts, pagination filters, repository-only versus service-backed handlers, and predictable endpoint composition. Use when exposing Advanced Alchemy models over HTTP in Litestar, FastAPI, or Flask, especially for list/detail/create/update/delete flows. Do not use for low-level database setup or model design.

Implement Advanced Alchemy service layers for business logic, schema validation, data transformation, and coordinated repository operations using Pydantic, Msgspec, attrs, or plain dictionaries. Use when handlers need more than raw CRUD, when repository results must be converted to schemas, or when complex create and update flows span multiple models. Do not use for low-level model or repository definition alone.

Apply Advanced Alchemy custom SQLAlchemy types such as `DateTimeUTC`, encrypted fields, `GUID`, `JsonB`, password hashing, and stored file objects with backend-aware behavior and migration compatibility. Use when modeling non-trivial persistence concerns, securing sensitive columns, or choosing database-portable data types. Do not use for general model design that does not require custom column behavior.

Configure Litestar templating with `TemplateConfig`, Jinja/Mako/MiniJinja engines, file-or-string `Template` responses, request and CSRF-aware context, template callables, and custom engine integration. Use when implementing or fixing server-rendered HTML in Litestar. Do not use for static asset serving or pure JSON API endpoints.

Implement Litestar authentication with custom authentication middleware, built-in security backends, JWT and session flows, route inclusion and exclusion rules, and typed auth context on `Request` / `ASGIConnection`. Use when establishing identity, issuing or validating credentials, or attaching authenticated user context in Litestar. Do not use for generic request parsing, broad security audits, or unrelated transport concerns.

Build and configure Litestar application entrypoints, app-level configuration, startup/shutdown lifecycle, lifespan context managers, application state, hooks, and layered parameter precedence. Use when creating a new Litestar service, restructuring app initialization, or setting app-level defaults. Do not use for isolated handler logic that belongs in routing, requests, responses, DTO-focused skills, or the in-process event bus handled by `litestar-events`.

Debug Litestar services with reproducible failure isolation, safe debug-mode usage, request and app logger inspection, middleware and dependency boundary analysis, and targeted regression checks. Use when investigating runtime errors, unexpected middleware behavior, lifecycle issues, request parsing failures, auth bugs, or route contract mismatches in Litestar. Do not use as a substitute for implementing missing tests, logging, metrics, or tracing instrumentation.

Implement Litestar exception handling with HTTPException, built-in exception subclasses, custom exception handlers, layered overrides, status-code mappings, and stable API error contracts. Use when translating domain failures, validation errors, middleware/dependency failures, or router-generated HTTP errors into deterministic Litestar responses. Do not use for authentication or authorization policy design that belongs in security layers.

Handle Litestar multipart file uploads securely with `UploadFile`, typed multipart models, multi-file inputs, request body limits, and storage-safe processing patterns. Use when accepting single or multiple uploaded files in request bodies, especially multipart form-data endpoints. Do not use for generic request parsing, static asset serving, or download response behavior.

Configure Litestar logging with `LoggingConfig`, `queue_listener`, exception logging policy, selective stack-trace suppression, standard logging, picologging, Structlog, and custom logging config subclasses. Use when establishing or refactoring application logging behavior, request-level logs, or production-safe error logging in Litestar. Do not use for metrics/tracing instrumentation or exception-response contract design.

Add Litestar metrics with OpenTelemetry and Prometheus instrumentation, plugin or middleware wiring, exporter configuration, path grouping, labels, exemplars, and endpoint exclusion strategy. Use when implementing service-level monitoring, scrape endpoints, request metrics, or custom observability dimensions in Litestar. Do not use for log formatting, tracing-only concerns, or exception contract design.

Design and apply Litestar middleware for cross-cutting concerns such as CORS, CSRF, allowed-host checks, compression, rate limiting, logging, sessions, request enrichment, policy enforcement, and custom ASGI pipeline control. Use when behavior must wrap broad route sets consistently across the ASGI stack. Do not use for route-specific business rules, simple response mutation better handled by lifecycle hooks, or auth/guard policy work that belongs in security-focused skills.

Configure Litestar OpenAPI schema generation and documentation UX with `OpenAPIConfig`, route-level schema metadata, schema generation controls, operation customization, UI render plugins, and documentation endpoint strategy. Use when API contract and docs quality must be implemented or corrected, especially for request, auth, and metrics surfaces. Do not use for runtime business logic changes unrelated to schema or documentation.

Handle Litestar request parsing and access for path, query, header, cookie, JSON body, form, multipart, and raw request inputs with explicit typing, `Parameter`, `Body`, `Request`, and upload handling. Use when implementing or fixing inbound HTTP contracts, request metadata access, or transport-side validation in Litestar. Do not use for response serialization, exception mapping, or broker-style messaging concerns.

Build Litestar responses with typed return values, explicit Response containers, layered response classes, headers, cookies, status-code control, redirects, files, streams, server-sent events, ASGI app returns, and background tasks. Use when shaping outbound HTTP behavior, correcting response contracts, or choosing the right Litestar response primitive. Do not use for request parsing, validation, or authentication policy design.

Build secure Litestar APIs using authentication middleware, built-in security backends, guards, endpoint inclusion and exclusion controls, JWT validation, request-boundary discipline, and secret-safe data handling. Use when implementing or auditing end-to-end API security controls in Litestar. Do not use for generic request parsing, unrelated business logic, or non-security transport concerns.

Test Litestar applications with TestClient, AsyncTestClient, create_test_client, websocket test helpers, dependency overrides, mocked dependencies, lifecycle-aware fixtures, and deterministic success and failure assertions. Use when adding or fixing Litestar test coverage, including exception contracts, override precedence, websocket behavior, event-bus side effects, or live-server-only response patterns. Do not use as a substitute for production observability or runtime debugging strategy.

Use Python dataclasses as Litestar transport models with explicit typing, defaults, and DTO interplay. Use when modeling request/response contracts with lightweight typed objects. Do not use when plugin-backed model systems (Pydantic/msgspec/attrs/ORM) are a better fit for the task.

Use Litestar's event emitter and listener system with `@listener`, `request.app.emit()`, multiple listeners per event, multi-event listeners, shared argument contracts, and custom event emitter backends. Use when decoupling async side effects, fanout-style in-process notifications, or transport-triggered domain events inside a Litestar app. Do not use for startup/shutdown lifecycle hooks, request/response interception, or broker-backed pub-sub systems that belong in app setup, lifecycle hooks, or channels.

Implement Litestar channels with ChannelsPlugin, backend selection, subscriber lifecycle, publish and subscribe flows, history management, backpressure strategy, and websocket integration. Use when building broker-backed event streams, server-side fanout, or reusable publish-subscribe flows in Litestar. Do not use for simple request-response APIs or one-off websocket loops without channel semantics.

Build Litestar WebSocket endpoints with low-level websocket handlers, websocket listeners, websocket streams, dependency injection, custom websocket classes, transport-mode control, and graceful connection lifecycle handling. Use when implementing bidirectional real-time communication, reactive websocket message handling, or proactive server push over WebSockets. Do not use for server-side pub/sub fanout that is better expressed with channels alone.

Apply Litestar dependency injection with Provide, Dependency markers, layered scopes, overrides, generator-based cleanup, per-request caching, and nested providers. Use when wiring services, settings, database sessions, request-derived resources, or test doubles into Litestar handlers, controllers, routers, and apps. Do not use when plain local function parameters or a small helper are sufficient.

Design and implement Litestar routing with app/router/controller composition, handler decorators, path and parameter modeling, route indexing/reverse lookups, ASGI mounting, and layered route metadata. Use when creating or refactoring endpoint topology and URL contracts. Do not use for purely internal service logic unrelated to HTTP route structure.

Configure Litestar DTO behavior for inbound parsing and outbound serialization, including layer-scoped `dto`/`return_dto`, `DTOConfig` policies, `DTOData` update workflows, and custom `AbstractDTO` implementations. Use when API payload contracts differ from internal model structures. Do not use when internal models can be exposed safely without transformation.

Build Litestar database architecture with SQLAlchemy and Piccolo ORM, including model/repository patterns, SQLAlchemy plugin selection, session lifecycle, transaction boundaries, and DTO/serialization controls. Use when implementing persistence layers, transaction handling, or ORM integration. Do not use for non-persistent in-memory workflows.