Litestar Settings

Use this skill for typed settings, env loading, cached settings factories, and app-state wiring.

Code Style Rules

• Use dataclass settings plus get_env for fresh Litestar apps.
• Use pydantic-settings when the project already depends on Pydantic for config.
• Cache settings once per process.
• Keep secret values out of logs and generated docs.

Quick Reference

• Settings patterns: settings.md
• Pair with litestar-di for settings providers.
• Pair with litestar-deployment for runtime env wiring.

<workflow>

Workflow

1. Inventory required env vars and defaults.
2. Choose dataclass settings or the existing Pydantic settings path.
3. Add a cached factory.
4. Inject settings through app state or DI.

</workflow> <guardrails>

Guardrails

• Do not parse env vars repeatedly in handlers.
• Do not use msgspec Structs for env loading.
• Do not bake environment-specific values into code.
• Do not log secrets while debugging config.

</guardrails> <validation>

Validation Checkpoint

• Settings are typed.
• Settings are cached.
• Required values fail early.
• Tests can override settings without mutating global process env unexpectedly.

</validation> <example>

Example

from dataclasses import dataclass, field
from functools import lru_cache
from os import getenv

def get_env(key: str, default: str) -> str:
    return getenv(key, default)

@dataclass(frozen=True)
class AppSettings:
    name: str = field(default_factory=lambda: get_env("APP_NAME", "api"))

@lru_cache(maxsize=1)
def get_settings() -> AppSettings:
    return AppSettings()

</example>

References Index

• settings.md

Official References

• https://docs.litestar.dev/ - Litestar documentation
• https://docs.litestar.dev/latest/reference/ - Litestar API reference

Shared Styleguide Baseline

• General
• Python
• Litestar