# 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](https://chameleon.readthedocs.io/) 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](https://github.com/AGeekInside/fastapi-jinja) has the same shape and the same decorator-first design. Everything here will feel familiar there. # Install ``` bash 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()](../reference/global_init.md#fastapi_chameleon.global_init) once, and from then on every template path you write is relative to it. **`main.py`** ``` python 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`** ``` html Shelf Life

Hello world

Your message is ${message}

``` 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()](../reference/global_init.md#fastapi_chameleon.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: ``` html Shelf Life

Hello world

Your message is Let's go Chameleon and FastAPI!

``` 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](configuration.md). # Where to go next The rest of the guide follows the shop as it grows. - [Decorating Views](views.md): the three decorator forms, what a view may return, how a login form redirects, and [response()](../reference/response.md#fastapi_chameleon.response) for when you want the wheel yourself. - [Writing Templates](templates.md): Chameleon syntax for people arriving from Jinja, shared layouts with METAL, and the folder layout the name inference expects. - [Friendly Error Pages](error-pages.md): the book that sold yesterday, and how to say so in HTML instead of JSON. - [Troubleshooting](troubleshooting.md): every error the package or Chameleon can raise, what it is really telling you, and the fix. - [Testing and CI](testing.md): views are plain callables, so tests need no server and no port. - [Configuration](configuration.md): every [global_init()](../reference/global_init.md#fastapi_chameleon.global_init) option, verified by running it. - [How It Works](how-it-works.md): what happens at import time, what happens per request, and why error pages are exceptions. - [FAQ](faq.md).