# Templates

Quickback provides pre-configured templates to get you started quickly. Each template combines a runtime, database, and auth provider into a working project.

The fastest way to start is `quickback start` — an interactive picker that asks for a template + project name and scaffolds in the current directory if it's empty, otherwise creates a subfolder. The picker offers `cloudflare`, `todos`, `blog`, and `blank`; every template (including `saas`) is available scriptably via `quickback create <template> <name>`.

```bash
# Interactive (recommended for first-time use)
mkdir my-app && cd my-app
npx @quickback-dev/cli start

# Already know what you want? Skip the prompts:
npx @quickback-dev/cli start blank        # config only, no features
npx @quickback-dev/cli start todos my-app # working CRUD example
```

## Available Templates

### Multi-tenant scaffolds

Cloudflare Workers + D1 + Better Auth with the organization plugin and a `member` / `admin` / `owner` role hierarchy wired in.

| Template | Includes | Command |
|----------|----------|---------|
| `cloudflare` | Bare scaffold — auth + DB + Hono, no example feature | `quickback create cloudflare my-app` |
| `todos` | Working todos feature: schema, masking, two actions (`complete` / `uncomplete`), and a `dashboard` named view | `quickback create todos my-app` |

The **todos** template is the recommended first read — it exercises every security pillar (firewall, access, guards, masking) plus actions and views in ~80 lines you can scan in five minutes.

### Fixed-org starter

| Template | Includes | Command |
|----------|----------|---------|
| `blog` | Blog with PUBLIC reads, admin writes, `publish` / `unpublish` actions, and a pinned organization id placeholder | `quickback create blog my-site` |

The **blog** template uses [pinned organization mode](/configure/single-tenant) and scaffolds `features.pinnedOrganizationId: "org_replace_me"`.

### Blank scaffold

| Template | Includes | Command |
|----------|----------|---------|
| `blank` | `quickback.config.ts` only — no example features | `quickback start blank` |

The blank template creates the project structure with `quickback.config.ts` only. Add your first feature by creating a file under `quickback/features/<name>/<name>.ts` exporting `defineTable(...)` — there is no separate `init` step.

### B2B SaaS

| Template | Includes | Command |
|----------|----------|---------|
| `saas` | Multi-tenant + **R2 file storage** + **outbound webhooks** + split databases + realtime + named views | `quickback create saas my-app` |

## What Each Template Includes

The `cloudflare`, `todos`, `blog`, and `saas` templates all scaffold:

- **`quickback.config.ts`** — Pre-configured with the right providers
- **`quickback/features/`** — Feature definitions (empty for `cloudflare`; populated for `todos` / `blog` / `saas`)
- **Deployment scripts** — `npm run deploy` for Cloudflare via wrangler

The `blank` template includes only:

- **`quickback.config.ts`**
- **`package.json`** — dependencies ready to install

## Choosing a Template

### Cloudflare bare scaffold

Best when you already know the conventions and want empty walls. Multi-tenant orgs are wired in; you add your own feature files.

### Todos (recommended for newcomers)

Best for learning by reading. Full multi-tenant security pillars, two actions, a named view (`/api/v1/todos/views/dashboard`), and field masking on the `description` column — all in a single ~80-line file you can copy-edit into your own table.

### Blog (pinned-organization CMS)

Best for personal sites, blogs, or any app that only needs one organization at runtime. Uses [pinned organization mode](/configure/single-tenant) — organization support stays on, but the generated app hard-codes one org id and hides org switching.

- Public JSON API for content
- Admin-only editing
- Pair with any frontend (Astro, Next.js, SvelteKit, etc.)

### Blank

Best when you know exactly what you want to build. Gets you the project structure and config without any opinionated features.

### SaaS

Best for production B2B work. Adds R2 file uploads, outbound webhooks (with retry/dedupe), split auth/features/webhooks databases, realtime broadcast, and named views.

## Template Aliases

For convenience, templates have short aliases:

| Alias | Full id |
|-------|---------|
| `cloudflare` / `cf` | `betterauth-d1-cloudflare` |
| `todos` | `todos-cloudflare` |
| `blog` | `blog-cloudflare` |
| `saas` | `b2bsaas-cloudflare` |
| `blank` / `empty` / `scaffold` | `empty-cloudflare` |

## After Scaffolding

`quickback start` runs scaffold + login + compile + install + drizzle in one flow. If you used the scriptable `quickback create` instead (or cancelled at the login prompt), finish setup with:

```bash
cd my-app
quickback compile   # prompts for login on first run; reuses session after
npm run dev
```

See the individual template guides for detailed setup:
- [Cloudflare Template](/start/template-cloudflare)
- [Blog Template](/start/template-blog)
- [Empty Scaffolding](/start/template-empty)
- [Pinned Organization Mode](/configure/single-tenant)