Getting Started

Every FastAPI app is born speaking JSON. Ask it for /, and it answers with curly braces. That is perfect for an API and slightly absurd for a website, where the thing on the other end of the request is a person with a browser, expecting a page.

fastapi-chameleon teaches your app a second language. You keep writing FastAPI views the way you always have, with path parameters, dependencies, async if you like. The difference is one decorator on top, and instead of returning JSON you return a plain dict. The decorator hands that dict to a Chameleon template, the template turns it into HTML, and FastAPI sends the page. Views decide, templates show. That is the whole arrangement.

Throughout this guide we will build a small site for a secondhand bookshop called Shelf Life. It has a home page, a catalog, a login form, and the occasional book that sold yesterday and now needs a graceful 404. Every mechanism in the package shows up somewhere in that story.

If Jinja is your template language of choice, the sister project fastapi-jinja has the same shape and the same decorator-first design. Everything here will feel familiar there.

Install

uv add fastapi-chameleon
# or
pip install fastapi-chameleon

Python 3.10 or newer. The package depends on exactly two things, fastapi and chameleon, and nothing else. You also need an ASGI server such as uvicorn to actually serve requests.

A first page

Two files are enough to open the shop. The template folder is handed to global_init() once, and from then on every template path you write is relative to it.

main.py

from pathlib import Path

import fastapi
import uvicorn

import fastapi_chameleon

app = fastapi.FastAPI()

# Point the engine at your template folder before any view is decorated.
BASE_DIR = Path(__file__).resolve().parent
fastapi_chameleon.global_init(BASE_DIR / 'templates', auto_reload=True)


@app.get('/')
@fastapi_chameleon.template('index.pt')
def hello_world():
    return {'message': "Let's go Chameleon and FastAPI!"}


if __name__ == '__main__':
    uvicorn.run(app, host='127.0.0.1', port=8000)

templates/index.pt

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Shelf Life</title>
</head>
<body>
<h1>Hello world</h1>
<p>Your message is <strong>${message}</strong></p>
</body>
</html>

Run it with python main.py or uvicorn main:app and open http://127.0.0.1:8000. Both commands work here for a reason worth noticing: global_init() runs at import time, before the decorated view is defined. Keep that order and the package never surprises you.

What you get back

The decorated function no longer returns a dict. It returns a fastapi.Response carrying a 200 status, a text/html content type, and this body:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Shelf Life</title>
</head>
<body>
<h1>Hello world</h1>
<p>Your message is <strong>Let's go Chameleon and FastAPI!</strong></p>
</body>
</html>

Each key in the dict became a variable in the template. ${message} was replaced by the string the view returned. There is no context object to build, no TemplateResponse to construct, no request to thread through by hand. The dict is the model.

Two details in that example are small now and important later:

  • Decorator order. The route decorator @app.get(...) is on the outside. @fastapi_chameleon.template(...) sits directly on the function. FastAPI must see the already-decorated view.
  • auto_reload=True. Chameleon compiles templates once and caches them, which is what you want in production. While you are editing templates every thirty seconds, you want them re-read. This flag is the switch. See Configuration.

Where to go next

The rest of the guide follows the shop as it grows.

  • Decorating Views: the three decorator forms, what a view may return, how a login form redirects, and response() for when you want the wheel yourself.
  • Writing Templates: Chameleon syntax for people arriving from Jinja, shared layouts with METAL, and the folder layout the name inference expects.
  • Friendly Error Pages: the book that sold yesterday, and how to say so in HTML instead of JSON.
  • Troubleshooting: every error the package or Chameleon can raise, what it is really telling you, and the fix.
  • Testing and CI: views are plain callables, so tests need no server and no port.
  • Configuration: every global_init() option, verified by running it.
  • How It Works: what happens at import time, what happens per request, and why error pages are exceptions.
  • FAQ.