Core concepts

A few building blocks explain how Skaff keeps generated projects reproducible and upgradeable.

Templates and repositories

Templates live in Git repositories under root-templates/<name>/. Each template exports a templateConfig.ts module alongside a templates/ directory (and optional subtemplates/). Skaff reads this metadata to know how to prompt for input, where to write files, and which hooks to run.

root-templates/
  nextjs-app/
    templateConfig.ts
    templates/
    subtemplates/

Template settings

When a template runs, Skaff validates user input against the Zod schema exported from templateConfig.ts. The resulting object is stored inside the generated project as templateSettings.json so future diffs can replay the exact same answers.

Instances and subtemplates

Every template invocation becomes an instance. Root templates usually have an instance ID such as root, while subtemplates receive generated IDs. Skaff tracks each instance’s revision hash and settings, allowing you to:

• Add new subtemplates later with skaff project add-subtemplate or through the web UI.
• Modify or re-run specific instances without touching the rest of the project.

Diffs and revisions

Skaff renders templates in a temporary Git repository and produces a patch before writing to disk. For new projects you review the initial file tree; for updates you only see the changes between the stored revision hash and the new template revision. Accepting the diff applies the patch so you can commit it with your normal Git workflow.

With these ideas in mind you can comfortably follow the CLI and template authoring guides that build on top of them.