@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
|
@@ -5,33 +5,58 @@ The Quickback CLI is the fastest way to create, compile, and manage your backend
|
|
|
5
5
|
## Installation
|
|
6
6
|
|
|
7
7
|
```bash
|
|
8
|
+
# One-shot via npx — recommended for first run
|
|
9
|
+
npx @quickback-dev/cli start
|
|
10
|
+
|
|
11
|
+
# Or install globally for repeat use
|
|
8
12
|
npm install -g @quickback-dev/cli
|
|
9
13
|
```
|
|
10
14
|
|
|
11
15
|
## Commands
|
|
12
16
|
|
|
13
|
-
###
|
|
17
|
+
### Start a Project (interactive)
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
quickback start
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
Interactive onboarding designed for new users. No flags required.
|
|
24
|
+
|
|
25
|
+
- Prompts for a template (curated free-tier picker: `cloudflare`, `todos`, `blog`, `empty`)
|
|
26
|
+
- Prompts for a project name (defaults to the current directory's name if empty)
|
|
27
|
+
- Auto-detects whether to scaffold in-place or create a `./<name>/` subdirectory
|
|
28
|
+
- Defers login until just before the compile step — cancel at the auth prompt and the scaffold stays on disk, ready for `quickback compile` later
|
|
29
|
+
|
|
30
|
+
**Example:**
|
|
31
|
+
```bash
|
|
32
|
+
mkdir my-app && cd my-app
|
|
33
|
+
npx @quickback-dev/cli start
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
### Create a Project (scriptable)
|
|
14
37
|
|
|
15
38
|
```bash
|
|
16
39
|
quickback create <template> <name>
|
|
17
40
|
```
|
|
18
41
|
|
|
19
42
|
**Templates:**
|
|
20
|
-
- `cloudflare`
|
|
21
|
-
- `
|
|
22
|
-
- `blog`
|
|
23
|
-
- `empty`
|
|
24
|
-
- `
|
|
43
|
+
- `cloudflare` — Cloudflare Workers + D1 + Better Auth, bare scaffold (free)
|
|
44
|
+
- `todos` — Working todos example with masking + actions + a named view (free)
|
|
45
|
+
- `blog` — Single-tenant blog, PUBLIC reads, admin writes (free)
|
|
46
|
+
- `empty` — Cloudflare scaffold, no example features (free)
|
|
47
|
+
- `saas` — Full B2B SaaS: orgs, R2 file storage, webhooks, split databases, realtime (pro)
|
|
25
48
|
|
|
26
49
|
**Example:**
|
|
27
50
|
```bash
|
|
28
|
-
quickback create
|
|
51
|
+
quickback create todos my-app
|
|
29
52
|
```
|
|
30
53
|
|
|
31
54
|
This scaffolds a complete project with:
|
|
32
|
-
- `quickback.config.ts`
|
|
33
|
-
- `quickback/features/`
|
|
34
|
-
- Example
|
|
55
|
+
- `quickback.config.ts` — Project configuration
|
|
56
|
+
- `quickback/features/` — Your table definitions
|
|
57
|
+
- Example feature with full security configuration (for `todos` / `blog` / `saas`)
|
|
58
|
+
|
|
59
|
+
See the [Templates](/compiler/getting-started/templates) page for a deeper guide on choosing between them.
|
|
35
60
|
|
|
36
61
|
### Compile Definitions
|
|
37
62
|
|
|
@@ -68,19 +93,6 @@ ls quickback/.archives/
|
|
|
68
93
|
|
|
69
94
|
As a safety net, the wipe is **skipped** when the manifest contains zero files for the target directory — that's almost always an upstream compile bug, and we'd rather keep your last working tree than overwrite it with nothing.
|
|
70
95
|
|
|
71
|
-
### Initialize Structure
|
|
72
|
-
|
|
73
|
-
```bash
|
|
74
|
-
quickback init
|
|
75
|
-
```
|
|
76
|
-
|
|
77
|
-
Creates the Quickback folder structure in an existing project:
|
|
78
|
-
```
|
|
79
|
-
quickback/
|
|
80
|
-
features/
|
|
81
|
-
quickback.config.ts
|
|
82
|
-
```
|
|
83
|
-
|
|
84
96
|
### View Documentation
|
|
85
97
|
|
|
86
98
|
```bash
|
|
@@ -209,18 +221,27 @@ The active organization is stored in your credentials and sent with compile requ
|
|
|
209
221
|
## Quick Start
|
|
210
222
|
|
|
211
223
|
```bash
|
|
212
|
-
# 1.
|
|
213
|
-
|
|
214
|
-
cd my-app
|
|
224
|
+
# 1. Start a new project (interactive — picks template, scaffolds,
|
|
225
|
+
# prompts for login only when needed)
|
|
226
|
+
mkdir my-app && cd my-app
|
|
227
|
+
npx @quickback-dev/cli start
|
|
228
|
+
|
|
229
|
+
# 2. Run locally
|
|
230
|
+
npm run dev
|
|
231
|
+
```
|
|
215
232
|
|
|
216
|
-
|
|
217
|
-
# (Already has example todos feature)
|
|
233
|
+
Or the scriptable form:
|
|
218
234
|
|
|
219
|
-
|
|
220
|
-
|
|
235
|
+
```bash
|
|
236
|
+
# 1. Create the project (scaffolds + compiles + installs)
|
|
237
|
+
quickback create todos my-app # prompts for login on first compile
|
|
238
|
+
cd my-app
|
|
221
239
|
|
|
222
|
-
#
|
|
240
|
+
# 2. Run
|
|
223
241
|
npm run dev
|
|
242
|
+
|
|
243
|
+
# 3. Recompile after editing definitions
|
|
244
|
+
quickback compile
|
|
224
245
|
```
|
|
225
246
|
|
|
226
247
|
## Options
|
|
@@ -278,9 +299,9 @@ Make sure the CLI is installed globally:
|
|
|
278
299
|
npm install -g @quickback-dev/cli
|
|
279
300
|
```
|
|
280
301
|
|
|
281
|
-
Or use npx:
|
|
302
|
+
Or use npx (no global install needed):
|
|
282
303
|
```bash
|
|
283
|
-
npx @quickback-dev/cli
|
|
304
|
+
npx @quickback-dev/cli start
|
|
284
305
|
```
|
|
285
306
|
|
|
286
307
|
### Compile errors
|
|
@@ -24,18 +24,18 @@ Quickback offers a hosted compiler at `https://compiler.quickback.dev`. The CLI
|
|
|
24
24
|
## Quick Start
|
|
25
25
|
|
|
26
26
|
```bash
|
|
27
|
-
# 1.
|
|
28
|
-
|
|
27
|
+
# 1. Scaffold + compile interactively
|
|
28
|
+
mkdir my-app && cd my-app
|
|
29
|
+
npx @quickback-dev/cli start
|
|
30
|
+
```
|
|
29
31
|
|
|
30
|
-
|
|
32
|
+
`start` walks through template selection, scaffolding, login (only when needed), and the first compile in one flow. Or do it scriptably:
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
npm install -g @quickback-dev/cli
|
|
31
36
|
quickback create cloudflare my-app
|
|
32
37
|
cd my-app
|
|
33
|
-
|
|
34
|
-
# 3. Log in
|
|
35
|
-
quickback login
|
|
36
|
-
|
|
37
|
-
# 4. Compile
|
|
38
|
-
quickback compile
|
|
38
|
+
quickback compile # prompts for login on the first run
|
|
39
39
|
```
|
|
40
40
|
|
|
41
41
|
## Existing Databases
|
|
@@ -1,17 +1,17 @@
|
|
|
1
1
|
# Multi-Domain Architecture
|
|
2
2
|
|
|
3
|
-
A single Quickback-compiled Cloudflare Worker can serve your API, CMS, Account UI,
|
|
3
|
+
A single Quickback-compiled Cloudflare Worker can serve your API, CMS, Account UI, Admin panel, and your own product SPAs on separate custom domains. The compiler generates hostname-based routing so each domain serves the right content.
|
|
4
4
|
|
|
5
5
|
## How It Works
|
|
6
6
|
|
|
7
|
-
When you configure custom domains for CMS, Account,
|
|
7
|
+
When you configure custom domains for CMS, Account, Admin, or `apps`, the compiler:
|
|
8
8
|
|
|
9
9
|
1. Adds `custom_domain` routes to `wrangler.toml`
|
|
10
10
|
2. Generates hostname-based middleware in the Worker
|
|
11
11
|
3. Auto-configures cross-subdomain cookies for shared authentication
|
|
12
12
|
4. Auto-infers a unified `quickback.{baseDomain}` fallback domain
|
|
13
13
|
|
|
14
|
-
All
|
|
14
|
+
All configured domains point to the **same Worker** — there's only one deployment.
|
|
15
15
|
|
|
16
16
|
## Domain Types
|
|
17
17
|
|
|
@@ -21,6 +21,7 @@ All five domains point to the **same Worker** — there's only one deployment.
|
|
|
21
21
|
| `cms.example.com` | `cms: { domain }` | CMS SPA | Blocked (404) |
|
|
22
22
|
| `auth.example.com` | `account: { domain }` | Account SPA | Pass-through |
|
|
23
23
|
| `admin.example.com` | `account: { adminDomain }` | Account SPA | Pass-through |
|
|
24
|
+
| `www.example.com` | `apps: { <name>: { domain } }` | User-authored SPA | Pass-through |
|
|
24
25
|
| `quickback.example.com` | Auto-inferred | Everything | All |
|
|
25
26
|
|
|
26
27
|
### CMS Domain
|
|
@@ -35,6 +36,32 @@ Serves the Account SPA at root (`/`). API and auth routes pass through to the Wo
|
|
|
35
36
|
|
|
36
37
|
Identical behavior to the Account domain — serves the same Account SPA at root. The Account SPA's client-side router handles the `/admin` route, restricting access to users with the `admin` role.
|
|
37
38
|
|
|
39
|
+
### App Domains
|
|
40
|
+
|
|
41
|
+
Mount your own product SPAs on dedicated hostnames via the `apps` field. Each entry binds one or more hostnames to a directory under `src/apps/<name>/` and inherits the same API/auth pass-through behavior as the Account domain — so the SPA can hit `/api/v1/...` and `/auth/...` same-origin without CORS.
|
|
42
|
+
|
|
43
|
+
```typescript
|
|
44
|
+
apps: {
|
|
45
|
+
www: {
|
|
46
|
+
domain: "www.example.com",
|
|
47
|
+
aliasDomains: ["example.com"], // apex serves the same SPA
|
|
48
|
+
},
|
|
49
|
+
marketing: {
|
|
50
|
+
domain: "marketing.example.com",
|
|
51
|
+
},
|
|
52
|
+
}
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
| Option | Required | Description |
|
|
56
|
+
|--------|----------|-------------|
|
|
57
|
+
| `domain` | Yes | Primary custom hostname served at root (`/`) |
|
|
58
|
+
| `aliasDomains` | No | Additional hostnames that serve the same SPA. Each gets its own `custom_domain = true` route. Common case: apex (`example.com`) alongside `www.example.com`. |
|
|
59
|
+
| `assetsDir` | No | Subdirectory under `src/apps/` to serve from. Defaults to the record key. Override only when the on-disk directory needs to differ from the URL-facing name. |
|
|
60
|
+
|
|
61
|
+
Drop the prebuilt SPA output at `quickback/apps/<name>/` — the source-apps passthrough copies it byte-for-byte into `src/apps/<name>/` on every compile. The compiler doesn't build the SPA; it just emits routing for whatever's already there. See [Output Structure](/compiler/config/output#source-apps-quickbackapps) for the passthrough rules.
|
|
62
|
+
|
|
63
|
+
The names `cms`, `account`, and `public` are reserved (they collide with compiler-emitted directories under `src/apps/`). Two app entries can't claim the same hostname, and an app's hostname can't collide with `cms.domain` / `account.domain` / `account.adminDomain`.
|
|
64
|
+
|
|
38
65
|
### Unified Domain
|
|
39
66
|
|
|
40
67
|
The compiler auto-infers a `quickback.{baseDomain}` domain from your configured custom domains. For example, if you have `cms.example.com`, it creates `quickback.example.com`.
|
|
@@ -68,11 +95,12 @@ export default {
|
|
|
68
95
|
name: "My App",
|
|
69
96
|
auth: { password: true, admin: true },
|
|
70
97
|
},
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
98
|
+
apps: {
|
|
99
|
+
www: {
|
|
100
|
+
domain: "www.example.com",
|
|
101
|
+
aliasDomains: ["example.com"],
|
|
102
|
+
},
|
|
103
|
+
},
|
|
76
104
|
providers: {
|
|
77
105
|
runtime: { name: "cloudflare", config: {
|
|
78
106
|
routes: [{ pattern: "api.example.com", custom_domain: true }],
|
|
@@ -82,6 +110,8 @@ export default {
|
|
|
82
110
|
};
|
|
83
111
|
```
|
|
84
112
|
|
|
113
|
+
`trustedOrigins` is optional here — every `cms.domain`, `account.domain`, `account.adminDomain`, and `apps[*].domain` (plus aliases) is automatically added. Declare `trustedOrigins` only when you need to allow an origin the compiler can't infer (e.g. a third-party domain).
|
|
114
|
+
|
|
85
115
|
This generates the following `wrangler.toml` routes:
|
|
86
116
|
|
|
87
117
|
```toml
|
|
@@ -90,18 +120,20 @@ routes = [
|
|
|
90
120
|
{ pattern = "cms.example.com", custom_domain = true },
|
|
91
121
|
{ pattern = "auth.example.com", custom_domain = true },
|
|
92
122
|
{ pattern = "admin.example.com", custom_domain = true },
|
|
123
|
+
{ pattern = "www.example.com", custom_domain = true },
|
|
124
|
+
{ pattern = "example.com", custom_domain = true },
|
|
93
125
|
{ pattern = "quickback.example.com", custom_domain = true }
|
|
94
126
|
]
|
|
95
127
|
```
|
|
96
128
|
|
|
97
129
|
## Cross-Subdomain Authentication
|
|
98
130
|
|
|
99
|
-
When two or more custom domains share a parent domain (e.g., `cms.example.com` + `auth.example.com`), the compiler automatically configures Better Auth for cross-subdomain cookie sharing:
|
|
131
|
+
When two or more custom domains share a parent domain (e.g., `cms.example.com` + `auth.example.com` + `www.example.com`), the compiler automatically configures Better Auth for cross-subdomain cookie sharing. App hostnames (primary + aliases) are folded into the shared-parent detection alongside the CMS, Account, Admin, and top-level `domain` slots:
|
|
100
132
|
|
|
101
133
|
- Sets `crossSubDomainCookies: { enabled: true, domain: '.example.com' }`
|
|
102
134
|
- Sets `sameSite: 'none'` and `secure: true` on auth cookies
|
|
103
135
|
|
|
104
|
-
This means a user who logs in on `auth.example.com` is automatically authenticated on `cms.example.com` and `
|
|
136
|
+
This means a user who logs in on `auth.example.com` is automatically authenticated on `cms.example.com`, `admin.example.com`, and `www.example.com` — no additional setup needed. Apex aliases (e.g. `example.com` listed under `aliasDomains`) are recognized as already being the parent — they don't break shared-parent equality.
|
|
105
137
|
|
|
106
138
|
> **Automatic Detection**
|
|
107
139
|
>
|
|
@@ -128,6 +160,8 @@ The compiler generates middleware that checks `new URL(c.req.url).hostname` on e
|
|
|
128
160
|
|
|
129
161
|
**Account/Admin domain** — API and auth routes (`/api/`, `/auth/`, `/admin/`, `/storage/`, `/health`) pass through to Hono handlers. All other paths are mapped to the `/account/` asset prefix and served with SPA fallback to `/account/index.html`.
|
|
130
162
|
|
|
163
|
+
**App domain** — Identical to Account: API/auth/admin/storage/health pass through, other paths map to `/<assetsDir>/` with SPA fallback. The multi-domain catchall (emitted when both CMS and Account are configured) explicitly skips app hostnames, so an API miss on an app host lands in `app.notFound` (404 JSON) instead of stray-serving a sibling SPA's HTML.
|
|
164
|
+
|
|
131
165
|
**Unified domain** — No hostname filtering. CMS is served at `/cms/`, Account at `/account/`. Root (`/`) redirects to `/cms/`. API routes work at their standard paths.
|
|
132
166
|
|
|
133
167
|
## Without Custom Domains
|
|
@@ -353,7 +353,7 @@ Notes:
|
|
|
353
353
|
|
|
354
354
|
### Source Apps (`quickback/apps/`)
|
|
355
355
|
|
|
356
|
-
For hand-authored TypeScript apps that live alongside the compiler-emitted SPA shells, drop them under `quickback/apps/<name>/`. The CLI copies the tree into `src/apps/<name>/` on every compile, byte-for-byte, after the compiler has finished writing.
|
|
356
|
+
For hand-authored TypeScript apps and prebuilt SPA bundles that live alongside the compiler-emitted SPA shells, drop them under `quickback/apps/<name>/`. The CLI copies the tree into `src/apps/<name>/` on every compile, byte-for-byte, after the compiler has finished writing. Bind a directory to a hostname via [`config.apps`](/compiler/config/domains#app-domains) — the compiler emits the matching Worker middleware automatically.
|
|
357
357
|
|
|
358
358
|
```
|
|
359
359
|
quickback/apps/ # Source — checked into your repo
|
|
@@ -18,6 +18,49 @@ providers: {
|
|
|
18
18
|
}
|
|
19
19
|
```
|
|
20
20
|
|
|
21
|
+
### Runtime Options
|
|
22
|
+
|
|
23
|
+
| Option | Type | Description |
|
|
24
|
+
|--------|------|-------------|
|
|
25
|
+
| `compatibilityDate` | `string` | Emits Cloudflare `compatibility_date` in `wrangler.toml`. |
|
|
26
|
+
| `placement.mode` | `"smart" \| "standard"` | Emits Cloudflare's `[placement]` block. |
|
|
27
|
+
| `observability.enabled` | `boolean` | Emits top-level Workers Logs persistence under `[observability]`. |
|
|
28
|
+
| `observability.headSamplingRate` | `number` | Top-level Workers Logs sample rate from `0` to `1`. |
|
|
29
|
+
| `observability.logs.enabled` | `boolean` | Emits `[observability.logs]`. |
|
|
30
|
+
| `observability.logs.invocationLogs` | `boolean` | Enables or suppresses invocation logs. |
|
|
31
|
+
| `observability.logs.destinations` | `string[]` | Named log export destinations configured in Cloudflare. |
|
|
32
|
+
| `observability.logs.headSamplingRate` | `number` | Workers Logs sample rate from `0` to `1`. |
|
|
33
|
+
| `observability.logs.persist` | `boolean` | Keeps exported logs in the Cloudflare dashboard. |
|
|
34
|
+
| `observability.traces.enabled` | `boolean` | Emits `[observability.traces]`. |
|
|
35
|
+
| `observability.traces.destinations` | `string[]` | Named trace export destinations configured in Cloudflare. |
|
|
36
|
+
| `observability.traces.headSamplingRate` | `number` | Workers Traces sample rate from `0` to `1`. |
|
|
37
|
+
| `observability.traces.persist` | `boolean` | Keeps exported traces in the Cloudflare dashboard. |
|
|
38
|
+
| `routes` | `{ pattern, custom_domain? }[]` | Custom domain routes for the generated Worker. |
|
|
39
|
+
|
|
40
|
+
```typescript
|
|
41
|
+
providers: {
|
|
42
|
+
runtime: defineRuntime("cloudflare", {
|
|
43
|
+
compatibilityDate: "2026-05-13",
|
|
44
|
+
placement: { mode: "smart" },
|
|
45
|
+
observability: {
|
|
46
|
+
enabled: true,
|
|
47
|
+
logs: {
|
|
48
|
+
enabled: true,
|
|
49
|
+
invocationLogs: false,
|
|
50
|
+
destinations: ["logs-prod"],
|
|
51
|
+
headSamplingRate: 0.6,
|
|
52
|
+
},
|
|
53
|
+
traces: {
|
|
54
|
+
enabled: true,
|
|
55
|
+
destinations: ["otel-prod"],
|
|
56
|
+
headSamplingRate: 0.05,
|
|
57
|
+
persist: false,
|
|
58
|
+
},
|
|
59
|
+
},
|
|
60
|
+
}),
|
|
61
|
+
}
|
|
62
|
+
```
|
|
63
|
+
|
|
21
64
|
## Database Providers
|
|
22
65
|
|
|
23
66
|
| Provider | Description |
|
|
@@ -59,6 +102,7 @@ providers: {
|
|
|
59
102
|
| `auditDatabaseName` | `string` | `"{app}-audit"` | D1 database name for audit events |
|
|
60
103
|
| `auditDatabaseId` | `string` | — | Explicit D1 database ID for audit events |
|
|
61
104
|
| `experimentalRemote` | `{ auth?, features?, audit?, webhooks?, files? }` | `{}` | Per-binding `experimental_remote = true` flag for `wrangler dev` (see [below](#sharing-deployed-d1-in-dev-experimental_remote)) |
|
|
105
|
+
| `realtime` | `boolean \| { enabled?, wsTicket? }` | `false` | Enables the Broadcaster Durable Object and optional resource-scoped ws-ticket auth (see [below](#realtime-broadcast-config)) |
|
|
62
106
|
| `webhookAdminRoles` | `string[]` | `["owner", "admin"]` | Org roles allowed to manage webhook endpoints |
|
|
63
107
|
|
|
64
108
|
#### Audit Database
|
|
@@ -125,6 +169,49 @@ Only `true` flips the flag on; `false` or omitted leaves the binding local. Off
|
|
|
125
169
|
> `experimental_remote` is a Wrangler dev feature. A flagged binding hits the deployed D1 from `wrangler dev`, so any write goes to production. Only enable for bindings you've decided are safe to read/write from local dev.
|
|
126
170
|
|
|
127
171
|
|
|
172
|
+
#### Realtime Broadcast Config
|
|
173
|
+
|
|
174
|
+
Set `realtime: true` to enable the generated Broadcaster Durable Object with the default organization-scoped routing model:
|
|
175
|
+
|
|
176
|
+
```typescript
|
|
177
|
+
providers: {
|
|
178
|
+
database: defineDatabase("cloudflare-d1", {
|
|
179
|
+
realtime: true,
|
|
180
|
+
}),
|
|
181
|
+
}
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
For relationship-authorized resource scopes, use the object form:
|
|
185
|
+
|
|
186
|
+
```typescript
|
|
187
|
+
providers: {
|
|
188
|
+
database: defineDatabase("cloudflare-d1", {
|
|
189
|
+
realtime: {
|
|
190
|
+
wsTicket: {
|
|
191
|
+
role: "attendee",
|
|
192
|
+
requestField: "eventId",
|
|
193
|
+
scopeTable: "events",
|
|
194
|
+
},
|
|
195
|
+
},
|
|
196
|
+
}),
|
|
197
|
+
}
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
`wsTicket` tells the compiler how to authorize `/broadcast/v1/ws-ticket` and what scope to stamp into the short-lived websocket ticket:
|
|
201
|
+
|
|
202
|
+
- `role`: an authz role declared under `authz.roles` that uses a direct relationship (`{ via: "..." }`)
|
|
203
|
+
- `requestField`: the JSON body field the client posts to `/broadcast/v1/ws-ticket`
|
|
204
|
+
- `scopeTable`: the parent resource table that defines the broadcast scope key
|
|
205
|
+
|
|
206
|
+
In other words: the relationship table proves access, and the `scopeTable` row defines the channel. For an attendee flow, `guests` (or RSVP) would be the relationship evidence and `events` would be the `scopeTable`.
|
|
207
|
+
|
|
208
|
+
Quickback keeps Better Auth as the front door, then mints its own 60-second websocket ticket after the authz check succeeds. The generated `createRealtime()` helper and Broadcaster share the same targeting model:
|
|
209
|
+
|
|
210
|
+
- string target: historical `organizationId` shorthand
|
|
211
|
+
- object target: `{ scopeKey?, organizationId?, userId? }`
|
|
212
|
+
|
|
213
|
+
See [Realtime](/stack/realtime) for the client-side connection flow and helper examples.
|
|
214
|
+
|
|
128
215
|
<Callout>
|
|
129
216
|
`usePlurals` only affects **auth tables** generated by Better Auth (e.g. `user` vs `users`, `session` vs `sessions`). Feature table names come directly from your Drizzle schema definitions — whatever you pass to `sqliteTable()` or `pgTable()` is used as-is. The `namingConvention` setting applies to both auth and feature column names.
|
|
130
217
|
</Callout>
|
|
@@ -46,9 +46,7 @@ export default defineTable(posts, {
|
|
|
46
46
|
read: {
|
|
47
47
|
access: { roles: ['user', 'admin'] },
|
|
48
48
|
},
|
|
49
|
-
|
|
50
|
-
create: { access: { roles: ['admin'] } },
|
|
51
|
-
},
|
|
49
|
+
create: { access: { roles: ['admin'] } },
|
|
52
50
|
});
|
|
53
51
|
|
|
54
52
|
// Public data (no ownership filtering)
|
|
@@ -57,11 +55,9 @@ export default defineTable(pages, {
|
|
|
57
55
|
read: {
|
|
58
56
|
access: { roles: ['PUBLIC'] },
|
|
59
57
|
},
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
delete: { access: { roles: ['admin'] } },
|
|
64
|
-
},
|
|
58
|
+
create: { access: { roles: ['admin'] } },
|
|
59
|
+
update: { access: { roles: ['admin'] } },
|
|
60
|
+
delete: { access: { roles: ['admin'] } },
|
|
65
61
|
});
|
|
66
62
|
```
|
|
67
63
|
|
|
@@ -76,9 +72,7 @@ Use the `PUBLIC` role to expose routes without authentication. This works the sa
|
|
|
76
72
|
read: {
|
|
77
73
|
access: { roles: ['PUBLIC'] }, // GET / and GET /:id — no auth required
|
|
78
74
|
},
|
|
79
|
-
|
|
80
|
-
create: { access: { roles: ['admin'] } }, // Admin only
|
|
81
|
-
}
|
|
75
|
+
create: { access: { roles: ['admin'] } }, // Admin only
|
|
82
76
|
```
|
|
83
77
|
|
|
84
78
|
## Role-Based Access
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Access - Role & Condition-Based Access Control
|
|
2
2
|
|
|
3
|
-
Define who can perform
|
|
3
|
+
Define who can perform read and write operations and under what conditions.
|
|
4
4
|
|
|
5
5
|
## Basic Usage
|
|
6
6
|
|
|
@@ -24,11 +24,9 @@ export default defineTable(applications, {
|
|
|
24
24
|
read: {
|
|
25
25
|
access: { roles: ["owner", "hiring-manager", "recruiter", "interviewer"] },
|
|
26
26
|
},
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
delete: { access: { roles: ["owner", "hiring-manager"] } },
|
|
31
|
-
},
|
|
27
|
+
create: { access: { roles: ["owner", "hiring-manager", "recruiter"] } },
|
|
28
|
+
update: { access: { roles: ["owner", "hiring-manager", "recruiter"] } },
|
|
29
|
+
delete: { access: { roles: ["owner", "hiring-manager"] } },
|
|
32
30
|
});
|
|
33
31
|
```
|
|
34
32
|
|
|
@@ -51,10 +49,8 @@ Then in your resource definitions:
|
|
|
51
49
|
|
|
52
50
|
```typescript
|
|
53
51
|
read: { access: { roles: ["member+"] } }, // member, admin, owner
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
delete: { access: { roles: ["owner"] } }, // owner only (no +)
|
|
57
|
-
}
|
|
52
|
+
create: { access: { roles: ["admin+"] } }, // admin, owner
|
|
53
|
+
delete: { access: { roles: ["owner"] } }, // owner only (no +)
|
|
58
54
|
```
|
|
59
55
|
|
|
60
56
|
The `+` suffix expands at compile time — `"member+"` becomes `["member", "admin", "owner"]` in the generated code. You can mix hierarchical and exact roles: `roles: ["member+", "finance"]` expands to `["member", "admin", "owner", "finance"]`.
|
|
@@ -118,11 +114,9 @@ access: {
|
|
|
118
114
|
|
|
119
115
|
// CMS-internal resource: only platform admins
|
|
120
116
|
read: { access: { userRole: ['admin'] } },
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
delete: { access: { userRole: ['admin'] } },
|
|
125
|
-
}
|
|
117
|
+
create: { access: { userRole: ['admin'] } },
|
|
118
|
+
update: { access: { userRole: ['admin'] } },
|
|
119
|
+
delete: { access: { userRole: ['admin'] } },
|
|
126
120
|
```
|
|
127
121
|
|
|
128
122
|
When `roles` and `userRole` both appear in a single `Access` node, they're combined with AND — the user must satisfy both. Use `or:` to express "one or the other".
|
|
@@ -153,7 +147,7 @@ access: { roles: ["PUBLIC"] }
|
|
|
153
147
|
|
|
154
148
|
**Important:**
|
|
155
149
|
- `PUBLIC` skips authentication and role checks — anyone can call the endpoint
|
|
156
|
-
- **`PUBLIC` is the explicit, uppercase opt-in for unauthenticated access.** It works on every access node — reads,
|
|
150
|
+
- **`PUBLIC` is the explicit, uppercase opt-in for unauthenticated access.** It works on every access node — reads, top-level writes (`create`/`update`/`delete`/`upsert`), views, and actions. The compiler trusts the marker; row-level safety comes from the firewall, masking, and (for token-gated endpoints like RSVP confirm, magic-link redemption, List-Unsubscribe-Post, webhook ingest) your handler's own validation. Anonymous write endpoints typically pair `roles: ["PUBLIC"]` with `firewall: { exception: true }` on the resource so the row predicate doesn't reject every unauthenticated caller.
|
|
157
151
|
- **Firewall still applies** — data is scoped by the firewall (organization, owner, team)
|
|
158
152
|
- Every `PUBLIC` action invocation is **mandatory audit logged** to the security audit table (IP address, input, result, timing)
|
|
159
153
|
- The wildcard `"*"` is **not supported** — using it throws a compile-time error
|
|
@@ -172,9 +166,7 @@ The firewall WHERE clause is always enforced. If no `organizationId` is provided
|
|
|
172
166
|
export default defineTable(listings, {
|
|
173
167
|
firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
|
|
174
168
|
read: { access: { roles: ["PUBLIC"] } }, // Public browsing + detail
|
|
175
|
-
|
|
176
|
-
create: { access: { roles: ["admin", "member"] } }, // Auth required to create
|
|
177
|
-
},
|
|
169
|
+
create: { access: { roles: ["admin", "member"] } }, // Auth required to create
|
|
178
170
|
});
|
|
179
171
|
```
|
|
180
172
|
|
|
@@ -196,11 +188,9 @@ Use `roles: ["USER"]` for resources where each user only sees their own records.
|
|
|
196
188
|
export default defineTable(todos, {
|
|
197
189
|
firewall: [{ field: 'userId', equals: 'ctx.userId' }],
|
|
198
190
|
read: { access: { roles: ["USER"] } },
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
delete: { access: { roles: ["USER"] } },
|
|
203
|
-
},
|
|
191
|
+
create: { access: { roles: ["USER"] } },
|
|
192
|
+
update: { access: { roles: ["USER"] } },
|
|
193
|
+
delete: { access: { roles: ["USER"] } },
|
|
204
194
|
});
|
|
205
195
|
```
|
|
206
196
|
|
|
@@ -444,9 +434,9 @@ The validator and resolver reject:
|
|
|
444
434
|
- `+` hierarchy suffix on a relationship-role name (terminal, like pseudo-roles).
|
|
445
435
|
- Relationship-roles in `masking.show` / `actions.access` (deferred surfaces — see the table above).
|
|
446
436
|
|
|
447
|
-
## Read &
|
|
437
|
+
## Read & Write Configuration
|
|
448
438
|
|
|
449
|
-
Reads (`GET /` and `GET /:id`) live under `read:`; mutations live under `
|
|
439
|
+
Reads (`GET /` and `GET /:id`) live under `read:`; mutations live under top-level `create:`, `update:`, `delete:`, and `upsert:`. See [Read](/compiler/definitions/read) for the full read pipeline reference.
|
|
450
440
|
|
|
451
441
|
```typescript
|
|
452
442
|
read: {
|
|
@@ -462,35 +452,33 @@ read: {
|
|
|
462
452
|
},
|
|
463
453
|
}
|
|
464
454
|
|
|
465
|
-
|
|
455
|
+
create: {
|
|
466
456
|
// CREATE - POST /resource
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
stage: 'applied',
|
|
471
|
-
},
|
|
457
|
+
access: { roles: ["owner", "hiring-manager", "recruiter"] },
|
|
458
|
+
defaults: { // Default values for new records
|
|
459
|
+
stage: 'applied',
|
|
472
460
|
},
|
|
461
|
+
},
|
|
473
462
|
|
|
463
|
+
update: {
|
|
474
464
|
// UPDATE - PATCH /resource/:id
|
|
475
|
-
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
]
|
|
481
|
-
},
|
|
465
|
+
access: {
|
|
466
|
+
or: [
|
|
467
|
+
{ roles: ["hiring-manager", "recruiter"] },
|
|
468
|
+
{ roles: ["interviewer"], record: { stage: { equals: "interview" } } }
|
|
469
|
+
]
|
|
482
470
|
},
|
|
471
|
+
},
|
|
483
472
|
|
|
473
|
+
delete: {
|
|
484
474
|
// DELETE - DELETE /resource/:id
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
},
|
|
475
|
+
access: { roles: ["owner", "hiring-manager"] },
|
|
476
|
+
mode: "soft", // 'soft' (default) or 'hard'
|
|
477
|
+
},
|
|
489
478
|
|
|
479
|
+
upsert: {
|
|
490
480
|
// PUT - PUT /resource/:id (only when generateId: false + guards: false)
|
|
491
|
-
|
|
492
|
-
access: { roles: ["hiring-manager", "sync-service"] },
|
|
493
|
-
},
|
|
481
|
+
access: { roles: ["hiring-manager", "sync-service"] },
|
|
494
482
|
}
|
|
495
483
|
```
|
|
496
484
|
|
|
@@ -601,17 +589,15 @@ access: {
|
|
|
601
589
|
For complex access logic that can't be expressed declaratively, use a function:
|
|
602
590
|
|
|
603
591
|
```typescript
|
|
604
|
-
|
|
605
|
-
|
|
606
|
-
|
|
607
|
-
|
|
608
|
-
|
|
609
|
-
|
|
610
|
-
|
|
611
|
-
|
|
612
|
-
|
|
613
|
-
return membership.canEdit;
|
|
614
|
-
}
|
|
592
|
+
update: {
|
|
593
|
+
access: async (ctx, record) => {
|
|
594
|
+
// Custom logic - return true to allow, false to deny
|
|
595
|
+
if (ctx.roles.includes('admin')) return true;
|
|
596
|
+
if (record.ownerId === ctx.userId) return true;
|
|
597
|
+
|
|
598
|
+
// Check custom business logic
|
|
599
|
+
const membership = await checkTeamMembership(ctx.userId, record.teamId);
|
|
600
|
+
return membership.canEdit;
|
|
615
601
|
}
|
|
616
602
|
}
|
|
617
603
|
```
|
|
@@ -19,11 +19,9 @@ export const contacts = q.table("contacts", {
|
|
|
19
19
|
export default defineTable(contacts, {
|
|
20
20
|
firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
|
|
21
21
|
read: { access: { roles: ["member+"] } },
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
delete: { access: { roles: ["admin+"] }, mode: "soft" },
|
|
26
|
-
},
|
|
22
|
+
create: { access: { roles: ["member+"] } },
|
|
23
|
+
update: { access: { roles: ["member+"] } },
|
|
24
|
+
delete: { access: { roles: ["admin+"] }, mode: "soft" },
|
|
27
25
|
guards: { createable: ["address", "name"] },
|
|
28
26
|
});
|
|
29
27
|
|
|
@@ -44,11 +42,9 @@ export default feature("contacts", {
|
|
|
44
42
|
},
|
|
45
43
|
firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
|
|
46
44
|
read: { access: { roles: ["member+"] } },
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
delete: { access: { roles: ["admin+"] }, mode: "soft" },
|
|
51
|
-
},
|
|
45
|
+
create: { access: { roles: ["member+"] } },
|
|
46
|
+
update: { access: { roles: ["member+"] } },
|
|
47
|
+
delete: { access: { roles: ["admin+"] }, mode: "soft" },
|
|
52
48
|
guards: { createable: ["address", "name"] },
|
|
53
49
|
});
|
|
54
50
|
```
|
|
@@ -57,7 +53,7 @@ Type inference still works — `typeof import("./contacts").default.$infer` give
|
|
|
57
53
|
|
|
58
54
|
## How it works
|
|
59
55
|
|
|
60
|
-
`feature(name, config)` is a **compile-time sugar**, not a runtime abstraction. When the compiler sees `export default feature(...)`, it rewrites the source to the canonical two-export form before any parsing runs. Every downstream layer — dialect pass, audit injection, security contracts,
|
|
56
|
+
`feature(name, config)` is a **compile-time sugar**, not a runtime abstraction. When the compiler sees `export default feature(...)`, it rewrites the source to the canonical two-export form before any parsing runs. Every downstream layer — dialect pass, audit injection, security contracts, generated routes, OpenAPI, MCP tools, RLS emission — runs on the same Drizzle source it always did. Zero runtime cost; zero semantic difference from `q.table()` + `defineTable()`.
|
|
61
57
|
|
|
62
58
|
That means:
|
|
63
59
|
|