// Create or modify Jinja2 templates. Use when: adding new HTML templates, configuring the Jinja2 environment, adding custom filters or globals, rendering templates outside FastAPI, or working with template inheritance.
| name | jinja-templates |
| description | Create or modify Jinja2 templates. Use when: adding new HTML templates, configuring the Jinja2 environment, adding custom filters or globals, rendering templates outside FastAPI, or working with template inheritance. |
context7: If the
mcp_context7tool is available, resolve and load the fulljinja2documentation before making changes:mcp_context7_resolve-library-id: "pallets/jinja" mcp_context7_get-library-docs: <resolved-id>
The Jinja2 environment is configured in {{cookiecutter.__package_slug}}/services/jinja.py. Templates live in {{cookiecutter.__package_slug}}/templates/.
The environment uses PackageLoader and autoescape=True:
from jinja2 import Environment, PackageLoader
env = Environment(
loader=PackageLoader("{{cookiecutter.__package_slug}}"),
autoescape=True,
)
{%- if cookiecutter.include_fastapi == "y" %}
For FastAPI responses, use response_templates:
from fastapi import Request
from {{cookiecutter.__package_slug}}.services.jinja import response_templates
@app.get("/page")
async def page(request: Request) -> Response:
return response_templates.TemplateResponse(
"page.html",
{"request": request, "title": "Page"},
)
{%- endif %}
Use the raw env for emails, tasks, CLI output:
from {{cookiecutter.__package_slug}}.services.jinja import env
template = env.get_template("emails/welcome.html")
html = template.render(name="World", year=2026)
Organize templates in subdirectories:
{{cookiecutter.__package_slug}}/templates/
├── base.html # Base layout
├── pages/
│ └── home.html
├── components/
│ └── header.html
└── emails/
└── welcome.html
Add to {{cookiecutter.__package_slug}}/services/jinja.py:
def format_currency(value: float) -> str:
return f"${value:,.2f}"
env.filters["currency"] = format_currency
env.globals["settings"] = settings
Base template (templates/base.html):
{%- raw %}
<!DOCTYPE html>
<html>
<head><title>{% block title %}Default{% endblock %}</title></head>
<body>
{% include "components/header.html" %}
<main>{% block content %}{% endblock %}</main>
</body>
</html>
{% endraw -%}
Child template (templates/pages/home.html):
{%- raw %}
{% extends "base.html" %}
{% block title %}Home{% endblock %}
{% block content %}<h1>Welcome</h1>{% endblock %}
{% endraw -%}
|safe on user-provided contentmarkupsafe.Markup in Python or |safe in templatesAny template whose source comes from users, third-party systems, or external APIs must be rendered with sandbox_env, not env.
The standard env allows templates to access arbitrary Python attributes and call any function passed to render(). A malicious template can exploit this to read secrets, access internals, or execute arbitrary code. The SandboxedEnvironment intercepts attribute access, method calls, and operators to prevent these attacks.
| Source | Environment |
|---|---|
Templates in templates/ (project code) | env |
| User-submitted templates | sandbox_env |
| Templates from external APIs or plugins | sandbox_env |
| Templates stored in the database by users | sandbox_env |
For usage patterns, blocked/allowed operations, immutable sandboxing, and customization — see references/sandboxed-templates.md.
{{cookiecutter.__package_slug}}/templates/services/jinja.pycomponents/ subdirectory|safe never applied to user inputenv used for non-FastAPI rendering, response_templates for FastAPIsandbox_env used for ALL user-provided or third-party template contentSecurityError caught and handled when rendering sandboxed templatesConfigure or use the aiocache caching layer. Use when: adding cache reads/writes, configuring cache backends, working with TTLs, enabling/disabling caching, or understanding the NoOpCache fallback pattern.
Create or modify Celery tasks and periodic task configuration. Use when: adding new background tasks, setting up periodic/scheduled tasks, configuring Celery workers, or understanding the Celery app setup.
Work with the Docker Compose development environment. Use when: starting or stopping services, inspecting logs, opening a shell in a container, resetting the database, or understanding the service topology.
Create or modify FastAPI routes. Use when: adding new API endpoints, creating Pydantic request/response models, registering routers, designing REST APIs, or following route conventions for this project.
Complete reference for all make targets in the project. Use when: looking up the right make command for any task — setup, testing, linting, formatting, database, packaging, or cleanup.
Add or modify application configuration settings. Use when: adding new environment variables, settings fields, understanding settings conventions, working with secrets, or configuring optional vs required settings.