Extensions

What is an extension?

An extension is a self-contained package that adds files, dependencies, and scripts to a scaffolded project. Extensions are composable: you can apply multiple compatible extensions in a single command and they are merged intelligently.

Each extension declares which template types it is compatible with (e.g. fastapi-backend, django-backend, cli-app), so the CLI only shows you relevant options for your chosen template.

uvx create-awesome-python-app@latest my-app --template fastapi-starter --addons fastapi-docker postgres github-setup

Extension categories

Extensions are organized into 8 categories covering the most common project needs.

How extensions work

When the CLI applies an extension it performs a deep merge of the extension's files and pyproject.toml fields into the scaffolded project:

1. Files — source files from the extension are copied or appended to the project. Filenames ending in .template are processed as EJS templates before being written.
2. Dependencies — extension dependency lists are merged into the project's pyproject.toml (runtime and dev groups).
3. Scripts — any task scripts or Makefile targets defined by the extension are merged with existing project tooling.
4. Incompatibilities — extensions declare incompatibleWith slugs so the CLI prevents conflicting combinations (e.g. two different test runners).

Extension file structure

Extensions live in the extensions/ directory of the cpa-templates repository:

extensions/
└── your-extension-name/
    ├── files/            # Files merged into the project tree
    ├── pyproject/        # Optional dependency fragments for merge
    ├── extension.json    # Extension metadata and compatibility
    └── README.md

Listing available extensions

uvx create-awesome-python-app --list-addons

Or browse the full catalogue on the Extensions page, where you can filter by template type and category.