Immutable. This exact content is served forever at /api/v1/blob/e4001eed0d1904d6.
---
name: litestar-routing
description: "Auto-activate for Controller, Router, @get/@post/@put/@patch/@delete, route_handler, path params, app/domain modules, or DomainPlugin layout. Not for frontend routers."
---
# Litestar Routing
Use this skill for route handlers, Controllers, Routers, domain clustering, and endpoint module layout.
## Code Style Rules
- Cluster Controllers by domain, not HTTP method.
- Keep handlers thin: parse request data, call a service, return a DTO or response object.
- Put shared path, dependencies, guards, and tags on the Controller class.
- Prefer the typed markers `FromPath[T]` / `FromQuery[T]` / `FromHeader[T]` / `FromCookie[T]` (Litestar ≥ 2.22) over `Annotated[T, Parameter()]`; never use the `field = Parameter(...)` default form (removed in 3.0).
- Use typed path parameters and explicit return annotations.
## Quick Reference
- Controller and route patterns: [routing.md](references/routing.md)
- Domain folder layout: [domains.md](references/domains.md)
- End-to-end vertical slice: [example.md](references/example.md)
<workflow>
## Workflow
1. Identify the domain boundary and URL prefix.
2. Pick a Controller when routes share path, guards, dependencies, or tags.
3. Keep data access in services and validation in DTOs.
4. Wire the Controller into the app or DomainPlugin.
</workflow>
<guardrails>
## Guardrails
- Do not group Controllers by HTTP method.
- Do not put authorization logic in handlers; use Guards.
- Do not hand-roll query parameter pagination; use the data-services skill.
- Do not put app-wide plugin setup in route modules.
</guardrails>
<validation>
## Validation Checkpoint
- [ ] Routes are domain-clustered.
- [ ] Handlers are async when they perform I/O.
- [ ] Shared guards and dependencies live on the Controller.
- [ ] DTO and service concerns link to their owning skills.
</validation>
<example>
## Example
```python
from litestar import Controller, get
from litestar.di import NamedDependency
class UserController(Controller):
path = "/users"
@get("/")
async def list_users(
self,
users_service: NamedDependency[UserService],
) -> list[UserRead]:
return await users_service.list_users()
```
</example>
## References Index
- [routing.md](references/routing.md)
- [domains.md](references/domains.md)
- [example.md](references/example.md)
## Official References
- <https://docs.litestar.dev/> - Litestar documentation
- <https://docs.litestar.dev/latest/reference/> - Litestar API reference
## Shared Styleguide Baseline
- [General](../litestar-styleguide/references/general.md)
- [Python](../litestar-styleguide/references/python.md)
- [Litestar](../litestar-styleguide/references/litestar.md)