@quickback-dev/cli 0.17.1 → 0.31.1

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.
Files changed (85) hide show
  1. package/dist/commands/compile.d.ts.map +1 -1
  2. package/dist/commands/compile.js +17 -1
  3. package/dist/commands/compile.js.map +1 -1
  4. package/dist/docs/content.d.ts.map +1 -1
  5. package/dist/docs/content.js +28 -63
  6. package/dist/docs/content.js.map +1 -1
  7. package/dist/index.js +1 -1
  8. package/dist/lib/api-client.d.ts +17 -0
  9. package/dist/lib/api-client.d.ts.map +1 -1
  10. package/dist/lib/api-client.js.map +1 -1
  11. package/dist/lib/file-loader.d.ts +24 -0
  12. package/dist/lib/file-loader.d.ts.map +1 -1
  13. package/dist/lib/file-loader.js +46 -0
  14. package/dist/lib/file-loader.js.map +1 -1
  15. package/dist/skill/docs/changelog.md +780 -1174
  16. package/dist/skill/docs/compiler/cloud-compiler/cli.md +54 -33
  17. package/dist/skill/docs/compiler/cloud-compiler/index.md +9 -9
  18. package/dist/skill/docs/compiler/config/domains.md +44 -10
  19. package/dist/skill/docs/compiler/config/output.md +1 -1
  20. package/dist/skill/docs/compiler/config/providers.md +6 -12
  21. package/dist/skill/docs/compiler/config/variables.md +0 -30
  22. package/dist/skill/docs/compiler/definitions/access.md +203 -1
  23. package/dist/skill/docs/compiler/definitions/actions.md +40 -7
  24. package/dist/skill/docs/compiler/definitions/schema.md +6 -10
  25. package/dist/skill/docs/compiler/getting-started/template-cloudflare.md +49 -54
  26. package/dist/skill/docs/compiler/getting-started/templates.md +58 -56
  27. package/dist/skill/docs/compiler/index.md +15 -34
  28. package/dist/skill/docs/compiler/targets/hono-api/cloudflare.md +1 -2
  29. package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +0 -1
  30. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +19 -0
  31. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +1 -1
  32. package/dist/skill/docs/compiler/targets/index.md +6 -34
  33. package/dist/skill/docs/index.md +11 -5
  34. package/dist/skill/docs/stack/account-ui/customization.md +2 -14
  35. package/dist/skill/docs/stack/account-ui/environment-variables.md +7 -1
  36. package/dist/skill/docs/stack/account-ui/features/avatars.md +2 -4
  37. package/dist/skill/docs/stack/account-ui/features/index.md +1 -1
  38. package/dist/skill/docs/stack/account-ui/features/organizations.md +31 -11
  39. package/dist/skill/docs/stack/account-ui/index.md +5 -43
  40. package/dist/skill/docs/stack/account-ui/with-quickback.md +2 -75
  41. package/dist/skill/docs/stack/auth/plugins/index.md +74 -0
  42. package/dist/skill/docs/stack/index.md +8 -4
  43. package/package.json +1 -1
  44. package/src/skill/docs/changelog.md +780 -1174
  45. package/src/skill/docs/compiler/cloud-compiler/cli.md +54 -33
  46. package/src/skill/docs/compiler/cloud-compiler/index.md +9 -9
  47. package/src/skill/docs/compiler/config/domains.md +44 -10
  48. package/src/skill/docs/compiler/config/output.md +1 -1
  49. package/src/skill/docs/compiler/config/providers.md +6 -12
  50. package/src/skill/docs/compiler/config/variables.md +0 -30
  51. package/src/skill/docs/compiler/definitions/access.md +203 -1
  52. package/src/skill/docs/compiler/definitions/actions.md +40 -7
  53. package/src/skill/docs/compiler/definitions/schema.md +6 -10
  54. package/src/skill/docs/compiler/getting-started/template-cloudflare.md +49 -54
  55. package/src/skill/docs/compiler/getting-started/templates.md +58 -56
  56. package/src/skill/docs/compiler/index.md +15 -34
  57. package/src/skill/docs/compiler/targets/hono-api/cloudflare.md +1 -2
  58. package/src/skill/docs/compiler/targets/hono-api/database/neon.md +0 -1
  59. package/src/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +19 -0
  60. package/src/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +1 -1
  61. package/src/skill/docs/compiler/targets/index.md +6 -34
  62. package/src/skill/docs/index.md +11 -5
  63. package/src/skill/docs/stack/account-ui/customization.md +2 -14
  64. package/src/skill/docs/stack/account-ui/environment-variables.md +7 -1
  65. package/src/skill/docs/stack/account-ui/features/avatars.md +2 -4
  66. package/src/skill/docs/stack/account-ui/features/index.md +1 -1
  67. package/src/skill/docs/stack/account-ui/features/organizations.md +31 -11
  68. package/src/skill/docs/stack/account-ui/index.md +5 -43
  69. package/src/skill/docs/stack/account-ui/with-quickback.md +2 -75
  70. package/src/skill/docs/stack/auth/plugins/index.md +74 -0
  71. package/src/skill/docs/stack/index.md +8 -4
  72. package/dist/skill/docs/compiler/targets/supabase-rls/index.md +0 -55
  73. package/dist/skill/docs/compiler/targets/supabase-rls/limitations.md +0 -48
  74. package/dist/skill/docs/compiler/targets/supabase-rls/mappings.md +0 -99
  75. package/dist/skill/docs/compiler/targets/supabase-rls/setup.md +0 -88
  76. package/dist/skill/docs/stack/account-ui/library-usage.md +0 -257
  77. package/dist/skill/docs/stack/account-ui/standalone.md +0 -149
  78. package/dist/skill/docs/stack/account-ui/worker.md +0 -362
  79. package/src/skill/docs/compiler/targets/supabase-rls/index.md +0 -55
  80. package/src/skill/docs/compiler/targets/supabase-rls/limitations.md +0 -48
  81. package/src/skill/docs/compiler/targets/supabase-rls/mappings.md +0 -99
  82. package/src/skill/docs/compiler/targets/supabase-rls/setup.md +0 -88
  83. package/src/skill/docs/stack/account-ui/library-usage.md +0 -257
  84. package/src/skill/docs/stack/account-ui/standalone.md +0 -149
  85. package/src/skill/docs/stack/account-ui/worker.md +0 -362
