Immutable. This exact content is served forever at /api/v1/blob/69c6f17c055a64e8.
---
name: litestar-settings
description: "Auto-activate for get_env, dataclass settings, pydantic_settings, BaseSettings, lru_cache config factories, app.state settings, LITESTAR_APP, or env parsing. Not for frontend env."
---
# 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](references/settings.md)
- Pair with [litestar-di](../litestar-di/SKILL.md) for settings providers.
- Pair with [litestar-deployment](../litestar-deployment/SKILL.md) 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
```python
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](references/settings.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)