@quickback-dev/cli 0.17.1 → 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/dist/docs/content.js +7 -7
- package/dist/docs/content.js.map +1 -1
- package/dist/skill/docs/changelog.md +398 -1214
- 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/getting-started/template-cloudflare.md +49 -54
- package/dist/skill/docs/compiler/getting-started/templates.md +58 -56
- package/dist/skill/docs/index.md +9 -0
- package/dist/skill/docs/stack/index.md +8 -4
- package/package.json +1 -1
- package/src/skill/docs/changelog.md +459 -1215
- 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/getting-started/template-cloudflare.md +49 -54
- package/src/skill/docs/compiler/getting-started/templates.md +58 -56
- package/src/skill/docs/index.md +9 -0
- package/src/skill/docs/stack/auth/plugins/index.md +74 -0
- package/src/skill/docs/stack/index.md +8 -4
|
@@ -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
|
|
@@ -2,14 +2,24 @@
|
|
|
2
2
|
|
|
3
3
|
The Cloudflare template creates a production-ready backend running on Cloudflare Workers with D1 (SQLite at the edge), KV storage, and Better Auth.
|
|
4
4
|
|
|
5
|
+
`cloudflare` is a **bare scaffold** — multi-tenant orgs + auth + DB are wired in, but there are no example features. Add your own feature files under `quickback/features/`. If you want a working example to read first, use the [todos template](/compiler/getting-started/templates#multi-tenant-scaffolds-free) — same providers, but with a complete `todos` feature ready to extend.
|
|
6
|
+
|
|
5
7
|
## Create the Project
|
|
6
8
|
|
|
9
|
+
The fastest path is `start` — interactive, scaffold + login + compile in one flow:
|
|
10
|
+
|
|
7
11
|
```bash
|
|
8
|
-
|
|
9
|
-
|
|
12
|
+
mkdir my-app && cd my-app
|
|
13
|
+
npx @quickback-dev/cli start
|
|
14
|
+
# pick "Cloudflare (bare scaffold)" at the prompt
|
|
10
15
|
```
|
|
11
16
|
|
|
12
|
-
|
|
17
|
+
Scriptable equivalent:
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
quickback create cloudflare my-app # aliases: cf
|
|
21
|
+
cd my-app
|
|
22
|
+
```
|
|
13
23
|
|
|
14
24
|
This scaffolds a project with:
|
|
15
25
|
|
|
@@ -17,11 +27,8 @@ This scaffolds a project with:
|
|
|
17
27
|
my-app/
|
|
18
28
|
├── quickback/
|
|
19
29
|
│ ├── quickback.config.ts # Compiler configuration
|
|
20
|
-
│ └── features/
|
|
21
|
-
|
|
22
|
-
│ ├── todos.ts # Schema + security (defineTable)
|
|
23
|
-
│ └── actions.ts # Custom actions
|
|
24
|
-
├── src/ # Compiled output (generated)
|
|
30
|
+
│ └── features/ # (empty — add your own)
|
|
31
|
+
├── src/ # Compiled output (generated by `quickback compile`)
|
|
25
32
|
├── package.json
|
|
26
33
|
├── tsconfig.json
|
|
27
34
|
├── wrangler.toml
|
|
@@ -33,90 +40,78 @@ my-app/
|
|
|
33
40
|
### quickback.config.ts
|
|
34
41
|
|
|
35
42
|
```typescript
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
export default defineConfig({
|
|
43
|
+
export default {
|
|
39
44
|
name: "my-app",
|
|
40
45
|
template: "hono",
|
|
41
|
-
features:
|
|
46
|
+
features: {
|
|
47
|
+
organizations: true,
|
|
48
|
+
},
|
|
49
|
+
auth: {
|
|
50
|
+
// Use "role+" in access rules to mean "this role and above".
|
|
51
|
+
// e.g. roles: ["member+"] expands to ["member", "admin", "owner"].
|
|
52
|
+
roleHierarchy: ["member", "admin", "owner"],
|
|
53
|
+
},
|
|
42
54
|
providers: {
|
|
43
55
|
runtime: { name: "cloudflare", config: {} },
|
|
44
56
|
database: {
|
|
45
57
|
name: "cloudflare-d1",
|
|
46
|
-
config: { binding: "DB" },
|
|
58
|
+
config: { binding: "DB", realtime: true },
|
|
47
59
|
},
|
|
48
60
|
auth: { name: "better-auth", config: {} },
|
|
49
61
|
},
|
|
50
|
-
}
|
|
62
|
+
};
|
|
51
63
|
```
|
|
52
64
|
|
|
53
|
-
###
|
|
65
|
+
### Adding your first feature
|
|
54
66
|
|
|
55
|
-
|
|
67
|
+
Create a file at `quickback/features/<name>/<name>.ts` and export a `defineTable(...)` default. The shape used by the `todos` template makes a good starting point — see [todos.ts in the template registry](/compiler/getting-started/templates#multi-tenant-scaffolds-free) for a full multi-tenant example with masking, actions, and a named view.
|
|
56
68
|
|
|
57
69
|
```typescript
|
|
58
|
-
|
|
70
|
+
// quickback/features/posts/posts.ts
|
|
71
|
+
import { sqliteTable, text } from "drizzle-orm/sqlite-core";
|
|
59
72
|
import { defineTable } from "@quickback/compiler";
|
|
60
73
|
|
|
61
|
-
export const
|
|
74
|
+
export const posts = sqliteTable("posts", {
|
|
62
75
|
id: text("id").primaryKey(),
|
|
63
76
|
title: text("title").notNull(),
|
|
64
|
-
|
|
65
|
-
completed: integer("completed", { mode: "boolean" }).default(false),
|
|
66
|
-
priority: text("priority").default("medium"),
|
|
67
|
-
dueDate: integer("due_date", { mode: "timestamp" }),
|
|
77
|
+
body: text("body"),
|
|
68
78
|
organizationId: text("organization_id").notNull(),
|
|
69
|
-
|
|
79
|
+
userId: text("user_id").notNull(),
|
|
70
80
|
});
|
|
71
81
|
|
|
72
|
-
export default defineTable(
|
|
73
|
-
firewall:
|
|
74
|
-
{ field: 'organizationId', equals: 'ctx.activeOrgId' },
|
|
75
|
-
{ field: 'deletedAt', isNull: true },
|
|
76
|
-
],
|
|
82
|
+
export default defineTable(posts, {
|
|
83
|
+
firewall: { organization: {}, owner: {}, softDelete: {} },
|
|
77
84
|
guards: {
|
|
78
|
-
createable: ["title", "
|
|
79
|
-
updatable: ["title", "
|
|
80
|
-
immutable: ["id", "organizationId", "
|
|
81
|
-
},
|
|
82
|
-
masking: {
|
|
83
|
-
description: {
|
|
84
|
-
type: "redact",
|
|
85
|
-
show: { roles: ["owner", "admin"] },
|
|
86
|
-
},
|
|
85
|
+
createable: ["title", "body"],
|
|
86
|
+
updatable: ["title", "body"],
|
|
87
|
+
immutable: ["id", "organizationId", "userId"],
|
|
87
88
|
},
|
|
88
|
-
read: {
|
|
89
|
-
|
|
90
|
-
},
|
|
91
|
-
|
|
92
|
-
update: { access: { roles: ["owner", "admin", "member"] } },
|
|
93
|
-
delete: { access: { roles: ["owner", "admin"] }, mode: "soft" },
|
|
89
|
+
read: { access: { roles: ["member+"] } },
|
|
90
|
+
create: { access: { roles: ["member+"] } },
|
|
91
|
+
update: { access: { roles: ["member+"] } },
|
|
92
|
+
delete: { access: { roles: ["admin+"] }, mode: "soft" },
|
|
94
93
|
});
|
|
95
94
|
```
|
|
96
95
|
|
|
97
96
|
## Setup Steps
|
|
98
97
|
|
|
98
|
+
If you used `quickback start`, dependencies, the first compile, and login are already done — skip to step 4. If you used `quickback create`, run these:
|
|
99
|
+
|
|
99
100
|
### 1. Install Dependencies
|
|
100
101
|
|
|
101
102
|
```bash
|
|
102
103
|
npm install
|
|
103
104
|
```
|
|
104
105
|
|
|
105
|
-
### 2.
|
|
106
|
-
|
|
107
|
-
```bash
|
|
108
|
-
quickback login
|
|
109
|
-
```
|
|
110
|
-
|
|
111
|
-
### 3. Compile Your Definitions
|
|
106
|
+
### 2. Compile Your Definitions
|
|
112
107
|
|
|
113
108
|
```bash
|
|
114
109
|
quickback compile
|
|
115
110
|
```
|
|
116
111
|
|
|
117
|
-
This
|
|
112
|
+
This prompts for an account on the first run (sign in or create one in the browser), then generates the full `src/` directory, migrations, and configuration files. Subsequent compiles re-use the stored session.
|
|
118
113
|
|
|
119
|
-
###
|
|
114
|
+
### 3. Create D1 Databases
|
|
120
115
|
|
|
121
116
|
The Cloudflare template uses **dual database mode** by default — separate databases for auth and application data.
|
|
122
117
|
|
|
@@ -142,7 +137,7 @@ database_name = "my-app-features"
|
|
|
142
137
|
database_id = "paste-features-id-here"
|
|
143
138
|
```
|
|
144
139
|
|
|
145
|
-
###
|
|
140
|
+
### 4. Run Migrations (Local)
|
|
146
141
|
|
|
147
142
|
```bash
|
|
148
143
|
npm run db:migrate:local
|
|
@@ -150,7 +145,7 @@ npm run db:migrate:local
|
|
|
150
145
|
|
|
151
146
|
This applies migrations to both databases locally.
|
|
152
147
|
|
|
153
|
-
###
|
|
148
|
+
### 5. Start Development Server
|
|
154
149
|
|
|
155
150
|
```bash
|
|
156
151
|
npm run dev
|
|
@@ -2,105 +2,107 @@
|
|
|
2
2
|
|
|
3
3
|
Quickback provides pre-configured templates to get you started quickly. Each template combines a runtime, database, and auth provider into a working project.
|
|
4
4
|
|
|
5
|
+
The fastest way to start is `quickback start` — an interactive picker that asks for a template + project name and scaffolds in the current directory if it's empty, otherwise creates a subfolder. Every template below can be reached either via `start`'s picker (free tier) or scriptably via `quickback create <template> <name>`.
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
# Interactive (recommended for first-time use)
|
|
9
|
+
mkdir my-app && cd my-app
|
|
10
|
+
npx @quickback-dev/cli start
|
|
11
|
+
```
|
|
12
|
+
|
|
5
13
|
## Available Templates
|
|
6
14
|
|
|
7
|
-
###
|
|
15
|
+
### Multi-tenant scaffolds (free)
|
|
16
|
+
|
|
17
|
+
Cloudflare Workers + D1 + Better Auth with the organization plugin and a `member` / `admin` / `owner` role hierarchy wired in.
|
|
8
18
|
|
|
9
|
-
|
|
19
|
+
| Template | Includes | Command |
|
|
20
|
+
|----------|----------|---------|
|
|
21
|
+
| `cloudflare` | Bare scaffold — auth + DB + Hono, no example feature | `quickback create cloudflare my-app` |
|
|
22
|
+
| `todos` | Working todos feature: schema, masking, two actions (`complete` / `uncomplete`), and a `dashboard` named view | `quickback create todos my-app` |
|
|
10
23
|
|
|
11
|
-
|
|
12
|
-
|----------|---------|----------|------|--------|---------|
|
|
13
|
-
| `cloudflare` | Cloudflare Workers | D1 (SQLite) | Better Auth | Multi-tenant | `quickback create cloudflare my-app` |
|
|
14
|
-
| `multi-tenant` | Cloudflare Workers | D1 (SQLite) | Better Auth | Multi-tenant + orgs | `quickback create multi-tenant my-app` |
|
|
24
|
+
The **todos** template is the recommended first read — it exercises every security pillar (firewall, access, guards, masking) plus actions and views in ~80 lines you can scan in five minutes.
|
|
15
25
|
|
|
16
|
-
###
|
|
26
|
+
### Single-tenant starter (free)
|
|
17
27
|
|
|
18
|
-
|
|
28
|
+
| Template | Includes | Command |
|
|
29
|
+
|----------|----------|---------|
|
|
30
|
+
| `blog` | Single-tenant blog with PUBLIC reads, admin writes, `publish` / `unpublish` actions | `quickback create blog my-site` |
|
|
19
31
|
|
|
20
|
-
|
|
21
|
-
|----------|---------|----------|--------|---------|
|
|
22
|
-
| `blog` | Cloudflare Workers | D1 | Single-tenant | `quickback create blog my-site` |
|
|
32
|
+
The **blog** template uses Better Auth's admin plugin (not the org plugin) and [single-tenant mode](/compiler/config/single-tenant) (`organizations: false`).
|
|
23
33
|
|
|
24
|
-
|
|
25
|
-
- Public read access (no auth required for `list` and `get`)
|
|
26
|
-
- Admin-only write access (create, update, delete, publish/unpublish)
|
|
27
|
-
- A `posts` feature with title, slug, content, status, and publish date
|
|
28
|
-
- [Single-tenant mode](/compiler/config/single-tenant) (`organizations: false`)
|
|
34
|
+
### Empty scaffold (free)
|
|
29
35
|
|
|
30
|
-
|
|
36
|
+
| Template | Includes | Command |
|
|
37
|
+
|----------|----------|---------|
|
|
38
|
+
| `empty` | `quickback.config.ts` only — no example features | `quickback create empty my-app` |
|
|
31
39
|
|
|
32
|
-
|
|
40
|
+
The empty template creates the project structure with `quickback.config.ts` only. Add your first feature by creating a file under `quickback/features/<name>/<name>.ts` exporting `defineTable(...)` — there is no separate `init` step.
|
|
33
41
|
|
|
34
|
-
|
|
35
|
-
|----------|---------|----------|---------|
|
|
36
|
-
| `empty` | Cloudflare Workers | D1 | `quickback create empty my-app` |
|
|
42
|
+
### B2B SaaS (Pro)
|
|
37
43
|
|
|
38
|
-
|
|
44
|
+
| Template | Includes | Command |
|
|
45
|
+
|----------|----------|---------|
|
|
46
|
+
| `saas` | Multi-tenant + **R2 file storage** + **outbound webhooks** + split databases + realtime + named views | `quickback create saas my-app` |
|
|
39
47
|
|
|
40
48
|
## What Each Template Includes
|
|
41
49
|
|
|
42
|
-
|
|
50
|
+
The `cloudflare`, `todos`, `blog`, and `saas` templates all scaffold:
|
|
43
51
|
|
|
44
52
|
- **`quickback.config.ts`** — Pre-configured with the right providers
|
|
45
|
-
- **`quickback/features/`** —
|
|
46
|
-
- **Deployment scripts** — `npm run deploy` for Cloudflare
|
|
53
|
+
- **`quickback/features/`** — Feature definitions (empty for `cloudflare`; populated for `todos` / `blog` / `saas`)
|
|
54
|
+
- **Deployment scripts** — `npm run deploy` for Cloudflare via wrangler
|
|
47
55
|
|
|
48
|
-
|
|
56
|
+
The `empty` template includes only:
|
|
49
57
|
|
|
50
|
-
- **`quickback.config.ts`**
|
|
51
|
-
- **`package.json`** —
|
|
58
|
+
- **`quickback.config.ts`**
|
|
59
|
+
- **`package.json`** — dependencies ready to install
|
|
52
60
|
|
|
53
61
|
## Choosing a Template
|
|
54
62
|
|
|
55
|
-
### Cloudflare
|
|
63
|
+
### Cloudflare bare scaffold
|
|
56
64
|
|
|
57
|
-
Best
|
|
65
|
+
Best when you already know the conventions and want empty walls. Multi-tenant orgs are wired in; you add your own feature files.
|
|
58
66
|
|
|
59
|
-
|
|
60
|
-
- Global edge deployment
|
|
61
|
-
- Built-in KV, R2, Queues, Vectorize
|
|
62
|
-
- Dual database mode (separate auth and features DBs)
|
|
67
|
+
### Todos (recommended for newcomers)
|
|
63
68
|
|
|
64
|
-
|
|
69
|
+
Best for learning by reading. Full multi-tenant security pillars, two actions, a named view (`/api/v1/todos/views/dashboard`), and field masking on the `description` column — all in a single ~80-line file you can copy-edit into your own table.
|
|
65
70
|
|
|
66
|
-
|
|
71
|
+
### Blog (single-tenant CMS)
|
|
72
|
+
|
|
73
|
+
Best for personal sites, blogs, or any app with a single tenant. Uses [single-tenant mode](/compiler/config/single-tenant) — no organizations, roles come from `user.role` via Better Auth's admin plugin.
|
|
67
74
|
|
|
68
75
|
- Public JSON API for content
|
|
69
|
-
- Admin-only editing
|
|
76
|
+
- Admin-only editing
|
|
70
77
|
- Pair with any frontend (Astro, Next.js, SvelteKit, etc.)
|
|
71
78
|
|
|
72
|
-
### Empty
|
|
79
|
+
### Empty
|
|
73
80
|
|
|
74
81
|
Best when you know exactly what you want to build. Gets you the project structure and config without any opinionated features.
|
|
75
82
|
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
83
|
+
### SaaS (Pro)
|
|
84
|
+
|
|
85
|
+
Best for production B2B work. Adds R2 file uploads, outbound webhooks (with retry/dedupe), split auth/features/webhooks databases, realtime broadcast, and named views.
|
|
79
86
|
|
|
80
87
|
## Template Aliases
|
|
81
88
|
|
|
82
89
|
For convenience, templates have short aliases:
|
|
83
90
|
|
|
84
|
-
| Alias |
|
|
85
|
-
|
|
86
|
-
| `cf` | `betterauth-d1-cloudflare` |
|
|
91
|
+
| Alias | Full id |
|
|
92
|
+
|-------|---------|
|
|
93
|
+
| `cloudflare` / `cf` | `betterauth-d1-cloudflare` |
|
|
94
|
+
| `todos` | `todos-cloudflare` |
|
|
95
|
+
| `blog` | `blog-cloudflare` |
|
|
87
96
|
| `saas` | `b2bsaas-cloudflare` |
|
|
88
|
-
| `scaffold` | `empty-cloudflare` |
|
|
97
|
+
| `empty` / `scaffold` | `empty-cloudflare` |
|
|
98
|
+
|
|
99
|
+
## After Scaffolding
|
|
89
100
|
|
|
90
|
-
|
|
101
|
+
`quickback start` runs scaffold + login + compile + install + drizzle in one flow. If you used the scriptable `quickback create` instead (or cancelled at the login prompt), finish setup with:
|
|
91
102
|
|
|
92
103
|
```bash
|
|
93
|
-
# 1. Create the project
|
|
94
|
-
quickback create cloudflare my-app
|
|
95
104
|
cd my-app
|
|
96
|
-
|
|
97
|
-
# 2. Log in to the compiler
|
|
98
|
-
quickback login
|
|
99
|
-
|
|
100
|
-
# 3. Compile your definitions
|
|
101
|
-
quickback compile
|
|
102
|
-
|
|
103
|
-
# 4. Run locally
|
|
105
|
+
quickback compile # prompts for login on first run; reuses session after
|
|
104
106
|
npm run dev
|
|
105
107
|
```
|
|
106
108
|
|
package/src/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
|