Adoption Paths

QuadKit is designed for incremental adoption. You do not install a catalog; you scaffold with the CLI and add packages as the application grows. The public line is small on purpose — thirteen packages, one project shape.

Day one — the CLI

uv add "quadkit-cli>=0.0.42,<0.1"
quadkit new project my-app --template web-api
cd my-app
quadkit run

That is the supported start. Templates (minimal, api, web-api, graphql, worker, full, fullstack) pick packages and application.yaml sections — not a second project shape. Feature types live in domains/. App providers live in app-root di/.

Hand-wiring create_app() is possible; the CLI is what generators and quadkit run expect. See Installation and Project Structure.

Starter — a web API

Enough to serve HTTP with OpenAPI. No database, no cache, no auth — fine for prototypes and early services.

• quadkit + quadkit-contracts — DI container, Application, YAML config, Result
• quadkit-web — ASGI, controllers, middleware, OpenAPI (the web-api template)

quadkit new project my-app --template web-api
quadkit run

Tip

This is a complete API server. Add persistence when you have something to persist — not because the framework requires it.

Standard — test it, then ship it

The next step is not another library; it is making the app testable and shippable.

• quadkit-testing — test harnesses, fakes, fixtures that boot the real application (uv add --dev)
• quadkit-cli — quadkit gen for new controllers and services, quadkit db/quadkit config for operations

uv add --dev quadkit-testing
quadkit gen controller users --module billing
quadkit run --server granian

See Testing and Deployment.

Beyond the public line

Persistence, auth, queues, search, storage, and the AI platform are not published — they are part of the private repository and are not installable from PyPI. If you see one referenced in a changelog or a design note, treat it as future work rather than an available dependency.

That is deliberate: the thirteen published packages are the contract surface. When one of them stabilises, the rest layer on top of it without changing your application code.

Note

quadkit add only advertises providers whose distribution is installed, so a public project never gets a dependency line it cannot fetch.

Decision flow

Starting a new project?
├── Prototype or microservice → CLI + web-api template
├── Keep it alive long term   → add quadkit-testing, wire health and logs
├── Need persistence / auth   → not published yet; keep contracts, add later
└── Need AI features          → not published yet; keep contracts, add later

Each step is a superset of the one before it. Moving forward is uv add, not a rewrite.

---

See Compatibility for extras, dependency rules, and runtime constraints.