@quickback-dev/cli 0.16.5 → 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.
- package/README.md +7 -3
- package/dist/commands/compile.d.ts.map +1 -1
- package/dist/commands/compile.js +12 -48
- package/dist/commands/compile.js.map +1 -1
- package/dist/commands/create.d.ts +20 -0
- package/dist/commands/create.d.ts.map +1 -1
- package/dist/commands/create.js +216 -151
- package/dist/commands/create.js.map +1 -1
- package/dist/commands/login.d.ts +4 -2
- package/dist/commands/login.d.ts.map +1 -1
- package/dist/commands/login.js +25 -17
- package/dist/commands/login.js.map +1 -1
- package/dist/commands/start.d.ts +20 -0
- package/dist/commands/start.d.ts.map +1 -0
- package/dist/commands/start.js +163 -0
- package/dist/commands/start.js.map +1 -0
- package/dist/commands/whoami.d.ts.map +1 -1
- package/dist/commands/whoami.js +5 -4
- package/dist/commands/whoami.js.map +1 -1
- package/dist/docs/content.js +42 -42
- package/dist/docs/content.js.map +1 -1
- package/dist/index.js +27 -10
- package/dist/index.js.map +1 -1
- package/dist/lib/api-client.js +1 -1
- package/dist/lib/api-client.js.map +1 -1
- package/dist/lib/api-client.test.js +15 -0
- package/dist/lib/api-client.test.js.map +1 -1
- package/dist/lib/auth.d.ts +39 -3
- package/dist/lib/auth.d.ts.map +1 -1
- package/dist/lib/auth.js +57 -3
- package/dist/lib/auth.js.map +1 -1
- package/dist/lib/drizzle-meta-routing.test.js +16 -3
- package/dist/lib/drizzle-meta-routing.test.js.map +1 -1
- package/dist/lib/file-loader.d.ts +6 -4
- package/dist/lib/file-loader.d.ts.map +1 -1
- package/dist/lib/file-loader.js +30 -27
- package/dist/lib/file-loader.js.map +1 -1
- package/dist/lib/file-loader.test.js +16 -7
- package/dist/lib/file-loader.test.js.map +1 -1
- package/dist/skill/docs/changelog.md +429 -1100
- 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/providers.md +87 -0
- package/dist/skill/docs/compiler/config/single-tenant.md +5 -11
- package/dist/skill/docs/compiler/definitions/access.md +43 -57
- package/dist/skill/docs/compiler/definitions/feature.md +7 -11
- package/dist/skill/docs/compiler/definitions/firewall.md +2 -4
- package/dist/skill/docs/compiler/definitions/guards.md +16 -18
- package/dist/skill/docs/compiler/definitions/index.md +10 -14
- package/dist/skill/docs/compiler/definitions/masking.md +6 -6
- package/dist/skill/docs/compiler/definitions/read.md +6 -11
- package/dist/skill/docs/compiler/definitions/schema.md +18 -18
- package/dist/skill/docs/compiler/definitions/views.md +3 -5
- package/dist/skill/docs/compiler/getting-started/full-example.md +6 -8
- package/dist/skill/docs/compiler/getting-started/hand-crafted.md +3 -5
- package/dist/skill/docs/compiler/getting-started/index.md +23 -20
- package/dist/skill/docs/compiler/getting-started/patterns.md +19 -31
- package/dist/skill/docs/compiler/getting-started/template-blog.md +6 -10
- package/dist/skill/docs/compiler/getting-started/template-cloudflare.md +49 -56
- package/dist/skill/docs/compiler/getting-started/template-empty.md +3 -5
- package/dist/skill/docs/compiler/getting-started/templates.md +58 -56
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +29 -23
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +12 -14
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +5 -2
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +5 -7
- package/dist/skill/docs/compiler/troubleshooting.md +10 -0
- package/dist/skill/docs/index.md +9 -0
- package/dist/skill/docs/stack/auth/security.md +69 -0
- package/dist/skill/docs/stack/cms/actions.md +28 -0
- package/dist/skill/docs/stack/cms/connecting.md +2 -2
- package/dist/skill/docs/stack/cms/index.md +2 -2
- package/dist/skill/docs/stack/cms/record-layouts.md +19 -19
- package/dist/skill/docs/stack/cms/schema-format.md +33 -3
- package/dist/skill/docs/stack/cms/schema-registry.md +22 -2
- package/dist/skill/docs/stack/cms/security.md +10 -12
- package/dist/skill/docs/stack/cms/table-views.md +1 -1
- package/dist/skill/docs/stack/index.md +8 -4
- package/dist/skill/docs/stack/realtime/durable-objects.md +46 -5
- package/dist/skill/docs/stack/realtime/index.md +20 -3
- package/dist/skill/docs/stack/realtime/using-realtime.md +8 -6
- package/dist/skill/docs/stack/vector/embeddings.md +7 -6
- package/package.json +1 -1
- package/src/skill/docs/changelog.md +486 -1097
- 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 +87 -0
- package/src/skill/docs/compiler/config/single-tenant.md +5 -11
- package/src/skill/docs/compiler/definitions/access.md +43 -57
- package/src/skill/docs/compiler/definitions/feature.md +7 -11
- package/src/skill/docs/compiler/definitions/firewall.md +2 -4
- package/src/skill/docs/compiler/definitions/guards.md +16 -18
- package/src/skill/docs/compiler/definitions/index.md +10 -14
- package/src/skill/docs/compiler/definitions/masking.md +6 -6
- package/src/skill/docs/compiler/definitions/read.md +6 -11
- package/src/skill/docs/compiler/definitions/schema.md +18 -18
- package/src/skill/docs/compiler/definitions/views.md +3 -5
- package/src/skill/docs/compiler/getting-started/full-example.md +6 -8
- package/src/skill/docs/compiler/getting-started/hand-crafted.md +3 -5
- package/src/skill/docs/compiler/getting-started/index.md +23 -20
- package/src/skill/docs/compiler/getting-started/patterns.md +19 -31
- package/src/skill/docs/compiler/getting-started/template-blog.md +6 -10
- package/src/skill/docs/compiler/getting-started/template-cloudflare.md +49 -56
- package/src/skill/docs/compiler/getting-started/template-empty.md +3 -5
- package/src/skill/docs/compiler/getting-started/templates.md +58 -56
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +29 -23
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +12 -14
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +5 -2
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +5 -7
- package/src/skill/docs/compiler/troubleshooting.md +10 -0
- package/src/skill/docs/index.md +9 -0
- package/src/skill/docs/stack/auth/plugins/index.md +74 -0
- package/src/skill/docs/stack/auth/security.md +69 -0
- package/src/skill/docs/stack/cms/actions.md +28 -0
- package/src/skill/docs/stack/cms/connecting.md +2 -2
- package/src/skill/docs/stack/cms/index.md +2 -2
- package/src/skill/docs/stack/cms/record-layouts.md +19 -19
- package/src/skill/docs/stack/cms/schema-format.md +33 -3
- package/src/skill/docs/stack/cms/schema-registry.md +22 -2
- package/src/skill/docs/stack/cms/security.md +10 -12
- package/src/skill/docs/stack/cms/table-views.md +1 -1
- package/src/skill/docs/stack/index.md +8 -4
- package/src/skill/docs/stack/realtime/durable-objects.md +46 -5
- package/src/skill/docs/stack/realtime/index.md +20 -3
- package/src/skill/docs/stack/realtime/using-realtime.md +8 -6
- package/src/skill/docs/stack/vector/embeddings.md +7 -6
|
@@ -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,92 +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
|
-
},
|
|
87
|
-
},
|
|
88
|
-
read: {
|
|
89
|
-
access: { roles: ["owner", "admin", "member"] },
|
|
90
|
-
},
|
|
91
|
-
crud: {
|
|
92
|
-
create: { access: { roles: ["owner", "admin", "member"] } },
|
|
93
|
-
update: { access: { roles: ["owner", "admin", "member"] } },
|
|
94
|
-
delete: { access: { roles: ["owner", "admin"] }, mode: "soft" },
|
|
85
|
+
createable: ["title", "body"],
|
|
86
|
+
updatable: ["title", "body"],
|
|
87
|
+
immutable: ["id", "organizationId", "userId"],
|
|
95
88
|
},
|
|
89
|
+
read: { access: { roles: ["member+"] } },
|
|
90
|
+
create: { access: { roles: ["member+"] } },
|
|
91
|
+
update: { access: { roles: ["member+"] } },
|
|
92
|
+
delete: { access: { roles: ["admin+"] }, mode: "soft" },
|
|
96
93
|
});
|
|
97
94
|
```
|
|
98
95
|
|
|
99
96
|
## Setup Steps
|
|
100
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
|
+
|
|
101
100
|
### 1. Install Dependencies
|
|
102
101
|
|
|
103
102
|
```bash
|
|
104
103
|
npm install
|
|
105
104
|
```
|
|
106
105
|
|
|
107
|
-
### 2.
|
|
108
|
-
|
|
109
|
-
```bash
|
|
110
|
-
quickback login
|
|
111
|
-
```
|
|
112
|
-
|
|
113
|
-
### 3. Compile Your Definitions
|
|
106
|
+
### 2. Compile Your Definitions
|
|
114
107
|
|
|
115
108
|
```bash
|
|
116
109
|
quickback compile
|
|
117
110
|
```
|
|
118
111
|
|
|
119
|
-
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.
|
|
120
113
|
|
|
121
|
-
###
|
|
114
|
+
### 3. Create D1 Databases
|
|
122
115
|
|
|
123
116
|
The Cloudflare template uses **dual database mode** by default — separate databases for auth and application data.
|
|
124
117
|
|
|
@@ -144,7 +137,7 @@ database_name = "my-app-features"
|
|
|
144
137
|
database_id = "paste-features-id-here"
|
|
145
138
|
```
|
|
146
139
|
|
|
147
|
-
###
|
|
140
|
+
### 4. Run Migrations (Local)
|
|
148
141
|
|
|
149
142
|
```bash
|
|
150
143
|
npm run db:migrate:local
|
|
@@ -152,7 +145,7 @@ npm run db:migrate:local
|
|
|
152
145
|
|
|
153
146
|
This applies migrations to both databases locally.
|
|
154
147
|
|
|
155
|
-
###
|
|
148
|
+
### 5. Start Development Server
|
|
156
149
|
|
|
157
150
|
```bash
|
|
158
151
|
npm run dev
|
|
@@ -84,11 +84,9 @@ export default defineTable(products, {
|
|
|
84
84
|
read: {
|
|
85
85
|
access: { roles: ["member+"] },
|
|
86
86
|
},
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
delete: { access: { roles: ["admin+"] }, mode: "soft" },
|
|
91
|
-
},
|
|
87
|
+
create: { access: { roles: ["member+"] } },
|
|
88
|
+
update: { access: { roles: ["member+"] } },
|
|
89
|
+
delete: { access: { roles: ["admin+"] }, mode: "soft" },
|
|
92
90
|
});
|
|
93
91
|
```
|
|
94
92
|
|
|
@@ -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,22 +1,22 @@
|
|
|
1
1
|
# Batch Operations
|
|
2
2
|
|
|
3
|
-
Batch operations let you create, update, or delete multiple records in a single request. They are **auto-enabled** when the corresponding
|
|
3
|
+
Batch operations let you create, update, upsert, or delete multiple records in a single request. They are **auto-enabled** when the corresponding write operation exists in your definition.
|
|
4
4
|
|
|
5
5
|
## Available Endpoints
|
|
6
6
|
|
|
7
7
|
| Endpoint | Method | Auto-enabled When |
|
|
8
8
|
|----------|--------|-------------------|
|
|
9
|
-
| `/{resource}/batch` | `POST` | `
|
|
10
|
-
| `/{resource}/batch` | `PATCH` | `
|
|
11
|
-
| `/{resource}/batch` | `DELETE` | `
|
|
12
|
-
| `/{resource}/batch` | `PUT` | `
|
|
9
|
+
| `/{resource}/batch` | `POST` | `create` exists |
|
|
10
|
+
| `/{resource}/batch` | `PATCH` | `update` exists |
|
|
11
|
+
| `/{resource}/batch` | `DELETE` | `delete` exists |
|
|
12
|
+
| `/{resource}/batch` | `PUT` | `upsert` exists |
|
|
13
13
|
|
|
14
14
|
To disable a batch operation, set it to `false` in your definition:
|
|
15
15
|
|
|
16
16
|
```typescript
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
17
|
+
create: {
|
|
18
|
+
access: { roles: ['hiring-manager'] },
|
|
19
|
+
batch: false, // Disable batch create
|
|
20
20
|
}
|
|
21
21
|
```
|
|
22
22
|
|
|
@@ -309,33 +309,39 @@ The default maximum batch size is **100 records**. Requests exceeding the limit
|
|
|
309
309
|
|
|
310
310
|
## Configuration
|
|
311
311
|
|
|
312
|
-
Batch operations inherit access control from their corresponding
|
|
312
|
+
Batch operations inherit access control from their corresponding write operation. You can override per-batch settings:
|
|
313
313
|
|
|
314
314
|
```typescript
|
|
315
315
|
export default defineTable(applications, {
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
batchCreate: {
|
|
323
|
-
access: { roles: ['hiring-manager'] }, // More restrictive than single create
|
|
324
|
-
maxBatchSize: 50, // Default: 100
|
|
325
|
-
allowFailFast: true, // Default: true
|
|
316
|
+
create: {
|
|
317
|
+
access: { roles: ['hiring-manager', 'recruiter'] },
|
|
318
|
+
batch: {
|
|
319
|
+
access: { roles: ['hiring-manager'] }, // More restrictive than single create
|
|
320
|
+
maxBatchSize: 50, // Default: 100
|
|
321
|
+
allowFailFast: true, // Default: true
|
|
326
322
|
},
|
|
327
|
-
|
|
323
|
+
},
|
|
324
|
+
update: {
|
|
325
|
+
access: { roles: ['hiring-manager', 'recruiter'] },
|
|
326
|
+
batch: {
|
|
328
327
|
maxBatchSize: 100,
|
|
329
328
|
allowFailFast: true,
|
|
330
329
|
},
|
|
331
|
-
|
|
330
|
+
},
|
|
331
|
+
delete: {
|
|
332
|
+
access: { roles: ['hiring-manager'] },
|
|
333
|
+
mode: 'soft',
|
|
334
|
+
batch: {
|
|
332
335
|
access: { roles: ['hiring-manager'] },
|
|
333
336
|
maxBatchSize: 100,
|
|
334
337
|
allowFailFast: true,
|
|
335
338
|
},
|
|
339
|
+
},
|
|
336
340
|
|
|
337
|
-
|
|
338
|
-
|
|
341
|
+
// Disable only batch upsert
|
|
342
|
+
upsert: {
|
|
343
|
+
access: { roles: ['hiring-manager'] },
|
|
344
|
+
batch: false,
|
|
339
345
|
},
|
|
340
346
|
});
|
|
341
347
|
```
|
|
@@ -580,30 +580,28 @@ All batch operation errors include:
|
|
|
580
580
|
|
|
581
581
|
#### Configuration
|
|
582
582
|
|
|
583
|
-
Batch operations are **auto-enabled** when corresponding
|
|
583
|
+
Batch operations are **auto-enabled** when corresponding write operations exist:
|
|
584
584
|
|
|
585
585
|
```typescript
|
|
586
586
|
// Auto-enabled - no configuration needed
|
|
587
|
-
|
|
588
|
-
|
|
589
|
-
|
|
590
|
-
// batchCreate and batchUpdate automatically available
|
|
591
|
-
}
|
|
587
|
+
create: { access: { roles: ['recruiter'] } },
|
|
588
|
+
update: { access: { roles: ['recruiter'] } }
|
|
589
|
+
// create.batch and update.batch automatically available
|
|
592
590
|
|
|
593
591
|
// Customize batch operations
|
|
594
|
-
|
|
595
|
-
|
|
596
|
-
|
|
592
|
+
create: {
|
|
593
|
+
access: { roles: ['recruiter'] },
|
|
594
|
+
batch: {
|
|
597
595
|
access: { roles: ['hiring-manager'] }, // Different access rules
|
|
598
|
-
maxBatchSize: 50,
|
|
599
|
-
allowFailFast: false
|
|
596
|
+
maxBatchSize: 50, // Lower limit
|
|
597
|
+
allowFailFast: false // Disable failFast mode
|
|
600
598
|
}
|
|
601
599
|
}
|
|
602
600
|
|
|
603
601
|
// Disable batch operations
|
|
604
|
-
|
|
605
|
-
|
|
606
|
-
|
|
602
|
+
create: {
|
|
603
|
+
access: { roles: ['recruiter'] },
|
|
604
|
+
batch: false // Explicitly disable
|
|
607
605
|
}
|
|
608
606
|
```
|
|
609
607
|
|
|
@@ -140,18 +140,21 @@ const { data, error } = await client.GET('/api/v1/jobs', { params: { query: { li
|
|
|
140
140
|
| `true` (default) | Write `api-types.gen.ts` to the project root |
|
|
141
141
|
| `false` | Don't emit the types file |
|
|
142
142
|
| `"src/lib/api-types.ts"` | Custom output path (relative to project root) |
|
|
143
|
+
| `["api-types.gen.ts", "apps/web/src/lib/api-types.gen.ts"]` | Write the same generated types to multiple paths in one compile |
|
|
143
144
|
|
|
144
145
|
```typescript
|
|
145
146
|
// quickback.config.ts
|
|
146
147
|
export default defineConfig({
|
|
147
148
|
// ...
|
|
148
149
|
openapi: {
|
|
149
|
-
types: 'src/lib/api-types.gen.ts',
|
|
150
|
+
types: ['api-types.gen.ts', 'apps/web/src/lib/api-types.gen.ts'],
|
|
150
151
|
},
|
|
151
152
|
});
|
|
152
153
|
```
|
|
153
154
|
|
|
154
|
-
The file is generated by piping the in-memory spec through [openapi-typescript](https://github.com/openapi-ts/openapi-typescript) — you can keep running it manually if you want a different output path or version, but for the typical case there's nothing to wire up. Skipped automatically when `openapi.generate` is `false`.
|
|
155
|
+
The file is generated by piping the in-memory spec through [openapi-typescript](https://github.com/openapi-ts/openapi-typescript) — you can keep running it manually if you want a different output path or version, but for the typical case there's nothing to wire up. If your API project and SPA live in the same repo, prefer multiple `openapi.types` outputs over a second manual `codegen:api` step so one `quickback compile` keeps both copies in sync. Skipped automatically when `openapi.generate` is `false`.
|
|
156
|
+
|
|
157
|
+
The bundled Quickback CMS and Account SPAs do not import `api-types.gen.ts`. CMS is driven by `schema-registry.json`, and Account uses Better Auth plus small hand-written fetch helpers. Use `openapi.types` for your own colocated client apps.
|
|
155
158
|
|
|
156
159
|
### External viewer
|
|
157
160
|
|
|
@@ -42,15 +42,13 @@ GET /api/v1/jobs?department.in=Engineering,Design,Product
|
|
|
42
42
|
GET /api/v1/jobs?limit=25&offset=50
|
|
43
43
|
```
|
|
44
44
|
|
|
45
|
-
The default `limit` can be configured per-resource in your definition:
|
|
45
|
+
The default `limit` can be configured per-resource in your `read` definition:
|
|
46
46
|
|
|
47
47
|
```typescript
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
maxPageSize: 100, // Maximum allowed limit
|
|
53
|
-
},
|
|
48
|
+
read: {
|
|
49
|
+
access: { roles: ["recruiter"] },
|
|
50
|
+
pageSize: 25, // Default limit
|
|
51
|
+
maxPageSize: 100, // Maximum allowed limit
|
|
54
52
|
},
|
|
55
53
|
```
|
|
56
54
|
|
|
@@ -65,6 +65,16 @@ To clean up, you'd need to manually create a migration.
|
|
|
65
65
|
|
|
66
66
|
If compilation fails with `drizzle-kit requested interactive rename input`, add explicit rename hints in your config. See [Drizzle rename prompts](/compiler/cloud-compiler/troubleshooting#drizzle-rename-prompts-in-ciheadless-compile).
|
|
67
67
|
|
|
68
|
+
### Cloudflare D1 destructive migrations
|
|
69
|
+
|
|
70
|
+
Quickback now adds a D1-specific safety pass around Drizzle-generated migrations for the `cloudflare-d1` provider:
|
|
71
|
+
|
|
72
|
+
1. **Better Auth cleanup** for retired managed tables is stripped instead of shipped as raw `DROP TABLE` SQL.
|
|
73
|
+
2. **Drop-only cleanup migrations** are reordered child-first when foreign keys require it.
|
|
74
|
+
3. **All D1 migration directories** generated by the compiler are replayed against SQLite during compile, so a D1-breaking migration fails before deploy.
|
|
75
|
+
|
|
76
|
+
If `quickback compile` now fails with a D1 replay error, treat that as a real migration problem instead of a deploy-time surprise. The generated SQL needs manual intervention or a schema change that Drizzle can express more safely.
|
|
77
|
+
|
|
68
78
|
## Runtime Issues
|
|
69
79
|
|
|
70
80
|
### 401 on all requests
|
package/dist/skill/docs/index.md
CHANGED
|
@@ -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
|
|
@@ -138,6 +138,75 @@ rateLimit: {
|
|
|
138
138
|
|
|
139
139
|
---
|
|
140
140
|
|
|
141
|
+
## Bearer Tokens and Cookie Precedence
|
|
142
|
+
|
|
143
|
+
Quickback supports three bearer-token flavors alongside the standard browser session cookie:
|
|
144
|
+
|
|
145
|
+
| Credential | Used by | Resolved by |
|
|
146
|
+
|------------|---------|-------------|
|
|
147
|
+
| Session cookie | Browser SPAs (CMS, Account, your app) | Better Auth session lookup |
|
|
148
|
+
| Session-token bearer | API clients that grabbed `set-auth-token` | Better Auth `bearer` plugin |
|
|
149
|
+
| JWT bearer | API clients that hit `/api/v1/token` | In-worker JWT fast-path (no DB hit) |
|
|
150
|
+
| API-key bearer | Long-lived programmatic access | `apiKey` plugin / `x-api-key` / `?api_key=` |
|
|
151
|
+
|
|
152
|
+
These match Better Auth's own framing of bearer tokens as **an alternative to cookies, not a supplement** — a request uses one or the other.
|
|
153
|
+
|
|
154
|
+
### Precedence: bearer always wins
|
|
155
|
+
|
|
156
|
+
If a request carries both `Authorization` and `Cookie` headers, the bearer wins universally and the cookie is dropped before session resolution:
|
|
157
|
+
|
|
158
|
+
```
|
|
159
|
+
Request Resolved as
|
|
160
|
+
────────────────────────────────────── ─────────────
|
|
161
|
+
Cookie only cookie session
|
|
162
|
+
Authorization: Bearer <jwt> JWT claims
|
|
163
|
+
Authorization: Bearer <api-key> API-key owner
|
|
164
|
+
Authorization: Bearer <session-token> bearer session
|
|
165
|
+
Cookie + Authorization: Bearer <token> bearer wins, cookie ignored
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
This closes a class of silent-impersonation bugs where an ambient session cookie (multi-account browser tabs, a malicious extension, a misconfigured proxy injecting `Set-Cookie`) would otherwise override an explicit bearer credential. The decision is made before `getSession()` runs, so it applies to every code path in the auth middleware.
|
|
169
|
+
|
|
170
|
+
The api-key and JWT bearers also short-circuit before cookie resolution via dedicated fast-paths — they never touch the database for session lookup. Only session-token bearers reach `getSession()`, where Better Auth's `bearer` plugin resolves the `Authorization` header.
|
|
171
|
+
|
|
172
|
+
### `requireSignature: true` is the secure default
|
|
173
|
+
|
|
174
|
+
Quickback configures the Better Auth `bearer` plugin with `requireSignature: true` by default. This means:
|
|
175
|
+
|
|
176
|
+
- The session token Better Auth emits via the `set-auth-token` response header is **signed server-side** with `BETTER_AUTH_SECRET`.
|
|
177
|
+
- Unsigned bearer tokens are **rejected** at the plugin layer before any session lookup happens.
|
|
178
|
+
- A session token leaked via a proxy access log, a browser dev-tools panel, or a misrouted `Referer` header **cannot** be replayed as a bearer token by an attacker — they would need the signing secret to forge a valid signature.
|
|
179
|
+
|
|
180
|
+
Better Auth's own default for this option is `false`. Quickback overrides it on the secure side. JWT bearers and agent-auth bearers are independently signed and unaffected by this setting.
|
|
181
|
+
|
|
182
|
+
### Overriding the default
|
|
183
|
+
|
|
184
|
+
If a project genuinely needs unsigned bearers (e.g., a closed loopback service where signing is redundant), pass an explicit object:
|
|
185
|
+
|
|
186
|
+
```ts
|
|
187
|
+
auth: defineAuth("better-auth", {
|
|
188
|
+
plugins: {
|
|
189
|
+
bearer: { requireSignature: false },
|
|
190
|
+
},
|
|
191
|
+
})
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
User-supplied options merge on top of the secure default, so any other [`bearer` plugin option](https://better-auth.com/docs/plugins/bearer) can be passed the same way.
|
|
195
|
+
|
|
196
|
+
### Threat model and trade-offs
|
|
197
|
+
|
|
198
|
+
| Threat | Mitigation |
|
|
199
|
+
|--------|-----------|
|
|
200
|
+
| Stolen session-token bearer replayed against the API | `requireSignature: true` blocks unsigned values |
|
|
201
|
+
| Browser extension injects a victim's session cookie into an attacker's bearer-authed API call | Cookie stripped when `Authorization` is present |
|
|
202
|
+
| Multi-account user has cookies for two identities and uses bearer for the second | Bearer identity wins; no ambiguity in audit log |
|
|
203
|
+
| MCP / agent flow exposed to ambient browser cookies | `/mcp` and agent-auth routes are bearer-only (cookies dropped entirely, see [Agent Auth](/stack/auth/plugins/agent-auth)) |
|
|
204
|
+
| Alg-confusion / forged JWT (alg=none, HS384, RS256) | Verifier pins HS256; signature math rejects all non-matching algs uniformly with 401 |
|
|
205
|
+
|
|
206
|
+
For a deeper walkthrough of the bearer flow itself, see the upstream [Better Auth bearer plugin docs](https://better-auth.com/docs/plugins/bearer).
|
|
207
|
+
|
|
208
|
+
---
|
|
209
|
+
|
|
141
210
|
## Cross-Domain Authentication
|
|
142
211
|
|
|
143
212
|
For applications spanning multiple subdomains (e.g., `account.example.com`, `api.example.com`, `dashboard.example.com`), Quickback provides dual-layer security.
|