Create your own template

If you ship the same starter shape ten times a year, make it a Caddi template. The contract is small — a few files at the root and three branches.

The contract

Public GitHub repo Caddi can fork (or private, with the GitHub App granted access).
Three long-lived branches: main, staging, dev. The contents should match — Caddi creates branches by ref, not by diff.
An AGENTS.md at the repo root.
A caddi.template.json at the repo root describing the env-var schema.
An .env.example matching that schema.

caddi.template.json

json

{
  "name": "Acme Starter",
  "slug": "acme-starter",
  "stack": "Next.js 15 + Tailwind",
  "description": "Our house Next.js starter with the form, footer, and theme we use everywhere.",
  "env": [
    { "name": "NEXT_PUBLIC_SITE_URL",       "type": "plain",  "required": true },
    { "name": "NEXT_PUBLIC_CADDI_FORM_URL", "type": "plain",  "required": true,
      "fill": "@caddi/form-endpoint" },
    { "name": "DATABASE_URL",               "type": "secret", "required": false },
    { "name": "RESEND_API_KEY",             "type": "secret", "required": false }
  ],
  "scaffold": {
    "rename": [
      { "from": "Acme Starter",  "to": "{project.name}" },
      { "from": "acme-starter",  "to": "{project.slug}" }
    ]
  }
}

fill tells Caddi to inject a runtime value during scaffold. Today only @caddi/form-endpoint is supported. More on the roadmap.

Registering

bash

caddi templates add \
  --repo github.com/your-org/acme-starter \
  --slug acme-starter

Once registered, the template shows up in caddi init and in the dashboard’s template picker for your agency only.

Custom templates are private to your agency by default. Open a PR against the canonical starters repo if you want yours to ship to everyone.

Updating

Templates evolve. When you push to the canonical template’s main, Caddi surfaces a “new version available” badge on every project scaffolded from it. Applying the update is a click — Caddi opens a PR with the upstream changes.

Environments →