@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
|
@@ -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
|
|
@@ -4,11 +4,7 @@ Providers configure which services your compiled backend targets.
|
|
|
4
4
|
|
|
5
5
|
## Runtime Providers
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
|----------|-------------|
|
|
9
|
-
| `cloudflare` | Cloudflare Workers (Hono) |
|
|
10
|
-
| `bun` | Bun runtime (Hono) |
|
|
11
|
-
| `node` | Node.js runtime (Hono) |
|
|
7
|
+
The Quickback Stack is **Cloudflare-only**. `cloudflare` is the single supported runtime.
|
|
12
8
|
|
|
13
9
|
```typescript
|
|
14
10
|
import { defineRuntime } from "@quickback/compiler";
|
|
@@ -63,13 +59,12 @@ providers: {
|
|
|
63
59
|
|
|
64
60
|
## Database Providers
|
|
65
61
|
|
|
62
|
+
Two databases are supported, both Cloudflare-native:
|
|
63
|
+
|
|
66
64
|
| Provider | Description |
|
|
67
65
|
|----------|-------------|
|
|
68
|
-
| `cloudflare-d1` | Cloudflare D1 (SQLite) |
|
|
69
|
-
| `
|
|
70
|
-
| `libsql` | LibSQL / Turso |
|
|
71
|
-
| `neon` | Neon (PostgreSQL) |
|
|
72
|
-
| `supabase` | Supabase (PostgreSQL) |
|
|
66
|
+
| `cloudflare-d1` | Cloudflare D1 (SQLite at the edge) |
|
|
67
|
+
| `neon` | Neon (PostgreSQL over Hyperdrive) |
|
|
73
68
|
|
|
74
69
|
```typescript
|
|
75
70
|
import { defineDatabase } from "@quickback/compiler";
|
|
@@ -235,8 +230,7 @@ See [Realtime](/stack/realtime) for the client-side connection flow and helper e
|
|
|
235
230
|
|
|
236
231
|
| Provider | Description |
|
|
237
232
|
|----------|-------------|
|
|
238
|
-
| `better-auth` | Better Auth with plugins |
|
|
239
|
-
| `supabase-auth` | Supabase Auth |
|
|
233
|
+
| `better-auth` | Better Auth with plugins (default) |
|
|
240
234
|
| `external` | External auth via Cloudflare service binding |
|
|
241
235
|
|
|
242
236
|
```typescript
|
|
@@ -107,36 +107,6 @@ For running remote migrations with `drizzle-kit`, set these in `.env`:
|
|
|
107
107
|
| `CLOUDFLARE_AUDIT_DATABASE_ID` | Security audit D1 database ID (unsafe cross-tenant actions) |
|
|
108
108
|
| `CLOUDFLARE_DATABASE_ID` | Database ID (single DB mode) |
|
|
109
109
|
|
|
110
|
-
## Bun Variables
|
|
111
|
-
|
|
112
|
-
Set these in a `.env` file in your project root:
|
|
113
|
-
|
|
114
|
-
| Variable | Description | Default |
|
|
115
|
-
|----------|-------------|---------|
|
|
116
|
-
| `NODE_ENV` | Runtime environment | `development` |
|
|
117
|
-
| `PORT` | Server port | `3000` |
|
|
118
|
-
| `BETTER_AUTH_SECRET` | Auth encryption secret | — (required) |
|
|
119
|
-
| `BETTER_AUTH_URL` | Public URL of your server | `http://localhost:3000` |
|
|
120
|
-
| `DATABASE_PATH` | Path to SQLite file | `./data/app.db` |
|
|
121
|
-
|
|
122
|
-
## Turso (LibSQL) Variables
|
|
123
|
-
|
|
124
|
-
In addition to the Bun variables above:
|
|
125
|
-
|
|
126
|
-
| Variable | Description | Default |
|
|
127
|
-
|----------|-------------|---------|
|
|
128
|
-
| `DATABASE_URL` | LibSQL connection URL | `file:./data/app.db` |
|
|
129
|
-
| `DATABASE_AUTH_TOKEN` | Turso auth token (required for remote) | — |
|
|
130
|
-
|
|
131
|
-
```bash
|
|
132
|
-
# Local development
|
|
133
|
-
DATABASE_URL=file:./data/app.db
|
|
134
|
-
|
|
135
|
-
# Production (Turso cloud)
|
|
136
|
-
DATABASE_URL=libsql://your-db-slug.turso.io
|
|
137
|
-
DATABASE_AUTH_TOKEN=eyJhbGciOi...
|
|
138
|
-
```
|
|
139
|
-
|
|
140
110
|
## Social Login Providers
|
|
141
111
|
|
|
142
112
|
When social login is configured in your auth provider:
|
|
@@ -321,10 +321,118 @@ Resource definitions reference declared roles by name in `roles: [...]` arrays e
|
|
|
321
321
|
| `crud.*.access` `roles: ['guest']` | ✓ Supported | Inline async lookup per request |
|
|
322
322
|
| `read.access` / `read.views.*.access` `roles: ['guest']` | ✓ Supported | Same inline path |
|
|
323
323
|
| `masking.<field>.show` `roles: ['guest']` | ⚠ Refused at compile | v1 limitation — async/batched mask functions deferred |
|
|
324
|
-
| `actions.<name>.access` `roles: ['guest']` |
|
|
324
|
+
| **Standalone** `actions.<name>.access` `roles: ['guest']` | ✓ Supported (v0.19+) | Inline gate; surface must expose `resource.column` as path param or input field |
|
|
325
|
+
| **Record-based** `actions.<name>.access` `roles: ['guest']` | ⚠ Fail-closed at runtime | Runtime helper denies; inline emission is a planned follow-up. Use `firewall: { exception: true }` or move the check into `execute()` until then |
|
|
325
326
|
|
|
326
327
|
For the surfaces that are not yet supported, the compiler refuses at build time with a clear error pointing to a workaround. The runtime evaluator fails closed on relationship arms regardless, so silent grants are impossible.
|
|
327
328
|
|
|
329
|
+
### Standalone actions: surface keys and `loads` / `exposeAs` (v0.19+)
|
|
330
|
+
|
|
331
|
+
When a standalone action's `access.roles` references a relationship-role, the compiler emits a runtime gate between input validation and `execute()`. The gate reads the relationship's `resource.column` value from the action surface — either a path parameter (`:eventId`) or an input field (`input.eventId`). If neither is present, the compiler:
|
|
332
|
+
|
|
333
|
+
- **v0.19** — emits a `[quickback:authz]` warning and skips resolver emission. The action's own hand-rolled gate (if any) keeps the route working at runtime.
|
|
334
|
+
- **v0.20** — hard compile error. Set `firewall: { exception: true }` to opt out (cross-tenant/admin routes only).
|
|
335
|
+
|
|
336
|
+
Pair the relationship with `loads` + `exposeAs` to hydrate the loaded resource onto `ctx`:
|
|
337
|
+
|
|
338
|
+
```typescript
|
|
339
|
+
authz: {
|
|
340
|
+
relationships: {
|
|
341
|
+
attendeeOf: {
|
|
342
|
+
from: 'guests',
|
|
343
|
+
subject: { column: 'userId', equals: 'ctx.userId' },
|
|
344
|
+
resource: { column: 'eventId' },
|
|
345
|
+
where: { status: 'confirmed' },
|
|
346
|
+
loads: 'events', // ← v0.19+: load matching event row
|
|
347
|
+
exposeAs: 'event', // ← onto ctx.event for the action body
|
|
348
|
+
},
|
|
349
|
+
},
|
|
350
|
+
roles: {
|
|
351
|
+
attendee: { via: 'attendeeOf' },
|
|
352
|
+
},
|
|
353
|
+
}
|
|
354
|
+
```
|
|
355
|
+
|
|
356
|
+
The resolver (v0.20):
|
|
357
|
+
|
|
358
|
+
1. **Cheap in-memory role check** first — `ctx.roles?.includes('admin')` and friends. If the caller has a qualifying role, this short-circuits and no DB queries fire for the access gate.
|
|
359
|
+
2. **Firewall-gated relationship match** if the role check failed — `SELECT { organizationId, teamId } FROM guests WHERE userId=ctx.userId AND eventId=input.eventId AND status='confirmed'` with the `guests` table's full firewall AND-applied. If neither role nor relationship qualifies → 403.
|
|
360
|
+
3. **Tenant stamping from the matched row** — for any tenant column the `from` table carries (`organizationId`, `teamId`), the resolver stamps `ctx.activeOrgId ??= matchedRow.organizationId` (and similar for team). This is **in-memory mutation of the request-scoped ctx only** — no JWT remint, no session-record write, no persistent grant.
|
|
361
|
+
4. **Firewall-gated load of the loaded resource** — `SELECT * FROM events WHERE id = :eventId AND buildEventsFirewallConditions(ctx, db)`. The events firewall is applied as normal; it succeeds for attendees because tenant was just stamped from the relationship row.
|
|
362
|
+
5. Assigns the loaded row to `ctx.event` for the action body.
|
|
363
|
+
|
|
364
|
+
**No firewall bypass anywhere.** Both queries run with their respective tables' full firewalls. The relationship row's existence is the proof that the caller is authorized; its tenant columns are the source of the stamped claim.
|
|
365
|
+
|
|
366
|
+
### Conditional tenant preconditions (v0.20+)
|
|
367
|
+
|
|
368
|
+
Standalone actions in features with org/team-scoped tables previously emitted unconditional preconditions:
|
|
369
|
+
|
|
370
|
+
```ts
|
|
371
|
+
if (!ctx.activeOrgId) return c.json(AccessErrors.noOrg(), 403);
|
|
372
|
+
if (!ctx.activeTeamId) return c.json(AccessErrors.noTeam(), 403);
|
|
373
|
+
```
|
|
374
|
+
|
|
375
|
+
These ran **before** the relationship resolver, which 403'd attendees whose sessions don't carry an active tenant claim (the canonical event-attendee shape).
|
|
376
|
+
|
|
377
|
+
v0.20 makes these preconditions **conditional on relationship supply**. If the access tree contains a relationship arm whose `from` table carries the matching tenant column, the precondition is skipped — the resolver runs first and stamps the value. Pseudo-role short-circuits (PUBLIC / AUTHENTICATED / USER / ADMIN / SYSADMIN) and `firewall: { exception: true }` still bypass the preconditions as before.
|
|
378
|
+
|
|
379
|
+
Typical event-attendee setup (`guests` table carries `organizationId`): the org precondition is dropped on every action whose access references `attendee` or `eventStaff`. Org admins still get `ctx.activeOrgId` from their session as today; attendees get it from the relationship row, mid-request. Both paths converge on a valid tenant claim before `execute()` runs.
|
|
380
|
+
|
|
381
|
+
### Requirement on the relationship's `from` table
|
|
382
|
+
|
|
383
|
+
For the v0.20 tenant-stamping to work, the relationship's `from` table must carry tenant columns:
|
|
384
|
+
|
|
385
|
+
- For org stamping: an `organizationId` column (or whatever spelling the project's auth-provider defaults pick).
|
|
386
|
+
- For team stamping: a `teamId` column.
|
|
387
|
+
|
|
388
|
+
When the `from` table has **neither**, the compiler emits a `[quickback:authz]` warning at compile time:
|
|
389
|
+
|
|
390
|
+
```
|
|
391
|
+
Relationship "X" at authz.relationships.X has no organization or team columns
|
|
392
|
+
on its `from` table ("guests"). Action "Y" will compile, but downstream
|
|
393
|
+
scoped-db queries inside execute() may 403 because ctx.activeOrgId /
|
|
394
|
+
activeTeamId cannot be stamped from the match row. Either add the tenant
|
|
395
|
+
column to "guests", or set firewall: { exception: true } on the action.
|
|
396
|
+
```
|
|
397
|
+
|
|
398
|
+
The relationship match still works (existence check), but no tenant gets stamped — so the conventional precondition still fires and the action still 403s for callers without a session-resident tenant claim. Add the tenant column (or denormalize it onto the relationship table during writes) to enable the stamping path.
|
|
399
|
+
|
|
400
|
+
The body can then trust `ctx.event` and drop the hand-rolled `SELECT … FROM guests WHERE …` boilerplate:
|
|
401
|
+
|
|
402
|
+
```ts
|
|
403
|
+
// features/chat/actions/getInbox.ts
|
|
404
|
+
export default defineAction({
|
|
405
|
+
path: '/chat/get-inbox',
|
|
406
|
+
input: z.object({ eventId: z.number().int().positive() }),
|
|
407
|
+
access: { roles: ['admin', 'member', 'attendee'] }, // attendee is a relationship-role
|
|
408
|
+
execute: async ({ db, ctx, input }) => {
|
|
409
|
+
// No hand-rolled attendance check needed — the resolver already ran.
|
|
410
|
+
// ctx.event is the loaded events row (typed as any in v0.19; cast as
|
|
411
|
+
// needed — narrow per-action types are a follow-up).
|
|
412
|
+
const event = ctx.event as typeof events.$inferSelect;
|
|
413
|
+
// … domain logic only.
|
|
414
|
+
},
|
|
415
|
+
});
|
|
416
|
+
```
|
|
417
|
+
|
|
418
|
+
`loads` and `exposeAs` are co-required (set both or neither). `exposeAs` must be a valid JS identifier and must not collide with built-in `ctx` fields (`userId`, `activeOrgId`, `activeTeamId`, `db`, etc.).
|
|
419
|
+
|
|
420
|
+
### Action firewall escape hatch (v0.19+)
|
|
421
|
+
|
|
422
|
+
`defineAction({ firewall: { exception: true } })` opts the action out of the inherited session-key preconditions (`ctx.activeOrgId` / `ctx.activeTeamId` requirements) AND the relationship resolver. The handler receives `unsafeDb` for raw Drizzle access. Use for cross-tenant or admin routes whose surface intentionally doesn't name a session/relationship key:
|
|
423
|
+
|
|
424
|
+
```ts
|
|
425
|
+
defineAction({
|
|
426
|
+
path: '/admin/cross-tenant-report',
|
|
427
|
+
firewall: { exception: true },
|
|
428
|
+
unsafe: { reason: 'cross-tenant audit', adminOnly: true, targetScope: 'all' },
|
|
429
|
+
access: { roles: ['ADMIN'] },
|
|
430
|
+
execute: async ({ unsafeDb, ctx }) => { /* cross-org query */ },
|
|
431
|
+
});
|
|
432
|
+
```
|
|
433
|
+
|
|
434
|
+
`firewall: { exception: true }` is the declarative twin of `unsafe: true` — they're conceptually distinct: `firewall.exception` opts out of the gate-emission pillars; `unsafe` signals audit/cross-tenant intent (and still applies for logging). Most cross-tenant actions set both.
|
|
435
|
+
|
|
328
436
|
### Recommended pattern: gate at the firewall layer
|
|
329
437
|
|
|
330
438
|
Most of the time, relationship-based row visibility is what you want, and putting it at the **firewall** layer is the cleanest expression. The firewall is row-filter; the access layer is route/role-filter; let each do its job:
|
|
@@ -434,6 +542,100 @@ The validator and resolver reject:
|
|
|
434
542
|
- `+` hierarchy suffix on a relationship-role name (terminal, like pseudo-roles).
|
|
435
543
|
- Relationship-roles in `masking.show` / `actions.access` (deferred surfaces — see the table above).
|
|
436
544
|
|
|
545
|
+
## Namespace mounts (hoisted relationship middleware)
|
|
546
|
+
|
|
547
|
+
When several standalone actions share a path prefix and the same relationship gate — `/event/:eventId/announce`, `/event/:eventId/cancel`, `/event/:eventId/respond` — declaring the gate per-action means writing the same `roles: ['attendee']` over and over AND paying the relationship-resolver cost N times per request (one subquery + one row-load, multiplied by the number of actions).
|
|
548
|
+
|
|
549
|
+
Namespace mounts hoist the resolver into one Hono middleware that runs once per request. Every action under the prefix skips the inline gate; `ctx.<exposeAs>` is hydrated by the middleware and typed automatically inside the handlers.
|
|
550
|
+
|
|
551
|
+
Two declaration sites depending on whether the participating actions live in one feature or many:
|
|
552
|
+
|
|
553
|
+
### Single feature: `defineTable({ namespace })` (v0.23+)
|
|
554
|
+
|
|
555
|
+
Use when every action under the prefix lives in the same feature directory. The namespace travels with the table that owns it — no addition to `quickback.config.ts` needed.
|
|
556
|
+
|
|
557
|
+
```typescript
|
|
558
|
+
// features/events/events.ts
|
|
559
|
+
export default defineTable(events, {
|
|
560
|
+
firewall: [...],
|
|
561
|
+
crud: { ... },
|
|
562
|
+
namespace: {
|
|
563
|
+
prefix: '/event/:eventId', // absolute URL path
|
|
564
|
+
via: 'attendeeOf', // relationship gate (must exist in authz.relationships)
|
|
565
|
+
},
|
|
566
|
+
});
|
|
567
|
+
|
|
568
|
+
// features/events/actions/post-announcement.ts
|
|
569
|
+
export default defineAction({
|
|
570
|
+
path: '/event/:eventId/announcements',
|
|
571
|
+
method: 'POST',
|
|
572
|
+
// No gate boilerplate. ctx.event is typed inside execute().
|
|
573
|
+
});
|
|
574
|
+
```
|
|
575
|
+
|
|
576
|
+
The compiler emits one `app.use(...)` on the events feature's Hono app. Every standalone action in `features/events/actions/` whose path starts with `/event/:eventId/` joins the namespace automatically.
|
|
577
|
+
|
|
578
|
+
### Cross-feature: `authz.namespaces` (v0.24+)
|
|
579
|
+
|
|
580
|
+
Use when the namespace spans multiple features. The declaration sits next to your other authz config in `quickback.config.ts`.
|
|
581
|
+
|
|
582
|
+
```typescript
|
|
583
|
+
// quickback.config.ts
|
|
584
|
+
authz: {
|
|
585
|
+
relationships: {
|
|
586
|
+
attendeeOf: {
|
|
587
|
+
from: 'guests',
|
|
588
|
+
subject: { column: 'userId', equals: 'ctx.userId' },
|
|
589
|
+
resource: { column: 'eventId' },
|
|
590
|
+
loads: 'events',
|
|
591
|
+
exposeAs: 'event',
|
|
592
|
+
},
|
|
593
|
+
},
|
|
594
|
+
namespaces: {
|
|
595
|
+
eventScope: { prefix: '/event/:eventId', via: 'attendeeOf' },
|
|
596
|
+
},
|
|
597
|
+
}
|
|
598
|
+
|
|
599
|
+
// features/feeds/actions/feed-moments.ts (in a different feature)
|
|
600
|
+
export default defineAction({
|
|
601
|
+
path: '/event/:eventId/feed-moments',
|
|
602
|
+
method: 'POST',
|
|
603
|
+
});
|
|
604
|
+
|
|
605
|
+
// features/rsvp/actions/respond.ts (and another)
|
|
606
|
+
export default defineAction({
|
|
607
|
+
path: '/event/:eventId/respond',
|
|
608
|
+
method: 'POST',
|
|
609
|
+
});
|
|
610
|
+
```
|
|
611
|
+
|
|
612
|
+
The compiler emits one synthetic `src/routes/__namespace-event-scope.routes.ts` that imports each contributing feature's `actions` map under a distinct alias, mounts the resolver middleware once, and dispatches to the matching action. Worker-root mount order ensures the middleware fires before any per-feature route handler under the prefix.
|
|
613
|
+
|
|
614
|
+
### Discovery is path-prefix-only
|
|
615
|
+
|
|
616
|
+
Actions opt in by matching `path:` against a declared namespace prefix. There's no `namespace: 'foo'` field on `defineAction` — the path string is the discoverable surface, consistent with how `path:` already determines an action's URL.
|
|
617
|
+
|
|
618
|
+
### Requirements (enforced at compile time)
|
|
619
|
+
|
|
620
|
+
Both forms share the same shape checks:
|
|
621
|
+
|
|
622
|
+
- **`via:` must point at a declared `authz.relationships[*]` entry**, and that relationship must declare `loads + exposeAs`. Without `loads` there's nothing for the middleware to hydrate, and the namespace gate becomes indistinguishable from a per-action access rule.
|
|
623
|
+
- **`prefix:` must contain at least one `:param` segment** (e.g. `/event/:eventId`). The middleware reads the relationship key from `c.req.param()` because no request body has been parsed at middleware time.
|
|
624
|
+
- **One declaration per namespace name.** The same name in both `defineTable({ namespace })` and `authz.namespaces` is rejected. The project-level form is canonical for cross-feature; the table-level form is the single-feature shorthand.
|
|
625
|
+
|
|
626
|
+
Project-level only:
|
|
627
|
+
|
|
628
|
+
- **Ambiguous prefixes** like `/a/:x` and `/a/:y` (same shape, different `:param` names) are rejected. Strict super/sub-set relationships (`/event/:e` vs `/event/:e/admin`) are fine — the harvester routes each action to the longest matching prefix.
|
|
629
|
+
- **Unused namespace** emits a `[quickback:authz]` warning when no action's path matches the declared prefix. Not a hard error — the namespace may be staged ahead of the actions.
|
|
630
|
+
|
|
631
|
+
### What namespace actions get for free
|
|
632
|
+
|
|
633
|
+
Inside a namespace action's `execute()`:
|
|
634
|
+
|
|
635
|
+
- `ctx.<exposeAs>` is populated by the middleware with the loaded resource row, typed as `typeof <loadsTable>.$inferSelect`.
|
|
636
|
+
- Tenant context (`ctx.activeOrgId` / `ctx.activeTeamId`) is stamped from the matched relationship row when its `from` table carries those columns. Downstream scoped queries work without further setup.
|
|
637
|
+
- The action's own `access:` block (additional roles, userRole, record predicates, OTHER relationship arms) still runs after the namespace gate — namespace handles entry, per-action gates further.
|
|
638
|
+
|
|
437
639
|
## Read & Write Configuration
|
|
438
640
|
|
|
439
641
|
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.
|