@@ -304,9 +304,9 @@ land in `success[]` masked the same way the single-record response is.
304
304
 
305
305
  | Provider | failFast | transactional | Behavior |
306
306
  |---|---|---|---|
307
- | postgres / supabase / neon / libsql / sqlite drivers | `true` | `true` | `db.transaction()` wraps the loop; any throw rolls back all writes |
307
+ | neon (Postgres via Hyperdrive) | `true` | `true` | `db.transaction()` wraps the loop; any throw rolls back all writes |
308
308
  | (any) | `false` | `false` | Independent per-record outcomes, partial success |
309
- | cloudflare-d1 | `true` | `false` | Fail-fast loop without rollback — earlier records stay committed |
309
+ | cloudflare-d1 | `true` | `false` | Fail-fast loop without rollback — earlier records stay committed (D1 has no `db.transaction`) |
310
310
 
311
311
  **Constraints:**
312
312
 
@@ -502,13 +502,46 @@ access: async (ctx, record) => {
502
502
  }
503
503
  ```
504
504
 
505
- ### Relationship-roles in actions (v1 limitation)
505
+ ### Relationship-roles in actions
506
506
 
507
- Relationship-roles declared under `authz.roles` (e.g. `guest: { via: 'guestOf' }`) are **not yet supported in action access blocks**. The compiler refuses to build with a clear error message because the binding semantics — which input field or which loaded record's column to check the relationship against — differ between record-actions and standalone-actions and require explicit declaration not yet wired in v1.
507
+ **v0.19+** — standalone actions now support relationship-roles in `access.roles` directly. Declare the relationship under `authz.relationships` with optional `loads` / `exposeAs` for ctx hydration, and reference the role by name on the action:
508
508
 
509
- The runtime evaluator fails closed on unrecognized relationship arms, so silent grants are impossible.
509
+ ```ts
510
+ // quickback.config.ts
511
+ authz: {
512
+ relationships: {
513
+ attendeeOf: {
514
+ from: 'guests',
515
+ subject: { column: 'userId', equals: 'ctx.userId' },
516
+ resource: { column: 'eventId' },
517
+ where: { status: 'confirmed' },
518
+ loads: 'events',
519
+ exposeAs: 'event',
520
+ },
521
+ },
522
+ roles: { attendee: { via: 'attendeeOf' } },
523
+ }
524
+
525
+ // features/chat/actions/getInbox.ts
526
+ export default defineAction({
527
+ path: '/chat/get-inbox',
528
+ input: z.object({ eventId: z.number().int().positive() }),
529
+ access: { roles: ['admin', 'member', 'attendee'] },
530
+ execute: async ({ db, ctx, input }) => {
531
+ // The resolver already verified attendance and loaded ctx.event.
532
+ // No hand-rolled `SELECT … FROM guests WHERE …` needed.
533
+ },
534
+ });
535
+ ```
536
+
537
+ The action's surface (path params + input fields) must expose the relationship's `resource.column`. At v0.19 a missing key emits a `[quickback:authz]` warning and skips resolver emission; at v0.20 it becomes a compile error. See [Access — standalone actions](/compiler/definitions/access#standalone-actions-surface-keys-and-loads--exposeas-v019) for the full mechanism.
538
+
539
+ **Record-based actions** are NOT yet supported — the runtime evaluator fail-closes (403) on relationship arms reached without an inline gate. Until inline emission for record-based actions lands, either:
540
+
541
+ - Set `firewall: { exception: true }` on the action and gate manually in `execute()`, OR
542
+ - Apply the relationship at the resource's firewall layer (worked example below).
510
543
 
511
- **Workaround**: gate the action on BA roles only and apply the relationship at the resource layer via a firewall `via:` predicate:
544
+ **Resource-layer workaround for record-based actions**: gate the action on BA roles only and apply the relationship at the resource layer via a firewall `via:` predicate:
512
545
 
513
546
  ```typescript
