// 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.
Configure 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.
| 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 templates