@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.
Files changed (127) hide show
  1. package/README.md +7 -3
  2. package/dist/commands/compile.d.ts.map +1 -1
  3. package/dist/commands/compile.js +12 -48
  4. package/dist/commands/compile.js.map +1 -1
  5. package/dist/commands/create.d.ts +20 -0
  6. package/dist/commands/create.d.ts.map +1 -1
  7. package/dist/commands/create.js +216 -151
  8. package/dist/commands/create.js.map +1 -1
  9. package/dist/commands/login.d.ts +4 -2
  10. package/dist/commands/login.d.ts.map +1 -1
  11. package/dist/commands/login.js +25 -17
  12. package/dist/commands/login.js.map +1 -1
  13. package/dist/commands/start.d.ts +20 -0
  14. package/dist/commands/start.d.ts.map +1 -0
  15. package/dist/commands/start.js +163 -0
  16. package/dist/commands/start.js.map +1 -0
  17. package/dist/commands/whoami.d.ts.map +1 -1
  18. package/dist/commands/whoami.js +5 -4
  19. package/dist/commands/whoami.js.map +1 -1
  20. package/dist/docs/content.js +42 -42
  21. package/dist/docs/content.js.map +1 -1
  22. package/dist/index.js +27 -10
  23. package/dist/index.js.map +1 -1
  24. package/dist/lib/api-client.js +1 -1
  25. package/dist/lib/api-client.js.map +1 -1
  26. package/dist/lib/api-client.test.js +15 -0
  27. package/dist/lib/api-client.test.js.map +1 -1
  28. package/dist/lib/auth.d.ts +39 -3
  29. package/dist/lib/auth.d.ts.map +1 -1
  30. package/dist/lib/auth.js +57 -3
  31. package/dist/lib/auth.js.map +1 -1
  32. package/dist/lib/drizzle-meta-routing.test.js +16 -3
  33. package/dist/lib/drizzle-meta-routing.test.js.map +1 -1
  34. package/dist/lib/file-loader.d.ts +6 -4
  35. package/dist/lib/file-loader.d.ts.map +1 -1
  36. package/dist/lib/file-loader.js +30 -27
  37. package/dist/lib/file-loader.js.map +1 -1
  38. package/dist/lib/file-loader.test.js +16 -7
  39. package/dist/lib/file-loader.test.js.map +1 -1
  40. package/dist/skill/docs/changelog.md +429 -1100
  41. package/dist/skill/docs/compiler/cloud-compiler/cli.md +54 -33
  42. package/dist/skill/docs/compiler/cloud-compiler/index.md +9 -9
  43. package/dist/skill/docs/compiler/config/providers.md +87 -0
  44. package/dist/skill/docs/compiler/config/single-tenant.md +5 -11
  45. package/dist/skill/docs/compiler/definitions/access.md +43 -57
  46. package/dist/skill/docs/compiler/definitions/feature.md +7 -11
  47. package/dist/skill/docs/compiler/definitions/firewall.md +2 -4
  48. package/dist/skill/docs/compiler/definitions/guards.md +16 -18
  49. package/dist/skill/docs/compiler/definitions/index.md +10 -14
  50. package/dist/skill/docs/compiler/definitions/masking.md +6 -6
  51. package/dist/skill/docs/compiler/definitions/read.md +6 -11
  52. package/dist/skill/docs/compiler/definitions/schema.md +18 -18
  53. package/dist/skill/docs/compiler/definitions/views.md +3 -5
  54. package/dist/skill/docs/compiler/getting-started/full-example.md +6 -8
  55. package/dist/skill/docs/compiler/getting-started/hand-crafted.md +3 -5
  56. package/dist/skill/docs/compiler/getting-started/index.md +23 -20
  57. package/dist/skill/docs/compiler/getting-started/patterns.md +19 -31
  58. package/dist/skill/docs/compiler/getting-started/template-blog.md +6 -10
  59. package/dist/skill/docs/compiler/getting-started/template-cloudflare.md +49 -56
  60. package/dist/skill/docs/compiler/getting-started/template-empty.md +3 -5
  61. package/dist/skill/docs/compiler/getting-started/templates.md +58 -56
  62. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +29 -23
  63. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +12 -14
  64. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +5 -2
  65. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +5 -7
  66. package/dist/skill/docs/compiler/troubleshooting.md +10 -0
  67. package/dist/skill/docs/index.md +9 -0
  68. package/dist/skill/docs/stack/auth/security.md +69 -0
  69. package/dist/skill/docs/stack/cms/actions.md +28 -0
  70. package/dist/skill/docs/stack/cms/connecting.md +2 -2
  71. package/dist/skill/docs/stack/cms/index.md +2 -2
  72. package/dist/skill/docs/stack/cms/record-layouts.md +19 -19
  73. package/dist/skill/docs/stack/cms/schema-format.md +33 -3
  74. package/dist/skill/docs/stack/cms/schema-registry.md +22 -2
  75. package/dist/skill/docs/stack/cms/security.md +10 -12
  76. package/dist/skill/docs/stack/cms/table-views.md +1 -1
  77. package/dist/skill/docs/stack/index.md +8 -4
  78. package/dist/skill/docs/stack/realtime/durable-objects.md +46 -5
  79. package/dist/skill/docs/stack/realtime/index.md +20 -3
  80. package/dist/skill/docs/stack/realtime/using-realtime.md +8 -6
  81. package/dist/skill/docs/stack/vector/embeddings.md +7 -6
  82. package/package.json +1 -1
  83. package/src/skill/docs/changelog.md +486 -1097
  84. package/src/skill/docs/compiler/cloud-compiler/cli.md +54 -33
  85. package/src/skill/docs/compiler/cloud-compiler/index.md +9 -9
  86. package/src/skill/docs/compiler/config/domains.md +44 -10
  87. package/src/skill/docs/compiler/config/output.md +1 -1
  88. package/src/skill/docs/compiler/config/providers.md +87 -0
  89. package/src/skill/docs/compiler/config/single-tenant.md +5 -11
  90. package/src/skill/docs/compiler/definitions/access.md +43 -57
  91. package/src/skill/docs/compiler/definitions/feature.md +7 -11
  92. package/src/skill/docs/compiler/definitions/firewall.md +2 -4
  93. package/src/skill/docs/compiler/definitions/guards.md +16 -18
  94. package/src/skill/docs/compiler/definitions/index.md +10 -14
  95. package/src/skill/docs/compiler/definitions/masking.md +6 -6
  96. package/src/skill/docs/compiler/definitions/read.md +6 -11
  97. package/src/skill/docs/compiler/definitions/schema.md +18 -18
  98. package/src/skill/docs/compiler/definitions/views.md +3 -5
  99. package/src/skill/docs/compiler/getting-started/full-example.md +6 -8
  100. package/src/skill/docs/compiler/getting-started/hand-crafted.md +3 -5
  101. package/src/skill/docs/compiler/getting-started/index.md +23 -20
  102. package/src/skill/docs/compiler/getting-started/patterns.md +19 -31
  103. package/src/skill/docs/compiler/getting-started/template-blog.md +6 -10
  104. package/src/skill/docs/compiler/getting-started/template-cloudflare.md +49 -56
  105. package/src/skill/docs/compiler/getting-started/template-empty.md +3 -5
  106. package/src/skill/docs/compiler/getting-started/templates.md +58 -56
  107. package/src/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +29 -23
  108. package/src/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +12 -14
  109. package/src/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +5 -2
  110. package/src/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +5 -7
  111. package/src/skill/docs/compiler/troubleshooting.md +10 -0
  112. package/src/skill/docs/index.md +9 -0
  113. package/src/skill/docs/stack/auth/plugins/index.md +74 -0
  114. package/src/skill/docs/stack/auth/security.md +69 -0
  115. package/src/skill/docs/stack/cms/actions.md +28 -0
  116. package/src/skill/docs/stack/cms/connecting.md +2 -2
  117. package/src/skill/docs/stack/cms/index.md +2 -2
  118. package/src/skill/docs/stack/cms/record-layouts.md +19 -19
  119. package/src/skill/docs/stack/cms/schema-format.md +33 -3
  120. package/src/skill/docs/stack/cms/schema-registry.md +22 -2
  121. package/src/skill/docs/stack/cms/security.md +10 -12
  122. package/src/skill/docs/stack/cms/table-views.md +1 -1
  123. package/src/skill/docs/stack/index.md +8 -4
  124. package/src/skill/docs/stack/realtime/durable-objects.md +46 -5
  125. package/src/skill/docs/stack/realtime/index.md +20 -3
  126. package/src/skill/docs/stack/realtime/using-realtime.md +8 -6
  127. package/src/skill/docs/stack/vector/embeddings.md +7 -6