514
547
  // quickback.config.ts
@@ -543,7 +576,7 @@ actions: {
543
576
 
544
577
  This pattern composes cleanly: the firewall guarantees the caller has the relationship to the record being acted on; the action's access list keeps the role surface obvious.
545
578
 
546
- A future `actions.<name>.relationshipBindings` declaration is on the roadmap to remove this limitation. See [Access — relationship authorization](/compiler/definitions/access#relationship-based-authorization) for the full picture.
579
+ See [Access — relationship authorization](/compiler/definitions/access#relationship-based-authorization) for the full picture, including `loads` / `exposeAs` and the `firewall: { exception: true }` escape hatch.
547
580
 
548
581
  ## Scoped Database
549
582
 
@@ -95,7 +95,7 @@ A few mechanics to know:
95
95
 
96
96
  `q.url()` is `q.text()` plus `z.string().url()` at the validation edge, so `javascript:` / `data:` URIs and free-form strings are rejected before they ever land in storage or get rendered in the CMS.
97
97
 
98
- `q.id()` emits a plain text primary key. Actual ID assignment at insert time is driven by the provider's `generateId` setting — prefixed UUIDs for D1, cuid for libsql/bun-sqlite, `crypto.randomUUID()` for supabase, etc. This keeps q's output decoupled from any specific ID library.
98
+ `q.id()` emits a plain text primary key. Actual ID assignment at insert time is driven by the provider's `generateId` setting — prefixed UUIDs for D1, `crypto.randomUUID()` for Neon, etc. This keeps q's output decoupled from any specific ID library.
99
99
 
100
100
  ### q.scope() — tenant scope columns
101
101
 
@@ -123,10 +123,7 @@ ownerId: q.scope('owner', { source: 'ctx.userId' }),
123
123
 
124
124
  ### Naming Convention
125
125
 
126
- By default, `q` picks the SQL column name from the JS key using the target database's conventional casing:
127
-
128
- - **Postgres family (Supabase, Neon, D1)** → `snake_case` (`organizationId` → `organization_id`)
129
- - **SQLite family (bun-sqlite, better-sqlite3, libsql)** → `camelCase` (`organizationId` → `organizationId`)
126
+ By default, `q` picks the SQL column name from the JS key using the target database's conventional casing. Both `cloudflare-d1` and `neon` default to **`snake_case`** (`organizationId` → `organization_id`).
130
127
 
131
128
  You can override for any project by setting `namingConvention` on the database provider config:
132
129
 
@@ -135,10 +132,9 @@ You can override for any project by setting `namingConvention` on the database p
135
132
  export default {
136
133
  providers: {
137
134
  database: {
138
- name: 'bun-sqlite',
135
+ name: 'cloudflare-d1',
139
136
  config: {
140
- path: './data/app.db',
141
- namingConvention: 'snake_case', // force snake_case everywhere
137
+ namingConvention: 'camelCase', // keep JS-style names in the SQL
142
138
  },
143
139
  },
144
140
  },
@@ -661,7 +657,7 @@ export default defineConfig({
661
657
 
662
658
  Use the Drizzle dialect that matches your database provider:
663
659
 
664
- ### SQLite (D1, Turso, better-sqlite3)
660
+ ### SQLite (Cloudflare D1)
665
661
 
666
662
  ```typescript
667
663
  import { sqliteTable, text, integer } from 'drizzle-orm/sqlite-core';
@@ -675,7 +671,7 @@ export const jobs = sqliteTable('jobs', {
675
671
  });
676
672
  ```
677
673
 
678
- ### PostgreSQL (Supabase, Neon)
674
+ ### PostgreSQL (Neon)
679
675
 
680
676
  ```typescript
681
677
  import { pgTable, text, serial, jsonb, boolean } from 'drizzle-orm/pg-core';
@@ -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
 
@@ -1,62 +1,44 @@
1
1
  # Quickback Compiler
2
2
 
3
- The **Quickback Compiler** is the build tool at the center of Quickback. You write declarative definitions in TypeScript — schema, security rules, validation, custom actions — and the compiler emits production-ready output for your chosen target.
3
+ The **Quickback Compiler** is the build tool at the center of Quickback. You write declarative definitions in TypeScript — schema, security rules, validation, custom actions — and the compiler emits a production Hono application for the **Quickback Stack** on Cloudflare.
4
4
 
5
5
  ```
6
- defineTable() ─┐ ┌─► Hono API (Cloudflare D1 / Neon)
7
- ├─► quickback compile┤
8
- defineActions()─┘ └─► RLS policies (Supabase)
6
+ defineTable() ─┐
7
+ ├─► quickback compile ─► Hono API on Cloudflare
8
+ defineActions()─┘ (D1 or Neon)
9
9
  ```
10
10
 
11
- The same definitions, the same DSL — pick the target that fits where you're deploying.
12
-
13
11
  ## What the compiler does
14
12
 
15
13
  When you run `quickback compile`, it:
16
14
 
17
15
  1. **Reads your definitions** — every `defineTable()`, `defineActions()`, and `defineConfig()` in your project
18
16
  2. **Validates security** — firewall, access, guards, and masking are checked for consistency
19
- 3. **Generates target output** — Hono routes + middleware + types + OpenAPI + MCP, or RLS migrations + helper functions
17
+ 3. **Generates output** — Hono routes + middleware + types + OpenAPI spec + MCP server + security artifacts
20
18
  4. **Emits database migrations** — runs `drizzle-kit generate` for schema changes
21
19
 
22
20
  ```
23
21
  quickback/
24
- ├── quickback.config.ts # Compiler configuration (target + providers)
22
+ ├── quickback.config.ts # Compiler configuration (providers, options)
25
23
  └── features/
26
24
  └── jobs/
27
25
  ├── jobs.ts # defineTable(...)
28
26
  └── actions.ts # defineActions(...)
29
27
  ```
30
28
 
31
- ## Two compile targets
32
-
33
- ### [Quickback for Hono API](/compiler/targets/hono-api)
29
+ ## The target: Hono on Cloudflare
34
30
 
35
- Generates a complete Hono application: routes, middleware, types, OpenAPI spec, MCP server. Pair with **Cloudflare D1** for SQLite-at-the-edge or **Neon** for full PostgreSQL with database-level RLS.
31
+ [Quickback for Hono API](/compiler/targets/hono-api) generates a complete Hono application bundled into a Cloudflare Worker. Pair with **Cloudflare D1** for SQLite-at-the-edge or **Neon** for full PostgreSQL via Hyperdrive.
36
32
 
37
33
  ```typescript
38
34
  providers: {
39
35
  runtime: defineRuntime('cloudflare'),
40
- database: defineDatabase('cloudflare-d1'),
36
+ database: defineDatabase('cloudflare-d1'), // or 'neon'
41
37
  auth: defineAuth('better-auth'),
42
38
  }
43
39
  ```
44
40
 
45
- ### [Quickback for Supabase](/compiler/targets/supabase-rls)
46
-
47
- Generates PostgreSQL Row Level Security policies for Supabase. Keep Supabase Auth, Storage, and Realtime — Quickback adds the security layer beneath your existing app code.
48
-
49
- ```typescript
50
- providers: {
51
- runtime: defineRuntime('supabase'),
52
- database: defineDatabase('supabase'),
53
- auth: defineAuth('supabase-auth'),
54
- }
55
- ```
56
-
57
- ## The shared core
58
-
59
- Whichever target you pick, the **input language is the same**:
41
+ ## The DSL
60
42
 
61
43
  - **[Definitions](/compiler/definitions)** — Schema, Firewall, Access, Guards, Masking, Views, Actions
62
44
  - **[Configuration](/compiler/config)** — `quickback.config.ts`, providers, domains, bindings
@@ -73,13 +55,12 @@ You don't run the compiler binary locally — it runs as a hosted service:
73
55
 
74
56
  1. **Define resources** in `quickback/features/`
75
57
  2. **Compile** with `quickback compile`
76
- 3. **Apply migrations** for your provider
77
- 4. **Test locally** with `npm run dev`
78
- 5. **Deploy** with `npm run deploy` (Hono target) or `supabase db push` (Supabase target)
58
+ 3. **Apply migrations** with `wrangler d1 migrations apply`
59
+ 4. **Test locally** with `wrangler dev`
60
+ 5. **Deploy** with `wrangler deploy`
79
61
 
80
62
  ## Next steps
81
63
 
82
64
  - [Getting Started](/compiler/getting-started) — Create your first project
83
- - [Definitions](/compiler/definitions) — The shared DSL
84
- - [Quickback for Hono API](/compiler/targets/hono-api) — Compile to a Hono app
85
- - [Quickback for Supabase](/compiler/targets/supabase-rls) — Compile to RLS policies
65
+ - [Definitions](/compiler/definitions) — The DSL
66
+ - [Quickback for Hono API](/compiler/targets/hono-api) — Generated output reference
@@ -90,5 +90,4 @@ Your `wrangler.toml` needs these bindings:
90
90
 
91
91
  - [Cloudflare Template](/compiler/getting-started/template-cloudflare) — Step-by-step setup guide with full wrangler.toml configuration
92
92
  - [D1 Database](/compiler/targets/hono-api/database/d1) — D1 setup, multi-database pattern, and security architecture
93
- - [Neon Integration](/compiler/targets/hono-api/database/neon) — Alternative: PostgreSQL with RLS
94
- - [Supabase Integration](/compiler/targets/supabase-rls) — Alternative: Supabase with RLS
93
+ - [Neon Integration](/compiler/targets/hono-api/database/neon) — Alternative: PostgreSQL via Hyperdrive
@@ -141,4 +141,3 @@ src/
141
141
 
142
142
  - [D1](/compiler/targets/hono-api/database/d1) — SQLite at the edge
143
143
  - [Providers](/compiler/config/providers) — All database provider options
144
- - [Quickback for Supabase](/compiler/targets/supabase-rls) — A different Postgres+RLS path that uses Supabase Auth instead of Better Auth
@@ -99,6 +99,25 @@ All actions (both standalone and record-based) receive a **scoped `db`** instanc
99
99
  - Tables with `deletedAt` — soft delete filter (`WHERE deletedAt IS NULL`)
100
100
  - `INSERT` operations auto-inject `organizationId` and `ownerId` from context
101
101
 
102
+ #### `userId` vs `ownerId` on feature tables
103
+
104
+ Use `ownerId` (not `userId`) for the row-owner column on a feature table. The compiler:
105
+
106
+ - Auto-firewalls reads on `ownerId` (`WHERE ownerId = ctx.userId`).
107
+ - Auto-stamps `ownerId` on insert from `ctx.userId`.
108
+ - Treats a `userId` column on a feature table as **informational** — almost always "a user this row references" (member, contact, invitee), not "the row owner."
109
+
110
+ A `userId` column on a feature table emits a compile-time warning. To resolve it:
111
+
112
+ - **Rename to `ownerId`** if the column controls access (most common case).
113
+ - **Rename to `linkedUserId`** (or similar) if the column is informational — explicit naming prevents future confusion.
114
+ - **Declare explicit firewall** if `userId` really is the access column on that table:
115
+ ```ts
116
+ firewall: [{ field: 'userId', equals: 'ctx.userId' }]
117
+ ```
118
+
119
+ Better Auth's own internal tables (`session`, `account`, `member`, `passkey`, `subscriptions`) use `userId` by convention. Those are not feature tables and don't pass through the auto-firewall — the warning only fires on resources you define in your `quickback/` folder.
120
+
102
121
  ```typescript
103
122
  // Your handler receives a scoped db — no manual filtering needed
104
123
  execute: async ({ db, ctx, input }) => {
@@ -264,7 +264,7 @@ rollback.
264
264
 
265
265
  | Endpoint | Provider | `failFast` | `meta.transactional` | Behavior |
266
266
  |----------|----------|-----------|----------------------|----------|
267
- | `PATCH /batch` (update) | postgres / supabase / neon / libsql / better-sqlite3 / bun-sqlite | `true` | `true` | `db.transaction()` wraps the per-record loop. Any failure rolls back ALL writes in the batch. |
267
+ | `PATCH /batch` (update) | neon (Postgres via Hyperdrive) | `true` | `true` | `db.transaction()` wraps the per-record loop. Any failure rolls back ALL writes in the batch. |
268
268
  | `PATCH /batch` (update) | (any) | `false` | `false` | Per-record loop, partial success. Each record commits independently. |
269
269
  | `PATCH /batch` (update) | cloudflare-d1 | `true` | `false` | Fail-fast loop without rollback — D1 has no `db.transaction`. Records before the failure stay committed. |
270
270
  | `PUT /batch` (upsert) | tx-supporting | `true` | `true` | Bulk insert + per-record update share one transaction. Any failure rolls back both. |