Litestar Routing

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

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.

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.

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.

Example

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()

References Index

• [routing.md](references/routing.md)
• [domains.md](references/domains.md)
• [example.md](references/example.md)

Official References

• - Litestar documentation
• - Litestar API reference

Shared Styleguide Baseline

• [General](../litestar-styleguide/references/general.md)
• [Python](../litestar-styleguide/references/python.md)
• [Litestar](../litestar-styleguide/references/litestar.md)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: litestar-org
• Source: litestar-org/litestar-skills
• License: MIT
• Homepage: https://github.com/litestar-org/litestar-skills

Install and usage instructions live in the source repository linked above.