# Templates (contributor index)

> **This file is for contributors maintaining the templates.** End-users
> see the per-template `README.md` after `spv init` copies the files
> into their project.

`spv init` copies one of these directories verbatim, substituting a few
template variables (`{{projectName}}`, `{{projectNameKebab}}`,
`{{componentName}}`). The init command logic itself lives in the
generator at
`engines/libs/instance-factories/cli/templates/commander/command-generator.ts`
in the `specverse-engines` repo.

## Templates

| Template | Default? | What it generates |
|---|---|---|
| **`full-stack/`** | ✅ yes | Backend (Fastify + Prisma + SQLite) **and** frontend (React + Vite + Tailwind), wired together. Used when `spv init` is called without `--template`. |
| **`backend-only/`** | no | Backend API only — REST routes, Prisma schema, no UI. For microservices and API-first development. |
| **`frontend-only/`** | no | React SPA only — connects to an external API via `VITE_API_BASE_URL`. For JAMstack / frontend-first projects. |

Use:

```bash
spv init my-app                        # full-stack (default)
spv init my-api  --template backend-only
spv init my-spa  --template frontend-only
```

## Variable substitution

`spv init` walks every file in the chosen template and replaces:

| Placeholder | Replaced with | Example for `spv init my-app` |
|---|---|---|
| `{{projectName}}` | name as provided | `my-app` |
| `{{projectNameKebab}}` | kebab-case name | `my-app` |
| `{{componentName}}` | PascalCase, hyphens removed | `MyApp` |
| `{{PROJECT_NAME}}` | name as provided (legacy) | `my-app` |

`gitignore` and `dot.env.example` get renamed on copy to `.gitignore`
and `.env.example` so npm doesn't strip them from published packages.

## Adding a new template

1. `mkdir templates/my-template/`
2. Drop in `specs/main.specly`, `manifests/implementation.yaml`,
   `package.json`, `README.md`, plus any starter content
3. Use `{{componentName}}` (not the literal project name) in the spec
   so it gets substituted on init
4. Validate with `spv init test-it --template my-template` →
   `cd test-it && npm run setup`

## Maintaining existing templates

When you change a template, run a fresh `spv init` against it and
walk the README's quick-start as if you were a new user. The bin
wrapper hint and the README sample code both need to match the
actual scripts in `package.json`.