Templating

Execution Workflow

1. Choose the template engine that matches the project and ensure the corresponding Litestar extra is installed.
2. Configure template_config with the right TemplateConfig shape: directory, directory=[...], or instance=....
3. Return Template responses with explicit template_name or template_str and a stable, minimal context mapping.
4. Use built-in request, CSRF, and URL helpers for presentation concerns; keep domain logic out of templates.
5. Register engine-wide callables or environment customization centrally through engine_callback.
6. Verify missing-template behavior, route/static URL generation, CSRF rendering, and HTML output in tests.

Core Rules

• Register one template engine at the app level via template_config.
• Use directory or directory=[...] for normal file-based templates.
• Use instance= only when you intentionally own engine creation or loader/environment wiring.
• Do not combine instance with directory.
• Prefer template_name for normal pages and reusable fragments; use template_str only for small inline templates.
• Keep context string-keyed, explicit, and view-shaped rather than dumping service or ORM objects into the template.