@quickback-dev/cli 0.17.1 → 0.18.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -5,33 +5,58 @@ The Quickback CLI is the fastest way to create, compile, and manage your backend
5
5
  ## Installation
6
6
 
7
7
  ```bash
8
+ # One-shot via npx — recommended for first run
9
+ npx @quickback-dev/cli start
10
+
11
+ # Or install globally for repeat use
8
12
  npm install -g @quickback-dev/cli
9
13
  ```
10
14
 
11
15
  ## Commands
12
16
 
13
- ### Create a Project
17
+ ### Start a Project (interactive)
18
+
19
+ ```bash
20
+ quickback start
21
+ ```
22
+
23
+ Interactive onboarding designed for new users. No flags required.
24
+
25
+ - Prompts for a template (curated free-tier picker: `cloudflare`, `todos`, `blog`, `empty`)
26
+ - Prompts for a project name (defaults to the current directory's name if empty)
27
+ - Auto-detects whether to scaffold in-place or create a `./<name>/` subdirectory
28
+ - Defers login until just before the compile step — cancel at the auth prompt and the scaffold stays on disk, ready for `quickback compile` later
29
+
30
+ **Example:**
31
+ ```bash
32
+ mkdir my-app && cd my-app
33
+ npx @quickback-dev/cli start
34
+ ```
35
+
36
+ ### Create a Project (scriptable)
14
37
 
15
38
  ```bash
16
39
  quickback create <template> <name>
17
40
  ```
18
41
 
19
42
  **Templates:**
20
- - `cloudflare` - Cloudflare Workers + D1 + Better Auth (free)
21
- - `supabase` - Hono + Supabase Postgres + Supabase Auth (free)
22
- - `blog` - Single-tenant blog (PUBLIC reads, admin writes) (free)
23
- - `empty` - Cloudflare scaffold, no example features (free)
24
- - `multi-tenant` - Full SaaS with orgs, teams, billing (pro)
43
+ - `cloudflare` — Cloudflare Workers + D1 + Better Auth, bare scaffold (free)
44
+ - `todos` — Working todos example with masking + actions + a named view (free)
45
+ - `blog` — Single-tenant blog, PUBLIC reads, admin writes (free)
46
+ - `empty` — Cloudflare scaffold, no example features (free)
47
+ - `saas` — Full B2B SaaS: orgs, R2 file storage, webhooks, split databases, realtime (pro)
25
48
 
26
49
  **Example:**
27
50
  ```bash
28
- quickback create cloudflare my-app
51
+ quickback create todos my-app
29
52
  ```
30
53
 
31
54
  This scaffolds a complete project with:
32
- - `quickback.config.ts` - Project configuration
33
- - `quickback/features/` - Your table definitions
34
- - Example todos feature with full security configuration
55
+ - `quickback.config.ts` — Project configuration
56
+ - `quickback/features/` — Your table definitions
57
+ - Example feature with full security configuration (for `todos` / `blog` / `saas`)
58
+
59
+ See the [Templates](/compiler/getting-started/templates) page for a deeper guide on choosing between them.
35
60
 
36
61
  ### Compile Definitions
37
62
 
@@ -68,19 +93,6 @@ ls quickback/.archives/
68
93
 
69
94
  As a safety net, the wipe is **skipped** when the manifest contains zero files for the target directory — that's almost always an upstream compile bug, and we'd rather keep your last working tree than overwrite it with nothing.
70
95
 
71
- ### Initialize Structure
72
-
73
- ```bash
74
- quickback init
75
- ```
76
-
77
- Creates the Quickback folder structure in an existing project:
78
- ```
79
- quickback/
80
- features/
81
- quickback.config.ts
82
- ```
83
-
84
96
  ### View Documentation
85
97
 
86
98
  ```bash
@@ -209,18 +221,27 @@ The active organization is stored in your credentials and sent with compile requ
209
221
  ## Quick Start
210
222
 
211
223
  ```bash
212
- # 1. Create a new project
213
- quickback create cloudflare my-app
214
- cd my-app
224
+ # 1. Start a new project (interactive — picks template, scaffolds,
225
+ # prompts for login only when needed)
226
+ mkdir my-app && cd my-app
227
+ npx @quickback-dev/cli start
228
+
229
+ # 2. Run locally
230
+ npm run dev
231
+ ```
215
232
 
216
- # 2. Define your tables in quickback/features/
217
- # (Already has example todos feature)
233
+ Or the scriptable form:
218
234
 
219
- # 3. Compile
220
- quickback compile
235
+ ```bash
236
+ # 1. Create the project (scaffolds + compiles + installs)
237
+ quickback create todos my-app # prompts for login on first compile
238
+ cd my-app
221
239
 
222
- # 4. Run
240
+ # 2. Run
223
241
  npm run dev
242
+
243
+ # 3. Recompile after editing definitions
244
+ quickback compile
224
245
  ```
225
246
 
226
247
  ## Options
@@ -278,9 +299,9 @@ Make sure the CLI is installed globally:
278
299
  npm install -g @quickback-dev/cli
279
300
  ```
280
301
 
281
- Or use npx:
302
+ Or use npx (no global install needed):
282
303
  ```bash
283
- npx @quickback-dev/cli create cloudflare my-app
304
+ npx @quickback-dev/cli start
284
305
  ```
285
306
 
286
307
  ### Compile errors
@@ -24,18 +24,18 @@ Quickback offers a hosted compiler at `https://compiler.quickback.dev`. The CLI
24
24
  ## Quick Start
25
25
 
26
26
  ```bash
27
- # 1. Install the CLI
28
- npm install -g @quickback-dev/cli
27
+ # 1. Scaffold + compile interactively
28
+ mkdir my-app && cd my-app
29
+ npx @quickback-dev/cli start
30
+ ```
29
31
 
30
- # 2. Create a project
32
+ `start` walks through template selection, scaffolding, login (only when needed), and the first compile in one flow. Or do it scriptably:
33
+
34
+ ```bash
35
+ npm install -g @quickback-dev/cli
31
36
  quickback create cloudflare my-app
32
37
  cd my-app
33
-
34
- # 3. Log in
35
- quickback login
36
-
37
- # 4. Compile
38
- quickback compile
38
+ quickback compile # prompts for login on the first run
39
39
  ```
40
40
 
41
41
  ## Existing Databases
@@ -1,17 +1,17 @@
1
1
  # Multi-Domain Architecture
2
2
 
3
- A single Quickback-compiled Cloudflare Worker can serve your API, CMS, Account UI, and Admin panel on separate custom domains. The compiler generates hostname-based routing so each domain serves the right content.
3
+ A single Quickback-compiled Cloudflare Worker can serve your API, CMS, Account UI, Admin panel, and your own product SPAs on separate custom domains. The compiler generates hostname-based routing so each domain serves the right content.
4
4
 
5
5
  ## How It Works
6
6
 
7
- When you configure custom domains for CMS, Account, or Admin, the compiler:
7
+ When you configure custom domains for CMS, Account, Admin, or `apps`, the compiler:
8
8
 
9
9
  1. Adds `custom_domain` routes to `wrangler.toml`
10
10
  2. Generates hostname-based middleware in the Worker
11
11
  3. Auto-configures cross-subdomain cookies for shared authentication
12
12
  4. Auto-infers a unified `quickback.{baseDomain}` fallback domain
13
13
 
14
- All five domains point to the **same Worker** — there's only one deployment.
14
+ All configured domains point to the **same Worker** — there's only one deployment.
15
15
 
16
16
  ## Domain Types
17
17
 
@@ -21,6 +21,7 @@ All five domains point to the **same Worker** — there's only one deployment.
21
21
  | `cms.example.com` | `cms: { domain }` | CMS SPA | Blocked (404) |
22
22
  | `auth.example.com` | `account: { domain }` | Account SPA | Pass-through |
23
23
  | `admin.example.com` | `account: { adminDomain }` | Account SPA | Pass-through |
24
+ | `www.example.com` | `apps: { <name>: { domain } }` | User-authored SPA | Pass-through |
24
25
  | `quickback.example.com` | Auto-inferred | Everything | All |
25
26
 
26
27
  ### CMS Domain
@@ -35,6 +36,32 @@ Serves the Account SPA at root (`/`). API and auth routes pass through to the Wo
35
36
 
36
37
  Identical behavior to the Account domain — serves the same Account SPA at root. The Account SPA's client-side router handles the `/admin` route, restricting access to users with the `admin` role.
37
38
 
39
+ ### App Domains
40
+
41
+ Mount your own product SPAs on dedicated hostnames via the `apps` field. Each entry binds one or more hostnames to a directory under `src/apps/<name>/` and inherits the same API/auth pass-through behavior as the Account domain — so the SPA can hit `/api/v1/...` and `/auth/...` same-origin without CORS.
42
+
43
+ ```typescript
44
+ apps: {
45
+ www: {
46
+ domain: "www.example.com",
47
+ aliasDomains: ["example.com"], // apex serves the same SPA
48
+ },
49
+ marketing: {
50
+ domain: "marketing.example.com",
51
+ },
52
+ }
53
+ ```
54
+
55
+ | Option | Required | Description |
56
+ |--------|----------|-------------|
57
+ | `domain` | Yes | Primary custom hostname served at root (`/`) |
58
+ | `aliasDomains` | No | Additional hostnames that serve the same SPA. Each gets its own `custom_domain = true` route. Common case: apex (`example.com`) alongside `www.example.com`. |
59
+ | `assetsDir` | No | Subdirectory under `src/apps/` to serve from. Defaults to the record key. Override only when the on-disk directory needs to differ from the URL-facing name. |
60
+
61
+ Drop the prebuilt SPA output at `quickback/apps/<name>/` — the source-apps passthrough copies it byte-for-byte into `src/apps/<name>/` on every compile. The compiler doesn't build the SPA; it just emits routing for whatever's already there. See [Output Structure](/compiler/config/output#source-apps-quickbackapps) for the passthrough rules.
62
+
63
+ The names `cms`, `account`, and `public` are reserved (they collide with compiler-emitted directories under `src/apps/`). Two app entries can't claim the same hostname, and an app's hostname can't collide with `cms.domain` / `account.domain` / `account.adminDomain`.
64
+
38
65
  ### Unified Domain
39
66
 
40
67
  The compiler auto-infers a `quickback.{baseDomain}` domain from your configured custom domains. For example, if you have `cms.example.com`, it creates `quickback.example.com`.
@@ -68,11 +95,12 @@ export default {
68
95
  name: "My App",
69
96
  auth: { password: true, admin: true },
70
97
  },
71
- trustedOrigins: [
72
- "https://auth.example.com",
73
- "https://admin.example.com",
74
- "https://cms.example.com",
75
- ],
98
+ apps: {
99
+ www: {
100
+ domain: "www.example.com",
101
+ aliasDomains: ["example.com"],
102
+ },
103
+ },
76
104
  providers: {
77
105
  runtime: { name: "cloudflare", config: {
78
106
  routes: [{ pattern: "api.example.com", custom_domain: true }],
@@ -82,6 +110,8 @@ export default {
82
110
  };
83
111
  ```
84
112
 
113
+ `trustedOrigins` is optional here — every `cms.domain`, `account.domain`, `account.adminDomain`, and `apps[*].domain` (plus aliases) is automatically added. Declare `trustedOrigins` only when you need to allow an origin the compiler can't infer (e.g. a third-party domain).
114
+
85
115
  This generates the following `wrangler.toml` routes:
86
116
 
87
117
  ```toml
@@ -90,18 +120,20 @@ routes = [
90
120
  { pattern = "cms.example.com", custom_domain = true },
91
121
  { pattern = "auth.example.com", custom_domain = true },
92
122
  { pattern = "admin.example.com", custom_domain = true },
123
+ { pattern = "www.example.com", custom_domain = true },
124
+ { pattern = "example.com", custom_domain = true },
93
125
  { pattern = "quickback.example.com", custom_domain = true }
94
126
  ]
95
127
  ```
96
128
 
97
129
  ## Cross-Subdomain Authentication
98
130
 
99
- When two or more custom domains share a parent domain (e.g., `cms.example.com` + `auth.example.com`), the compiler automatically configures Better Auth for cross-subdomain cookie sharing:
131
+ When two or more custom domains share a parent domain (e.g., `cms.example.com` + `auth.example.com` + `www.example.com`), the compiler automatically configures Better Auth for cross-subdomain cookie sharing. App hostnames (primary + aliases) are folded into the shared-parent detection alongside the CMS, Account, Admin, and top-level `domain` slots:
100
132
 
101
133
  - Sets `crossSubDomainCookies: { enabled: true, domain: '.example.com' }`
102
134
  - Sets `sameSite: 'none'` and `secure: true` on auth cookies
103
135
 
104
- This means a user who logs in on `auth.example.com` is automatically authenticated on `cms.example.com` and `admin.example.com` — no additional setup needed.
136
+ This means a user who logs in on `auth.example.com` is automatically authenticated on `cms.example.com`, `admin.example.com`, and `www.example.com` — no additional setup needed. Apex aliases (e.g. `example.com` listed under `aliasDomains`) are recognized as already being the parent — they don't break shared-parent equality.
105
137
 
106
138
  > **Automatic Detection**
107
139
  >
@@ -128,6 +160,8 @@ The compiler generates middleware that checks `new URL(c.req.url).hostname` on e
128
160
 
129
161
  **Account/Admin domain** — API and auth routes (`/api/`, `/auth/`, `/admin/`, `/storage/`, `/health`) pass through to Hono handlers. All other paths are mapped to the `/account/` asset prefix and served with SPA fallback to `/account/index.html`.
130
162
 
163
+ **App domain** — Identical to Account: API/auth/admin/storage/health pass through, other paths map to `/<assetsDir>/` with SPA fallback. The multi-domain catchall (emitted when both CMS and Account are configured) explicitly skips app hostnames, so an API miss on an app host lands in `app.notFound` (404 JSON) instead of stray-serving a sibling SPA's HTML.
164
+
131
165
  **Unified domain** — No hostname filtering. CMS is served at `/cms/`, Account at `/account/`. Root (`/`) redirects to `/cms/`. API routes work at their standard paths.
132
166
 
133
167
  ## Without Custom Domains
@@ -353,7 +353,7 @@ Notes:
353
353
 
354
354
  ### Source Apps (`quickback/apps/`)
355
355
 
356
- For hand-authored TypeScript apps that live alongside the compiler-emitted SPA shells, drop them under `quickback/apps/<name>/`. The CLI copies the tree into `src/apps/<name>/` on every compile, byte-for-byte, after the compiler has finished writing.
356
+ For hand-authored TypeScript apps and prebuilt SPA bundles that live alongside the compiler-emitted SPA shells, drop them under `quickback/apps/<name>/`. The CLI copies the tree into `src/apps/<name>/` on every compile, byte-for-byte, after the compiler has finished writing. Bind a directory to a hostname via [`config.apps`](/compiler/config/domains#app-domains) — the compiler emits the matching Worker middleware automatically.
357
357
 
358
358
  ```
359
359
  quickback/apps/ # Source — checked into your repo
@@ -2,14 +2,24 @@
2
2
 
3
3
  The Cloudflare template creates a production-ready backend running on Cloudflare Workers with D1 (SQLite at the edge), KV storage, and Better Auth.
4
4
 
5
+ `cloudflare` is a **bare scaffold** — multi-tenant orgs + auth + DB are wired in, but there are no example features. Add your own feature files under `quickback/features/`. If you want a working example to read first, use the [todos template](/compiler/getting-started/templates#multi-tenant-scaffolds-free) — same providers, but with a complete `todos` feature ready to extend.
6
+
5
7
  ## Create the Project
6
8
 
9
+ The fastest path is `start` — interactive, scaffold + login + compile in one flow:
10
+
7
11
  ```bash
8
- quickback create cloudflare my-app
9
- cd my-app
12
+ mkdir my-app && cd my-app
13
+ npx @quickback-dev/cli start
14
+ # pick "Cloudflare (bare scaffold)" at the prompt
10
15
  ```
11
16
 
12
- Aliases: `quickback create cf my-app`
17
+ Scriptable equivalent:
18
+
19
+ ```bash
20
+ quickback create cloudflare my-app # aliases: cf
21
+ cd my-app
22
+ ```
13
23
 
14
24
  This scaffolds a project with:
15
25
 
@@ -17,11 +27,8 @@ This scaffolds a project with:
17
27
  my-app/
18
28
  ├── quickback/
19
29
  │ ├── quickback.config.ts # Compiler configuration
20
- │ └── features/
21
- │ └── todos/
22
- │ ├── todos.ts # Schema + security (defineTable)
23
- │ └── actions.ts # Custom actions
24
- ├── src/ # Compiled output (generated)
30
+ │ └── features/ # (empty — add your own)
31
+ ├── src/ # Compiled output (generated by `quickback compile`)
25
32
  ├── package.json
26
33
  ├── tsconfig.json
27
34
  ├── wrangler.toml
@@ -33,90 +40,78 @@ my-app/
33
40
  ### quickback.config.ts
34
41
 
35
42
  ```typescript
36
- import { defineConfig } from "@quickback/compiler";
37
-
38
- export default defineConfig({
43
+ export default {
39
44
  name: "my-app",
40
45
  template: "hono",
41
- features: ["organizations"],
46
+ features: {
47
+ organizations: true,
48
+ },
49
+ auth: {
50
+ // Use "role+" in access rules to mean "this role and above".
51
+ // e.g. roles: ["member+"] expands to ["member", "admin", "owner"].
52
+ roleHierarchy: ["member", "admin", "owner"],
53
+ },
42
54
  providers: {
43
55
  runtime: { name: "cloudflare", config: {} },
44
56
  database: {
45
57
  name: "cloudflare-d1",
46
- config: { binding: "DB" },
58
+ config: { binding: "DB", realtime: true },
47
59
  },
48
60
  auth: { name: "better-auth", config: {} },
49
61
  },
50
- });
62
+ };
51
63
  ```
52
64
 
53
- ### Example Feature (todos.ts)
65
+ ### Adding your first feature
54
66
 
55
- The template includes a `todos` feature with all four security pillars configured:
67
+ Create a file at `quickback/features/<name>/<name>.ts` and export a `defineTable(...)` default. The shape used by the `todos` template makes a good starting point — see [todos.ts in the template registry](/compiler/getting-started/templates#multi-tenant-scaffolds-free) for a full multi-tenant example with masking, actions, and a named view.
56
68
 
57
69
  ```typescript
58
- import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
70
+ // quickback/features/posts/posts.ts
71
+ import { sqliteTable, text } from "drizzle-orm/sqlite-core";
59
72
  import { defineTable } from "@quickback/compiler";
60
73
 
61
- export const todos = sqliteTable("todos", {
74
+ export const posts = sqliteTable("posts", {
62
75
  id: text("id").primaryKey(),
63
76
  title: text("title").notNull(),
64
- description: text("description"),
65
- completed: integer("completed", { mode: "boolean" }).default(false),
66
- priority: text("priority").default("medium"),
67
- dueDate: integer("due_date", { mode: "timestamp" }),
77
+ body: text("body"),
68
78
  organizationId: text("organization_id").notNull(),
69
- ownerId: text("owner_id").notNull(),
79
+ userId: text("user_id").notNull(),
70
80
  });
71
81
 
72
- export default defineTable(todos, {
73
- firewall: [
74
- { field: 'organizationId', equals: 'ctx.activeOrgId' },
75
- { field: 'deletedAt', isNull: true },
76
- ],
82
+ export default defineTable(posts, {
83
+ firewall: { organization: {}, owner: {}, softDelete: {} },
77
84
  guards: {
78
- createable: ["title", "description", "completed", "priority", "dueDate"],
79
- updatable: ["title", "description", "completed", "priority", "dueDate"],
80
- immutable: ["id", "organizationId", "ownerId"],
81
- },
82
- masking: {
83
- description: {
84
- type: "redact",
85
- show: { roles: ["owner", "admin"] },
86
- },
85
+ createable: ["title", "body"],
86
+ updatable: ["title", "body"],
87
+ immutable: ["id", "organizationId", "userId"],
87
88
  },
88
- read: {
89
- access: { roles: ["owner", "admin", "member"] },
90
- },
91
- create: { access: { roles: ["owner", "admin", "member"] } },
92
- update: { access: { roles: ["owner", "admin", "member"] } },
93
- delete: { access: { roles: ["owner", "admin"] }, mode: "soft" },
89
+ read: { access: { roles: ["member+"] } },
90
+ create: { access: { roles: ["member+"] } },
91
+ update: { access: { roles: ["member+"] } },
92
+ delete: { access: { roles: ["admin+"] }, mode: "soft" },
94
93
  });
95
94
  ```
96
95
 
97
96
  ## Setup Steps
98
97
 
98
+ If you used `quickback start`, dependencies, the first compile, and login are already done — skip to step 4. If you used `quickback create`, run these:
99
+
99
100
  ### 1. Install Dependencies
100
101
 
101
102
  ```bash
102
103
  npm install
103
104
  ```
104
105
 
105
- ### 2. Log In to the Compiler
106
-
107
- ```bash
108
- quickback login
109
- ```
110
-
111
- ### 3. Compile Your Definitions
106
+ ### 2. Compile Your Definitions
112
107
 
113
108
  ```bash
114
109
  quickback compile
115
110
  ```
116
111
 
117
- This sends your definitions to the Quickback compiler and generates the full `src/` directory, migrations, and configuration files.
112
+ This prompts for an account on the first run (sign in or create one in the browser), then generates the full `src/` directory, migrations, and configuration files. Subsequent compiles re-use the stored session.
118
113
 
119
- ### 4. Create D1 Databases
114
+ ### 3. Create D1 Databases
120
115
 
121
116
  The Cloudflare template uses **dual database mode** by default — separate databases for auth and application data.
122
117
 
@@ -142,7 +137,7 @@ database_name = "my-app-features"
142
137
  database_id = "paste-features-id-here"
143
138
  ```
144
139
 
145
- ### 5. Run Migrations (Local)
140
+ ### 4. Run Migrations (Local)
146
141
 
147
142
  ```bash
148
143
  npm run db:migrate:local
@@ -150,7 +145,7 @@ npm run db:migrate:local
150
145
 
151
146
  This applies migrations to both databases locally.
152
147
 
153
- ### 6. Start Development Server
148
+ ### 5. Start Development Server
154
149
 
155
150
  ```bash
156
151
  npm run dev
@@ -2,105 +2,107 @@
2
2
 
3
3
  Quickback provides pre-configured templates to get you started quickly. Each template combines a runtime, database, and auth provider into a working project.
4
4
 
5
+ 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. Every template below can be reached either via `start`'s picker (free tier) or scriptably via `quickback create <template> <name>`.
6
+
7
+ ```bash
8
+ # Interactive (recommended for first-time use)
9
+ mkdir my-app && cd my-app
10
+ npx @quickback-dev/cli start
11
+ ```
12
+
5
13
  ## Available Templates
6
14
 
7
- ### Full-Featured Templates
15
+ ### Multi-tenant scaffolds (free)
16
+
17
+ Cloudflare Workers + D1 + Better Auth with the organization plugin and a `member` / `admin` / `owner` role hierarchy wired in.
8
18
 
9
- These templates include an example feature (todos) with full security configuration.
19
+ | Template | Includes | Command |
20
+ |----------|----------|---------|
21
+ | `cloudflare` | Bare scaffold — auth + DB + Hono, no example feature | `quickback create cloudflare my-app` |
22
+ | `todos` | Working todos feature: schema, masking, two actions (`complete` / `uncomplete`), and a `dashboard` named view | `quickback create todos my-app` |
10
23
 
11
- | Template | Runtime | Database | Auth | Tenant | Command |
12
- |----------|---------|----------|------|--------|---------|
13
- | `cloudflare` | Cloudflare Workers | D1 (SQLite) | Better Auth | Multi-tenant | `quickback create cloudflare my-app` |
14
- | `multi-tenant` | Cloudflare Workers | D1 (SQLite) | Better Auth | Multi-tenant + orgs | `quickback create multi-tenant my-app` |
24
+ 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.
15
25
 
16
- ### Starter Templates
26
+ ### Single-tenant starter (free)
17
27
 
18
- Purpose-built templates with opinionated defaults for common use cases.
28
+ | Template | Includes | Command |
29
+ |----------|----------|---------|
30
+ | `blog` | Single-tenant blog with PUBLIC reads, admin writes, `publish` / `unpublish` actions | `quickback create blog my-site` |
19
31
 
20
- | Template | Runtime | Database | Tenant | Command |
21
- |----------|---------|----------|--------|---------|
22
- | `blog` | Cloudflare Workers | D1 | Single-tenant | `quickback create blog my-site` |
32
+ The **blog** template uses Better Auth's admin plugin (not the org plugin) and [single-tenant mode](/compiler/config/single-tenant) (`organizations: false`).
23
33
 
24
- The **blog** template creates a single-tenant blog/CMS backend with:
25
- - Public read access (no auth required for `list` and `get`)
26
- - Admin-only write access (create, update, delete, publish/unpublish)
27
- - A `posts` feature with title, slug, content, status, and publish date
28
- - [Single-tenant mode](/compiler/config/single-tenant) (`organizations: false`)
34
+ ### Empty scaffold (free)
29
35
 
30
- ### Empty Scaffolding
36
+ | Template | Includes | Command |
37
+ |----------|----------|---------|
38
+ | `empty` | `quickback.config.ts` only — no example features | `quickback create empty my-app` |
31
39
 
32
- Start from scratch with just the config file — no example features. Add your own definitions.
40
+ The empty 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.
33
41
 
34
- | Template | Runtime | Database | Command |
35
- |----------|---------|----------|---------|
36
- | `empty` | Cloudflare Workers | D1 | `quickback create empty my-app` |
42
+ ### B2B SaaS (Pro)
37
43
 
38
- These create the project structure with `quickback.config.ts` only — no `features/` directory. Run `quickback init` inside the project to scaffold your first feature.
44
+ | Template | Includes | Command |
45
+ |----------|----------|---------|
46
+ | `saas` | Multi-tenant + **R2 file storage** + **outbound webhooks** + split databases + realtime + named views | `quickback create saas my-app` |
39
47
 
40
48
  ## What Each Template Includes
41
49
 
42
- Full-featured and starter templates scaffold a complete project with:
50
+ The `cloudflare`, `todos`, `blog`, and `saas` templates all scaffold:
43
51
 
44
52
  - **`quickback.config.ts`** — Pre-configured with the right providers
45
- - **`quickback/features/`** — Example feature(s) with security configuration
46
- - **Deployment scripts** — `npm run deploy` for Cloudflare, `npm start` for Bun
53
+ - **`quickback/features/`** — Feature definitions (empty for `cloudflare`; populated for `todos` / `blog` / `saas`)
54
+ - **Deployment scripts** — `npm run deploy` for Cloudflare via wrangler
47
55
 
48
- Empty templates include only:
56
+ The `empty` template includes only:
49
57
 
50
- - **`quickback.config.ts`** — Pre-configured with the right providers
51
- - **`package.json`** — Dependencies ready to install
58
+ - **`quickback.config.ts`**
59
+ - **`package.json`** — dependencies ready to install
52
60
 
53
61
  ## Choosing a Template
54
62
 
55
- ### Cloudflare (Recommended for Production)
63
+ ### Cloudflare bare scaffold
56
64
 
57
- Best for production deployments. Runs on Cloudflare's global edge network with zero cold starts. Includes D1 (SQLite at the edge), KV storage, and R2 file storage.
65
+ Best when you already know the conventions and want empty walls. Multi-tenant orgs are wired in; you add your own feature files.
58
66
 
59
- - Free tier available (Workers free plan)
60
- - Global edge deployment
61
- - Built-in KV, R2, Queues, Vectorize
62
- - Dual database mode (separate auth and features DBs)
67
+ ### Todos (recommended for newcomers)
63
68
 
64
- ### Blog (Single-Tenant CMS)
69
+ 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.
65
70
 
66
- Best for personal sites, blogs, or any app with a single tenant. Uses [single-tenant mode](/compiler/config/single-tenant) — no organizations, roles come from `user.role`.
71
+ ### Blog (single-tenant CMS)
72
+
73
+ Best for personal sites, blogs, or any app with a single tenant. Uses [single-tenant mode](/compiler/config/single-tenant) — no organizations, roles come from `user.role` via Better Auth's admin plugin.
67
74
 
68
75
  - Public JSON API for content
69
- - Admin-only editing via Better Auth admin plugin
76
+ - Admin-only editing
70
77
  - Pair with any frontend (Astro, Next.js, SvelteKit, etc.)
71
78
 
72
- ### Empty (Start from Scratch)
79
+ ### Empty
73
80
 
74
81
  Best when you know exactly what you want to build. Gets you the project structure and config without any opinionated features.
75
82
 
76
- - Config-only scaffolding
77
- - Cloudflare Workers + D1 runtime
78
- - Add features with `quickback init` or by hand
83
+ ### SaaS (Pro)
84
+
85
+ Best for production B2B work. Adds R2 file uploads, outbound webhooks (with retry/dedupe), split auth/features/webhooks databases, realtime broadcast, and named views.
79
86
 
80
87
  ## Template Aliases
81
88
 
82
89
  For convenience, templates have short aliases:
83
90
 
84
- | Alias | Template |
85
- |-------|----------|
86
- | `cf` | `betterauth-d1-cloudflare` |
91
+ | Alias | Full id |
92
+ |-------|---------|
93
+ | `cloudflare` / `cf` | `betterauth-d1-cloudflare` |
94
+ | `todos` | `todos-cloudflare` |
95
+ | `blog` | `blog-cloudflare` |
87
96
  | `saas` | `b2bsaas-cloudflare` |
88
- | `scaffold` | `empty-cloudflare` |
97
+ | `empty` / `scaffold` | `empty-cloudflare` |
98
+
99
+ ## After Scaffolding
89
100
 
90
- ## After Creating a Project
101
+ `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:
91
102
 
92
103
  ```bash
93
- # 1. Create the project
94
- quickback create cloudflare my-app
95
104
  cd my-app
96
-
97
- # 2. Log in to the compiler
98
- quickback login
99
-
100
- # 3. Compile your definitions
101
- quickback compile
102
-
103
- # 4. Run locally
105
+ quickback compile # prompts for login on first run; reuses session after
104
106
  npm run dev
105
107
  ```
106
108
 
@@ -4,6 +4,15 @@ Quickback is a **backend compiler**. Define your database schema and security ru
4
4
 
5
5
  ## Quick start
6
6
 
7
+ ```bash
8
+ mkdir my-app && cd my-app
9
+ npx @quickback-dev/cli start
10
+ ```
11
+
12
+ `start` is interactive — it asks for a template, scaffolds the project on disk, and only prompts for an account just before compiling. If you cancel at the login prompt the scaffold stays put; you can finish later with `quickback compile`.
13
+
14
+ Prefer scripting?
15
+
7
16
  ```bash
8
17
  npm install -g @quickback-dev/cli
9
18
  quickback create cloudflare my-app