@@ -2,14 +2,24 @@
2
2
 
3
3
  The Cloudflare template creates a production-ready backend running on Cloudflare Workers with D1 (SQLite at the edge), KV storage, and Better Auth.
4
4
 
5
+ `cloudflare` is a **bare scaffold** — multi-tenant orgs + auth + DB are wired in, but there are no example features. Add your own feature files under `quickback/features/`. If you want a working example to read first, use the [todos template](/compiler/getting-started/templates#multi-tenant-scaffolds-free) — same providers, but with a complete `todos` feature ready to extend.
6
+
5
7
  ## Create the Project
6
8
 
9
+ The fastest path is `start` — interactive, scaffold + login + compile in one flow:
10
+
7
11
  ```bash
8
- quickback create cloudflare my-app
9
- cd my-app
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
- Aliases: `quickback create cf my-app`
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
- │ └── todos/
22
- │ ├── todos.ts # Schema + security (defineTable)
23
- │ └── actions.ts # Custom actions
24
- ├── src/ # Compiled output (generated)
30
+ │ └── features/ # (empty — add your own)
31
+ ├── src/ # Compiled output (generated by `quickback compile`)
25
32
  ├── package.json
26
33
  ├── tsconfig.json
27
34
  ├── wrangler.toml
@@ -33,92 +40,78 @@ my-app/
33
40
  ### quickback.config.ts
34
41
 
35
42
  ```typescript
36
- import { defineConfig } from "@quickback/compiler";
37
-
38
- export default defineConfig({
43
+ export default {
39
44
  name: "my-app",
40
45
  template: "hono",
41
- features: ["organizations"],
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
- ### Example Feature (todos.ts)
65
+ ### Adding your first feature
54
66
 
55
- The template includes a `todos` feature with all four security pillars configured:
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
- import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
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 todos = sqliteTable("todos", {
74
+ export const posts = sqliteTable("posts", {
62
75
  id: text("id").primaryKey(),
63
76
  title: text("title").notNull(),
64
- description: text("description"),
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
- ownerId: text("owner_id").notNull(),
79
+ userId: text("user_id").notNull(),
70
80
  });
71
81
 
72
- export default defineTable(todos, {
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", "description", "completed", "priority", "dueDate"],
79
- updatable: ["title", "description", "completed", "priority", "dueDate"],
80
- immutable: ["id", "organizationId", "ownerId"],
81
- },
82
- masking: {
83
- description: {
84
- type: "redact",
85
- show: { roles: ["owner", "admin"] },
86
- },
87
- },
88
- read: {
89
- access: { roles: ["owner", "admin", "member"] },
90
- },
91
- crud: {
92
- create: { access: { roles: ["owner", "admin", "member"] } },
93
- update: { access: { roles: ["owner", "admin", "member"] } },
94
- delete: { access: { roles: ["owner", "admin"] }, mode: "soft" },
85
+ createable: ["title", "body"],
86
+ updatable: ["title", "body"],
87
+ immutable: ["id", "organizationId", "userId"],
95
88
  },
89
+ read: { access: { roles: ["member+"] } },
90
+ create: { access: { roles: ["member+"] } },
91
+ update: { access: { roles: ["member+"] } },
92
+ delete: { access: { roles: ["admin+"] }, mode: "soft" },
96
93
  });
97
94
  ```
98
95
 
99
96
  ## Setup Steps
100
97
 
98
+ If you used `quickback start`, dependencies, the first compile, and login are already done — skip to step 4. If you used `quickback create`, run these:
99
+
101
100
  ### 1. Install Dependencies
102
101
 
103
102
  ```bash
104
103
  npm install
105
104
  ```
106
105
 
107
- ### 2. Log In to the Compiler
108
-
109
- ```bash
110
- quickback login
111
- ```
112
-
113
- ### 3. Compile Your Definitions
106
+ ### 2. Compile Your Definitions
114
107
 
115
108
  ```bash
116
109
  quickback compile
117
110
  ```
118
111
 
119
- This sends your definitions to the Quickback compiler and generates the full `src/` directory, migrations, and configuration files.
112
+ This prompts for an account on the first run (sign in or create one in the browser), then generates the full `src/` directory, migrations, and configuration files. Subsequent compiles re-use the stored session.
120
113
 
121
- ### 4. Create D1 Databases
114
+ ### 3. Create D1 Databases
122
115
 
123
116
  The Cloudflare template uses **dual database mode** by default — separate databases for auth and application data.
124
117
 
@@ -144,7 +137,7 @@ database_name = "my-app-features"
144
137
  database_id = "paste-features-id-here"
145
138
  ```
146
139
 
147
- ### 5. Run Migrations (Local)
140
+ ### 4. Run Migrations (Local)
148
141
 
149
142
  ```bash
150
143
  npm run db:migrate:local
@@ -152,7 +145,7 @@ npm run db:migrate:local
152
145
 
153
146
  This applies migrations to both databases locally.
154
147
 
155
- ### 6. Start Development Server
148
+ ### 5. Start Development Server
156
149
 
157
150
  ```bash
158
151
  npm run dev
@@ -84,11 +84,9 @@ export default defineTable(products, {
84
84
  read: {
85
85
  access: { roles: ["member+"] },
86
86
  },
87
- crud: {
88
- create: { access: { roles: ["member+"] } },
89
- update: { access: { roles: ["member+"] } },
90
- delete: { access: { roles: ["admin+"] }, mode: "soft" },
91
- },
87
+ create: { access: { roles: ["member+"] } },
88
+ update: { access: { roles: ["member+"] } },
89
+ delete: { access: { roles: ["admin+"] }, mode: "soft" },
92
90
  });
93
91
  ```
94
92
 
@@ -2,105 +2,107 @@
2
2
 
3
3
  Quickback provides pre-configured templates to get you started quickly. Each template combines a runtime, database, and auth provider into a working project.
4
4
 
5
+ The fastest way to start is `quickback start` — an interactive picker that asks for a template + project name and scaffolds in the current directory if it's empty, otherwise creates a subfolder. Every template below can be reached either via `start`'s picker (free tier) or scriptably via `quickback create <template> <name>`.
6
+
7
+ ```bash
8
+ # Interactive (recommended for first-time use)
9
+ mkdir my-app && cd my-app
10
+ npx @quickback-dev/cli start
11
+ ```
12
+
5
13
  ## Available Templates
6
14
 
7
- ### Full-Featured Templates
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
- These templates include an example feature (todos) with full security configuration.
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
- | Template | Runtime | Database | Auth | Tenant | Command |
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
- ### Starter Templates
26
+ ### Single-tenant starter (free)
17
27
 
18
- Purpose-built templates with opinionated defaults for common use cases.
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
- | Template | Runtime | Database | Tenant | Command |
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
- The **blog** template creates a single-tenant blog/CMS backend with:
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
- ### Empty Scaffolding
36
+ | Template | Includes | Command |
37
+ |----------|----------|---------|
38
+ | `empty` | `quickback.config.ts` only — no example features | `quickback create empty my-app` |
31
39
 
32
- Start from scratch with just the config file — no example features. Add your own definitions.
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
- | Template | Runtime | Database | Command |
35
- |----------|---------|----------|---------|
36
- | `empty` | Cloudflare Workers | D1 | `quickback create empty my-app` |
42
+ ### B2B SaaS (Pro)
37
43
 
38
- These create the project structure with `quickback.config.ts` only — no `features/` directory. Run `quickback init` inside the project to scaffold your first feature.
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
- Full-featured and starter templates scaffold a complete project with:
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/`** — Example feature(s) with security configuration
46
- - **Deployment scripts** — `npm run deploy` for Cloudflare, `npm start` for Bun
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
- Empty templates include only:
56
+ The `empty` template includes only:
49
57
 
50
- - **`quickback.config.ts`** — Pre-configured with the right providers
51
- - **`package.json`** — Dependencies ready to install
58
+ - **`quickback.config.ts`**
59
+ - **`package.json`** — dependencies ready to install
52
60
 
53
61
  ## Choosing a Template
54
62
 
55
- ### Cloudflare (Recommended for Production)
63
+ ### Cloudflare bare scaffold
56
64
 
57
- Best for production deployments. Runs on Cloudflare's global edge network with zero cold starts. Includes D1 (SQLite at the edge), KV storage, and R2 file storage.
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
- - Free tier available (Workers free plan)
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
- ### Blog (Single-Tenant CMS)
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
- 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`.
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 via Better Auth admin plugin
76
+ - Admin-only editing
70
77
  - Pair with any frontend (Astro, Next.js, SvelteKit, etc.)
71
78
 
72
- ### Empty (Start from Scratch)
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
- - Config-only scaffolding
77
- - Cloudflare Workers + D1 runtime
78
- - Add features with `quickback init` or by hand
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 | Template |
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
- ## After Creating a Project
101
+ `quickback start` runs scaffold + login + compile + install + drizzle in one flow. If you used the scriptable `quickback create` instead (or cancelled at the login prompt), finish setup with:
91
102
 
92
103
  ```bash
93
- # 1. Create the project
94
- quickback create cloudflare my-app
95
104
  cd my-app
96
-
97
- # 2. Log in to the compiler
98
- quickback login
99
-
100
- # 3. Compile your definitions
101
- quickback compile
102
-
103
- # 4. Run locally
105
+ quickback compile # prompts for login on first run; reuses session after
104
106
  npm run dev
105
107
  ```
106
108
 
@@ -1,22 +1,22 @@
1
1
  # Batch Operations
2
2
 
3
- Batch operations let you create, update, or delete multiple records in a single request. They are **auto-enabled** when the corresponding CRUD operation exists in your definition.
3
+ Batch operations let you create, update, upsert, or delete multiple records in a single request. They are **auto-enabled** when the corresponding write operation exists in your definition.
4
4
 
5
5
  ## Available Endpoints
6
6
 
7
7
  | Endpoint | Method | Auto-enabled When |
8
8
  |----------|--------|-------------------|
9
- | `/{resource}/batch` | `POST` | `crud.create` exists |
10
- | `/{resource}/batch` | `PATCH` | `crud.update` exists |
11
- | `/{resource}/batch` | `DELETE` | `crud.delete` exists |
12
- | `/{resource}/batch` | `PUT` | `crud.put` exists |
9
+ | `/{resource}/batch` | `POST` | `create` exists |
10
+ | `/{resource}/batch` | `PATCH` | `update` exists |
11
+ | `/{resource}/batch` | `DELETE` | `delete` exists |
12
+ | `/{resource}/batch` | `PUT` | `upsert` exists |
13
13
 
14
14
  To disable a batch operation, set it to `false` in your definition:
15
15
 
16
16
  ```typescript
17
- crud: {
18
- create: { access: { roles: ['hiring-manager'] } },
19
- batchCreate: false, // Disable batch create
17
+ create: {
18
+ access: { roles: ['hiring-manager'] },
19
+ batch: false, // Disable batch create
20
20
  }
21
21
  ```
22
22
 
@@ -309,33 +309,39 @@ The default maximum batch size is **100 records**. Requests exceeding the limit
309
309
 
310
310
  ## Configuration
311
311
 
312
- Batch operations inherit access control from their corresponding CRUD operation. You can override per-batch settings:
312
+ Batch operations inherit access control from their corresponding write operation. You can override per-batch settings:
313
313
 
314
314
  ```typescript
315
315
  export default defineTable(applications, {
316
- crud: {
317
- create: { access: { roles: ['hiring-manager', 'recruiter'] } },
318
- update: { access: { roles: ['hiring-manager', 'recruiter'] } },
319
- delete: { access: { roles: ['hiring-manager'] }, mode: 'soft' },
320
-
321
- // Override batch-specific settings
322
- batchCreate: {
323
- access: { roles: ['hiring-manager'] }, // More restrictive than single create
324
- maxBatchSize: 50, // Default: 100
325
- allowFailFast: true, // Default: true
316
+ create: {
317
+ access: { roles: ['hiring-manager', 'recruiter'] },
318
+ batch: {
319
+ access: { roles: ['hiring-manager'] }, // More restrictive than single create
320
+ maxBatchSize: 50, // Default: 100
321
+ allowFailFast: true, // Default: true
326
322
  },
327
- batchUpdate: {
323
+ },
324
+ update: {
325
+ access: { roles: ['hiring-manager', 'recruiter'] },
326
+ batch: {
328
327
  maxBatchSize: 100,
329
328
  allowFailFast: true,
330
329
  },
331
- batchDelete: {
330
+ },
331
+ delete: {
332
+ access: { roles: ['hiring-manager'] },
333
+ mode: 'soft',
334
+ batch: {
332
335
  access: { roles: ['hiring-manager'] },
333
336
  maxBatchSize: 100,
334
337
  allowFailFast: true,
335
338
  },
339
+ },
336
340
 
337
- // Disable a batch operation entirely
338
- batchUpsert: false,
341
+ // Disable only batch upsert
342
+ upsert: {
343
+ access: { roles: ['hiring-manager'] },
344
+ batch: false,
339
345
  },
340
346
  });
341
347
  ```
@@ -580,30 +580,28 @@ All batch operation errors include:
580
580
 
581
581
  #### Configuration
582
582
 
583
- Batch operations are **auto-enabled** when corresponding CRUD operations exist:
583
+ Batch operations are **auto-enabled** when corresponding write operations exist:
584
584
 
585
585
  ```typescript
586
586
  // Auto-enabled - no configuration needed
587
- crud: {
588
- create: { access: { roles: ['recruiter'] } },
589
- update: { access: { roles: ['recruiter'] } }
590
- // batchCreate and batchUpdate automatically available
591
- }
587
+ create: { access: { roles: ['recruiter'] } },
588
+ update: { access: { roles: ['recruiter'] } }
589
+ // create.batch and update.batch automatically available
592
590
 
593
591
  // Customize batch operations
594
- crud: {
595
- create: { access: { roles: ['recruiter'] } },
596
- batchCreate: {
592
+ create: {
593
+ access: { roles: ['recruiter'] },
594
+ batch: {
597
595
  access: { roles: ['hiring-manager'] }, // Different access rules
598
- maxBatchSize: 50, // Lower limit
599
- allowFailFast: false // Disable failFast mode
596
+ maxBatchSize: 50, // Lower limit
597
+ allowFailFast: false // Disable failFast mode
600
598
  }
601
599
  }
602
600
 
603
601
  // Disable batch operations
604
- crud: {
605
- create: { access: { roles: ['recruiter'] } },
606
- batchCreate: false // Explicitly disable
602
+ create: {
603
+ access: { roles: ['recruiter'] },
604
+ batch: false // Explicitly disable
607
605
  }
608
606
  ```
609
607
 
@@ -140,18 +140,21 @@ const { data, error } = await client.GET('/api/v1/jobs', { params: { query: { li
140
140
  | `true` (default) | Write `api-types.gen.ts` to the project root |
141
141
  | `false` | Don't emit the types file |
142
142
  | `"src/lib/api-types.ts"` | Custom output path (relative to project root) |
143
+ | `["api-types.gen.ts", "apps/web/src/lib/api-types.gen.ts"]` | Write the same generated types to multiple paths in one compile |
143
144
 
144
145
  ```typescript
145
146
  // quickback.config.ts
146
147
  export default defineConfig({
147
148
  // ...
148
149
  openapi: {
149
- types: 'src/lib/api-types.gen.ts', // emit straight into your client app
150
+ types: ['api-types.gen.ts', 'apps/web/src/lib/api-types.gen.ts'],
150
151
  },
151
152
  });
152
153
  ```
153
154
 
154
- The file is generated by piping the in-memory spec through [openapi-typescript](https://github.com/openapi-ts/openapi-typescript) — you can keep running it manually if you want a different output path or version, but for the typical case there's nothing to wire up. Skipped automatically when `openapi.generate` is `false`.
155
+ The file is generated by piping the in-memory spec through [openapi-typescript](https://github.com/openapi-ts/openapi-typescript) — you can keep running it manually if you want a different output path or version, but for the typical case there's nothing to wire up. If your API project and SPA live in the same repo, prefer multiple `openapi.types` outputs over a second manual `codegen:api` step so one `quickback compile` keeps both copies in sync. Skipped automatically when `openapi.generate` is `false`.
156
+
157
+ The bundled Quickback CMS and Account SPAs do not import `api-types.gen.ts`. CMS is driven by `schema-registry.json`, and Account uses Better Auth plus small hand-written fetch helpers. Use `openapi.types` for your own colocated client apps.
155
158
 
156
159
  ### External viewer
157
160
 
@@ -42,15 +42,13 @@ GET /api/v1/jobs?department.in=Engineering,Design,Product
42
42
  GET /api/v1/jobs?limit=25&offset=50
43
43
  ```
44
44
 
45
- The default `limit` can be configured per-resource in your definition:
45
+ The default `limit` can be configured per-resource in your `read` definition:
46
46
 
47
47
  ```typescript
48
- crud: {
49
- list: {
50
- access: { roles: ["recruiter"] },
51
- pageSize: 25, // Default limit
52
- maxPageSize: 100, // Maximum allowed limit
53
- },
48
+ read: {
49
+ access: { roles: ["recruiter"] },
50
+ pageSize: 25, // Default limit
51
+ maxPageSize: 100, // Maximum allowed limit
54
52
  },
55
53
  ```
56
54
 
@@ -65,6 +65,16 @@ To clean up, you'd need to manually create a migration.
65
65
 
66
66
  If compilation fails with `drizzle-kit requested interactive rename input`, add explicit rename hints in your config. See [Drizzle rename prompts](/compiler/cloud-compiler/troubleshooting#drizzle-rename-prompts-in-ciheadless-compile).
67
67
 
68
+ ### Cloudflare D1 destructive migrations
69
+
70
+ Quickback now adds a D1-specific safety pass around Drizzle-generated migrations for the `cloudflare-d1` provider:
71
+
72
+ 1. **Better Auth cleanup** for retired managed tables is stripped instead of shipped as raw `DROP TABLE` SQL.
73
+ 2. **Drop-only cleanup migrations** are reordered child-first when foreign keys require it.
74
+ 3. **All D1 migration directories** generated by the compiler are replayed against SQLite during compile, so a D1-breaking migration fails before deploy.
75
+
76
+ If `quickback compile` now fails with a D1 replay error, treat that as a real migration problem instead of a deploy-time surprise. The generated SQL needs manual intervention or a schema change that Drizzle can express more safely.
77
+
68
78
  ## Runtime Issues
69
79
 
70
80
  ### 401 on all requests
@@ -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