litestar-skills

Reviews Litestar code against first-party conventions, adapting to the project's stack: msgspec or Pydantic DTOs, Guards, Provide or Dishka DI, advanced-alchemy or sqlspec services, first-party paginated responses, custom exception hierarchies, dataclass or pydantic-settings Settings, async-all-I/O, domain-clustered Controllers, Granian-first, SAQ or custom PG-native background workers, camelCase wire format. Use when reviewing PRs, code quality checks, or pre-merge validation in Litestar projects.

Auto-activate for alembic/, alembic.ini, advanced_alchemy imports. Expert knowledge for Advanced Alchemy / SQLAlchemy ORM patterns. Produces ORM models with audit trails, repository/service patterns, and Alembic migrations. Use when: defining models with UUIDAuditBase, building repositories and services, configuring SQLAlchemy plugins for Litestar/FastAPI/Flask/Sanic, creating DTOs, running Alembic migrations, using custom types (EncryptedString, FileObject, PasswordHash, DateTimeUTC), composing filters and pagination, choosing base classes and mixins, configuring dogpile.cache query caching, setting up read/write replica routing, or managing file storage with obstore/fsspec backends. Not for raw SQLAlchemy without Advanced Alchemy abstractions.

Auto-activate for `uv build`, `hatch build`, pyapp invocations, bundler scripts, Hatchling force-include config, wheel packaging with bundled frontend assets, PyApp onefile binaries, GitHub Actions matrix workflows, `PYAPP_*` env vars, cargo-zigbuild, python-build-standalone. Produces Hatchling build configs that bundle Vite/Bun output into the wheel, Makefile build graphs (`build-assets` → `build-wheel` → `build-onefile`), PyApp hatch-binary targets, advanced PyApp pipelines with custom bundler and install-dir patching, GitHub Actions CI/release workflows with Python matrix + uv + Bun. Use when: building a Litestar wheel with embedded frontend assets, packaging an app as a single-file PyApp binary (standard or offline), customizing PyApp install location, setting up `uv` + `bun` CI, writing release pipelines that produce wheels + onefiles + container images. Not for runtime deployment — see litestar-deployment. Not for Vite plugin authoring — see litestar-vite.

Auto-activate for Dockerfile, docker-compose.yml, railway.json, railway.toml, Procfile, cloudbuild.yaml, app.yaml, service.yaml, `.github/workflows/deploy*`, deploy.sh, systemd unit files, or `granian` / `litestar run` in deployment context. Litestar deployment across targets: Docker multi-stage builds (standard + distroless), Docker Compose, Railway, Cloud Run, GKE, systemd. Produces Dockerfiles, compose files, K8s manifests, Railway configs, Cloud Run service.yaml, systemd units, CI/CD workflows, health-check endpoints. Key patterns: uv for packages, Bun for frontend builds, tini as PID 1, non-root UID 65532, UV_COMPILE_BYTECODE=1, STOPSIGNAL SIGINT, distroless prod images, separate SAQ worker containers, Vite asset pipeline in Docker, LITESTAR_APP env var. Use when: deploying a Litestar app, writing Dockerfiles, Docker Compose, Railway/Cloud Run/GKE, systemd, or CI/CD pipelines with asset builds. Not for non-Litestar Python apps — Litestar has specific Granian/entrypoint/lifespan conventions.

Auto-activate for litestar_email imports, EmailPlugin, EmailConfig, EmailService, EmailMessage, SMTPConfig, ResendConfig, SendGridConfig, MailgunConfig, InMemoryConfig. The first-party Litestar plugin for sending email with pluggable backends and DI of EmailService. Produces EmailPlugin configs, backend selection (SMTP/Resend/SendGrid/Mailgun/InMemory), EmailMessage construction, multipart (text+HTML) handling, and DI patterns. Use when: sending transactional or notification email from a Litestar app, choosing an email backend, testing email flows with InMemoryConfig, or wiring the EmailService into handlers. Not for non-Litestar email (use the underlying SDK directly) or for marketing/bulk email campaigns at scale (use a dedicated marketing platform).

Auto-activate for litestar_granian imports, GranianPlugin, granian CLI commands, ASGI server config in a Litestar app. The litestar-granian plugin: zero-config replacement for `litestar run` that uses Granian (Rust-based ASGI server) instead of uvicorn. Produces GranianPlugin configurations, GranianConfig tuning (workers/threads/HTTP/SSL/backpressure), and Litestar app lifespan integration. Use when: serving a Litestar app in dev or production, replacing uvicorn, configuring workers/threads, enabling HTTP/2 or SSL, or tuning backpressure. Not for FastAPI, Django, or non-Litestar apps — use plain `granian` CLI for those. Not for uvicorn — Granian is preferred for all Litestar deployments.

