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.
• Keep custom template callables side-effect free and presentation-focused.
• Use Litestar URL helpers instead of hardcoding route or static asset paths in markup.
• Treat CSRF helpers as transport concerns and wire them only when CSRF protection is enabled.

Decision Guide

• Match the existing project engine unless there is a clear reason to migrate.
• Use Jinja when the project wants the default Litestar path and broad ecosystem support.
• Use Mako or MiniJinja when the project already standardizes on those template syntaxes.
• Use multiple template directories only when lookup truly spans shared and feature-local templates.
• Use instance= when you need a custom environment, loader, or preconfigured engine object.
• Use engine_callback when the engine needs custom callables, globals, or centralized one-time setup.
• Implement a custom engine only when Jinja, Mako, and MiniJinja do not fit the project.

Reference Files

Read only the sections you need:

• For engine selection, install extras, TemplateConfig, directory vs. instance setup, and engine access, read references/engine-selection-and-setup.md.
• For Template responses, file vs. string rendering, context shaping, request access, and CSRF inputs, read references/template-responses-and-context.md.
• For built-in template callables, registering custom callables, and implementing a custom engine protocol, read references/template-callables-and-custom-engines.md.

Recommended Defaults

• Keep templates in dedicated directories with engine-specific suffixes such as .jinja2, .mako, or .minijinja.
• Pass small view models or explicit dictionaries to templates instead of raw persistence models when possible.
• Use url_for and url_for_static_asset inside templates for links and asset references.
• Use csrf_input for HTML forms and csrf_token only when the token must be embedded another way.
• Keep partials, layouts, and page templates separate so fragment rendering stays predictable.
• Reach for template_str mainly for very small fragments, prototyping, or HTMX-style inline responses.

Anti-Patterns

• Mixing directory and instance in the same TemplateConfig.
• Treating templates as a place for business rules, permission checks, or database lookups.
• Returning large full-page HTML from inline template_str snippets.
• Passing large opaque objects into context when the template needs only a few fields.
• Hardcoding URLs for routes or static files in templates.
• Registering template callables ad hoc inside handlers instead of once through engine configuration.
• Following older custom-engine examples without checking the current protocol surface in the reference docs.

Validation Checklist

• Confirm the correct Litestar engine extra is installed.
• Confirm template_config exists and uses a valid directory or instance configuration.
• Confirm template names resolve from the intended directory set and fail clearly when missing.
• Confirm context keys and request-dependent template values render as expected.
• Confirm CSRF helpers appear only when CSRF protection is configured.
• Confirm route and static asset URLs reverse correctly through template helpers.
• Confirm inline string templates are limited to cases where file-based templates would add unnecessary overhead.
• Confirm tests cover both full-page and fragment responses where applicable.

Cross-Skill Handoffs

• Use litestar-htmx for fragment-oriented update flows and progressive enhancement.
• Use litestar-responses when response container behavior, headers, cookies, or status codes are the main concern.
• Use litestar-static-files when asset mounting and static URL behavior are part of the task.
• Use litestar-security when CSRF configuration or broader web security policy is the real issue.
• Use litestar-testing for client assertions on rendered HTML, redirects, and form flows.

Litestar References

• https://docs.litestar.dev/latest/usage/templating.html
• https://docs.litestar.dev/latest/reference/template.html