@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.
- package/dist/commands/compile.d.ts.map +1 -1
- package/dist/commands/compile.js +17 -1
- package/dist/commands/compile.js.map +1 -1
- package/dist/docs/content.d.ts.map +1 -1
- package/dist/docs/content.js +28 -63
- package/dist/docs/content.js.map +1 -1
- package/dist/index.js +1 -1
- package/dist/lib/api-client.d.ts +17 -0
- package/dist/lib/api-client.d.ts.map +1 -1
- package/dist/lib/api-client.js.map +1 -1
- package/dist/lib/file-loader.d.ts +24 -0
- package/dist/lib/file-loader.d.ts.map +1 -1
- package/dist/lib/file-loader.js +46 -0
- package/dist/lib/file-loader.js.map +1 -1
- package/dist/skill/docs/changelog.md +780 -1174
- package/dist/skill/docs/compiler/cloud-compiler/cli.md +54 -33
- package/dist/skill/docs/compiler/cloud-compiler/index.md +9 -9
- package/dist/skill/docs/compiler/config/domains.md +44 -10
- package/dist/skill/docs/compiler/config/output.md +1 -1
- package/dist/skill/docs/compiler/config/providers.md +6 -12
- package/dist/skill/docs/compiler/config/variables.md +0 -30
- package/dist/skill/docs/compiler/definitions/access.md +203 -1
- package/dist/skill/docs/compiler/definitions/actions.md +40 -7
- package/dist/skill/docs/compiler/definitions/schema.md +6 -10
- package/dist/skill/docs/compiler/getting-started/template-cloudflare.md +49 -54
- package/dist/skill/docs/compiler/getting-started/templates.md +58 -56
- package/dist/skill/docs/compiler/index.md +15 -34
- package/dist/skill/docs/compiler/targets/hono-api/cloudflare.md +1 -2
- package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +0 -1
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +19 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +1 -1
- package/dist/skill/docs/compiler/targets/index.md +6 -34
- package/dist/skill/docs/index.md +11 -5
- package/dist/skill/docs/stack/account-ui/customization.md +2 -14
- package/dist/skill/docs/stack/account-ui/environment-variables.md +7 -1
- package/dist/skill/docs/stack/account-ui/features/avatars.md +2 -4
- package/dist/skill/docs/stack/account-ui/features/index.md +1 -1
- package/dist/skill/docs/stack/account-ui/features/organizations.md +31 -11
- package/dist/skill/docs/stack/account-ui/index.md +5 -43
- package/dist/skill/docs/stack/account-ui/with-quickback.md +2 -75
- package/dist/skill/docs/stack/auth/plugins/index.md +74 -0
- package/dist/skill/docs/stack/index.md +8 -4
- package/package.json +1 -1
- package/src/skill/docs/changelog.md +780 -1174
- package/src/skill/docs/compiler/cloud-compiler/cli.md +54 -33
- package/src/skill/docs/compiler/cloud-compiler/index.md +9 -9
- package/src/skill/docs/compiler/config/domains.md +44 -10
- package/src/skill/docs/compiler/config/output.md +1 -1
- package/src/skill/docs/compiler/config/providers.md +6 -12
- package/src/skill/docs/compiler/config/variables.md +0 -30
- package/src/skill/docs/compiler/definitions/access.md +203 -1
- package/src/skill/docs/compiler/definitions/actions.md +40 -7
- package/src/skill/docs/compiler/definitions/schema.md +6 -10
- package/src/skill/docs/compiler/getting-started/template-cloudflare.md +49 -54
- package/src/skill/docs/compiler/getting-started/templates.md +58 -56
- package/src/skill/docs/compiler/index.md +15 -34
- package/src/skill/docs/compiler/targets/hono-api/cloudflare.md +1 -2
- package/src/skill/docs/compiler/targets/hono-api/database/neon.md +0 -1
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +19 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +1 -1
- package/src/skill/docs/compiler/targets/index.md +6 -34
- package/src/skill/docs/index.md +11 -5
- package/src/skill/docs/stack/account-ui/customization.md +2 -14
- package/src/skill/docs/stack/account-ui/environment-variables.md +7 -1
- package/src/skill/docs/stack/account-ui/features/avatars.md +2 -4
- package/src/skill/docs/stack/account-ui/features/index.md +1 -1
- package/src/skill/docs/stack/account-ui/features/organizations.md +31 -11
- package/src/skill/docs/stack/account-ui/index.md +5 -43
- package/src/skill/docs/stack/account-ui/with-quickback.md +2 -75
- package/src/skill/docs/stack/auth/plugins/index.md +74 -0
- package/src/skill/docs/stack/index.md +8 -4
- package/dist/skill/docs/compiler/targets/supabase-rls/index.md +0 -55
- package/dist/skill/docs/compiler/targets/supabase-rls/limitations.md +0 -48
- package/dist/skill/docs/compiler/targets/supabase-rls/mappings.md +0 -99
- package/dist/skill/docs/compiler/targets/supabase-rls/setup.md +0 -88
- package/dist/skill/docs/stack/account-ui/library-usage.md +0 -257
- package/dist/skill/docs/stack/account-ui/standalone.md +0 -149
- package/dist/skill/docs/stack/account-ui/worker.md +0 -362
- package/src/skill/docs/compiler/targets/supabase-rls/index.md +0 -55
- package/src/skill/docs/compiler/targets/supabase-rls/limitations.md +0 -48
- package/src/skill/docs/compiler/targets/supabase-rls/mappings.md +0 -99
- package/src/skill/docs/compiler/targets/supabase-rls/setup.md +0 -88
- package/src/skill/docs/stack/account-ui/library-usage.md +0 -257
- package/src/skill/docs/stack/account-ui/standalone.md +0 -149
- 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
|
-
|
|
|
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
|
|
505
|
+
### Relationship-roles in actions
|
|
506
506
|
|
|
507
|
-
|
|
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
|
-
|
|
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
|
-
**
|
|
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
|
-
|
|
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,
|
|
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: '
|
|
135
|
+
name: 'cloudflare-d1',
|
|
139
136
|
config: {
|
|
140
|
-
|
|
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
|
|
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 (
|
|
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
|
-
|
|
9
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
37
|
-
|
|
38
|
-
export default defineConfig({
|
|
43
|
+
export default {
|
|
39
44
|
name: "my-app",
|
|
40
45
|
template: "hono",
|
|
41
|
-
features:
|
|
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
|
-
###
|
|
65
|
+
### Adding your first feature
|
|
54
66
|
|
|
55
|
-
|
|
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
|
-
|
|
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
|
|
74
|
+
export const posts = sqliteTable("posts", {
|
|
62
75
|
id: text("id").primaryKey(),
|
|
63
76
|
title: text("title").notNull(),
|
|
64
|
-
|
|
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
|
-
|
|
79
|
+
userId: text("user_id").notNull(),
|
|
70
80
|
});
|
|
71
81
|
|
|
72
|
-
export default defineTable(
|
|
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", "
|
|
79
|
-
updatable: ["title", "
|
|
80
|
-
immutable: ["id", "organizationId", "
|
|
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
|
-
|
|
90
|
-
},
|
|
91
|
-
|
|
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.
|
|
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
|
|
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
|
-
###
|
|
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
|
-
###
|
|
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
|
-
###
|
|
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
|
-
###
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
###
|
|
26
|
+
### Single-tenant starter (free)
|
|
17
27
|
|
|
18
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
36
|
+
| Template | Includes | Command |
|
|
37
|
+
|----------|----------|---------|
|
|
38
|
+
| `empty` | `quickback.config.ts` only — no example features | `quickback create empty my-app` |
|
|
31
39
|
|
|
32
|
-
|
|
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
|
-
|
|
35
|
-
|----------|---------|----------|---------|
|
|
36
|
-
| `empty` | Cloudflare Workers | D1 | `quickback create empty my-app` |
|
|
42
|
+
### B2B SaaS (Pro)
|
|
37
43
|
|
|
38
|
-
|
|
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
|
-
|
|
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/`** —
|
|
46
|
-
- **Deployment scripts** — `npm run deploy` for Cloudflare
|
|
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
|
-
|
|
56
|
+
The `empty` template includes only:
|
|
49
57
|
|
|
50
|
-
- **`quickback.config.ts`**
|
|
51
|
-
- **`package.json`** —
|
|
58
|
+
- **`quickback.config.ts`**
|
|
59
|
+
- **`package.json`** — dependencies ready to install
|
|
52
60
|
|
|
53
61
|
## Choosing a Template
|
|
54
62
|
|
|
55
|
-
### Cloudflare
|
|
63
|
+
### Cloudflare bare scaffold
|
|
56
64
|
|
|
57
|
-
Best
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
76
|
+
- Admin-only editing
|
|
70
77
|
- Pair with any frontend (Astro, Next.js, SvelteKit, etc.)
|
|
71
78
|
|
|
72
|
-
### Empty
|
|
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
|
-
|
|
77
|
-
|
|
78
|
-
|
|
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 |
|
|
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
|
-
|
|
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
|
|
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() ─┐
|
|
7
|
-
├─► quickback compile
|
|
8
|
-
defineActions()─┘
|
|
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
|
|
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 (
|
|
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
|
-
##
|
|
32
|
-
|
|
33
|
-
### [Quickback for Hono API](/compiler/targets/hono-api)
|
|
29
|
+
## The target: Hono on Cloudflare
|
|
34
30
|
|
|
35
|
-
|
|
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
|
-
|
|
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**
|
|
77
|
-
4. **Test locally** with `
|
|
78
|
-
5. **Deploy** with `
|
|
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
|
|
84
|
-
- [Quickback for Hono API](/compiler/targets/hono-api) —
|
|
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
|
|
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) |
|
|
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. |
|