Auto-activate for litestar.contrib.htmx imports, HTMXRequest, HTMXResponse, hx-* attributes in templates served by Litestar. Litestar's first-party HTMX integration: HTMXRequest helpers, HTMXResponse, TriggerEvent, Refresh, PushUrl, HXLocation, partial-HTML responses, OOB swaps, and pairing with litestar-vite for HTMX mode. Produces Litestar Controllers/handlers that return partial HTML, HTMX response helpers (TriggerEvent / Reswap / Retarget), and template patterns for hx-* driven UIs. Use when: building HTMX-powered Litestar apps, returning partial HTML, triggering client events from server, integrating htmx with litestar-vite. Not for full SPAs (React/Vue/Svelte — see litestar-vite SPA mode), not for non-Litestar HTMX apps.

Auto-activate for `@inertiajs/react`, `@inertiajs/vue3`, `@inertiajs/svelte`, `createInertiaApp`, `useForm`, `usePage`, `Link`, `router` from inertiajs, `InertiaPlugin`/`InertiaConfig` from `litestar_vite.inertia`, `@inertia` decorator, `resources/js/pages/` layout. Four-library integration: `litestar` (routes + Guards + DI) + `litestar-vite` (Inertia plugin, asset pipeline, TypeGen) + `vite` (build + HMR) + `inertia` (client adapter, forms, navigation). Produces Inertia page components, `@inertia`-decorated handlers, `InertiaPlugin` wiring, `shared_props` for auth/CSRF/flash, `useForm` with Litestar validation errors, partial reloads, lazy props, `back()` redirects, SSR. Use when: building a Python-backed SPA, converting a Litestar HTML app into an SPA, wiring React/Vue/Svelte with server-driven routing, mapping Litestar validation to form errors, or setting up Inertia SSR. Not for JSON-API-only SPAs, HTMX apps, or non-Litestar backends.

Auto-activate for litestar_mcp imports, LitestarMCP, MCPConfig, @mcp_tool, @mcp_resource, MCPController. The first-party Litestar plugin exposing route handlers as Model Context Protocol (MCP) tools and resources over JSON-RPC 2.0. Produces LitestarMCP plugin configs, @mcp_tool / @mcp_resource decorators, route filtering (include/exclude tags/operations), OpenAPI-aligned schemas, and OAuth 2.1 / Guard-based auth setups. Use when: exposing a Litestar API to LLM agents, wiring an MCP server, controlling which routes are visible to AI, or aligning MCP tool schemas with OpenAPI. Not for non-Litestar MCP servers (use the upstream Python MCP SDK) or for FastAPI/Django.

Auto-activate for litestar_saq imports, SAQPlugin, SAQConfig, QueueConfig, TaskQueues. The first-party Litestar plugin around SAQ (Simple Async Queue): background tasks, cron jobs, queue web UI, `litestar workers run` CLI, DI of `TaskQueues`. Produces SAQPlugin configs, QueueConfig definitions, task functions, CronJobs, and DI-injected enqueue patterns. Use when: adding background jobs to a Litestar app, scheduling cron work, exposing the SAQ web UI, or running workers via the Litestar CLI. Not for Celery, RQ, or Dramatiq — Litestar's first-party choice is SAQ. For raw SAQ patterns outside Litestar, see standalone SAQ docs. Or document the custom-PG-native alternative pattern when SAQ is explicitly rejected.

Shared code-style baseline for every skill in this plugin. Use when authoring or reviewing code in a Litestar / Python / TypeScript project — PEP 604 unions, async I/O, Google docstrings, msgspec over Pydantic, ruff / mypy / pyright tooling, pytest conventions, CI/CD rules. Produces: links to language-specific style references consumed by sibling skills via their `Shared Styleguide Baseline` sections. Use when: writing a new skill, reviewing code in this repo or a consumer project, or resolving a style disagreement. Not for framework-specific guidance (see the individual skills: litestar, sqlspec, advanced-alchemy, msgspec, etc.) — this skill is the cross-cutting baseline, not a framework guide.

Auto-activate for test_*.py, conftest.py in a Litestar project, litestar.testing imports (TestClient, AsyncTestClient, create_test_client). Litestar-specific testing: TestClient vs AsyncTestClient, @pytest.mark.anyio, app + lifespan, fixtures from canonical Litestar apps, mocking Guards / DI dependencies, integration with pytest-databases, and request-body / header / cookie / response assertions. Produces pytest fixtures, async tests, Guard mocks, DI overrides, AsyncTestClient setups, and pytest-databases-backed integration tests for Litestar apps. Use when: writing tests for a Litestar app, mocking auth/Guards, integration-testing handlers + DB, exercising HTMX or Inertia handlers. Not for generic non-Litestar pytest patterns (use the upstream pytest docs) or for Vitest/JS tests (one-liner pointer below).

Auto-activate for litestar_vite imports, VitePlugin, ViteConfig, PathConfig, RuntimeConfig, TypeGenConfig, vite.config.ts, astro.config.mjs with `litestar-vite-plugin/astro`, `litestar assets` CLI. First-party plugin coordinating a Vite frontend with a Litestar backend across **SPA / template / HTMX / Inertia / framework** modes. Produces ViteConfig + vite.config.ts wiring, manifest resolution, TypeGen (routes.ts, schemas.ts, openapi.json, inertia-pages.json), Jinja helpers (`vite()`, `vite_hmr()`, `vite_react_refresh()`), HMR, production build. Supported frameworks: **React** (+ TanStack Router), **Vue 3**, **Svelte**, **Angular** (`@analogjs/vite-plugin-angular`), **HTMX+Jinja** (with `ls-for`/`ls-if`/`$data` client templating), **Inertia.js** (React/Vue ±Jinja), **Nuxt, SvelteKit, Astro**. Use when: wiring any frontend with Litestar, choosing a mode, scaffolding from an example, setting up HMR, or generating types. Not for Webpack, Rollup, esbuild, Parcel, or plain Vite outside Litestar.

Auto-activate for litestar, litestar_granian, litestar_saq, litestar_vite, litestar_mcp, litestar_email, litestar_asyncpg, litestar_oracledb, sqlspec, advanced_alchemy, msgspec, dishka imports; litestar.toml; pyproject.toml with a litestar dep; `from litestar import` in any .py file. Litestar ASGI framework and first-party ecosystem — Controllers, Guards, middleware, msgspec DTOs, OpenAPI, DI (Provide / Dishka), and plugins for Granian, SAQ, Vite, MCP, Email, AsyncPG, OracleDB. Produces opinionated Litestar routes, DTOs, Guards, Controllers, plugin configs, auth flows, CRUD endpoints. Use when: exposing a SQLAlchemy model as a Controller or MCP tool, integrating a Vite frontend (React / Vue / Svelte / HTMX / Inertia), serving AI models with streaming and SAQ workers, implementing JWT refresh-token auth, scaffolding a Litestar app, or adding Guards / middleware / DI. Not for FastAPI, Django, Flask, Starlette, aiohttp, or Sanic — Litestar has its own runtime-introspection and DI model.

Auto-activate for msgspec imports, msgspec.Struct definitions, msgspec.json/msgpack usage. High-performance Python serialization and validation library: Struct definitions, Meta constraints, tagged unions, enc_hook/dec_hook, convert(). Produces msgspec Structs, serialization codecs, validation schemas, and type-safe conversion patterns. Use when: defining data models with msgspec, serializing/deserializing JSON or MessagePack, validating data with Meta constraints, building discriminated unions, or converting dicts/objects with msgspec.convert(). In Litestar apps, sqlspec.utils.serializers.to_json is the canonical serializer; hand-roll Encoder(enc_hook=...) only when sqlspec is not in-stack. Not for Pydantic models, dataclasses, or attrs -- msgspec has its own patterns.

Auto-activate for pytest_databases imports, conftest.py with database fixtures. Container-based database testing with pytest. Use when: creating PostgreSQL/MySQL/SQLite/Oracle fixtures, Docker test containers, database integration tests, or any pytest database setup. Produces container-based database test fixtures with proper lifecycle management. Not for mocking databases or non-pytest test frameworks.

Auto-activate for sqlspec imports. Produces database adapter configurations, SQL query mappings, and framework extensions using SQLSpec. Use when working with database adapters, SQL execution, query building, Arrow integration, parameter handling, framework extensions, filters, pagination, event channels, SQL file loading, or storage integrations. Not for raw SQL or ORM-specific patterns (see sqlalchemy, advanced-alchemy).

1 hook across 1 event