@quickback-dev/cli 0.10.16 → 0.10.20

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 (249) hide show
  1. package/dist/commands/compile.d.ts.map +1 -1
  2. package/dist/commands/compile.js +40 -2
  3. package/dist/commands/compile.js.map +1 -1
  4. package/dist/docs/content.js +6 -6
  5. package/dist/docs/content.js.map +1 -1
  6. package/dist/index.js +1 -1
  7. package/dist/skill/SKILL.md +142 -1051
  8. package/dist/skill/agents/quickback-specialist/AGENT.md +36 -0
  9. package/dist/skill/docs/changelog.md +1192 -0
  10. package/dist/skill/docs/compiler/claude-code-skill.md +312 -0
  11. package/dist/skill/docs/compiler/cloud-compiler/authentication.md +63 -0
  12. package/dist/skill/docs/compiler/cloud-compiler/cli.md +307 -0
  13. package/dist/skill/docs/compiler/cloud-compiler/endpoints.md +78 -0
  14. package/dist/skill/docs/compiler/cloud-compiler/index.md +65 -0
  15. package/dist/skill/docs/compiler/cloud-compiler/local-compiler.md +115 -0
  16. package/dist/skill/docs/compiler/cloud-compiler/troubleshooting.md +76 -0
  17. package/dist/skill/docs/compiler/config/agents.md +144 -0
  18. package/dist/skill/docs/compiler/config/auth.md +109 -0
  19. package/dist/skill/docs/compiler/config/bindings.md +176 -0
  20. package/dist/skill/docs/compiler/config/domains.md +149 -0
  21. package/dist/skill/docs/compiler/config/index.md +419 -0
  22. package/dist/skill/docs/compiler/config/output.md +338 -0
  23. package/dist/skill/docs/compiler/config/providers.md +248 -0
  24. package/dist/skill/docs/compiler/config/security.md +255 -0
  25. package/dist/skill/docs/compiler/config/single-tenant.md +128 -0
  26. package/dist/skill/docs/compiler/config/variables.md +157 -0
  27. package/dist/skill/docs/compiler/definitions/access.md +445 -0
  28. package/dist/skill/docs/compiler/definitions/actions.md +884 -0
  29. package/dist/skill/docs/compiler/definitions/concepts.md +52 -0
  30. package/dist/skill/docs/compiler/definitions/feature.md +164 -0
  31. package/dist/skill/docs/compiler/definitions/firewall.md +285 -0
  32. package/dist/skill/docs/compiler/definitions/guards.md +241 -0
  33. package/dist/skill/docs/compiler/definitions/index.md +219 -0
  34. package/dist/skill/docs/compiler/definitions/masking.md +241 -0
  35. package/dist/skill/docs/compiler/definitions/read.md +220 -0
  36. package/dist/skill/docs/compiler/definitions/schema.md +697 -0
  37. package/dist/skill/docs/compiler/definitions/validation.md +35 -0
  38. package/dist/skill/docs/compiler/definitions/views.md +292 -0
  39. package/dist/skill/docs/compiler/getting-started/claude-code.md +126 -0
  40. package/dist/skill/docs/compiler/getting-started/full-example.md +431 -0
  41. package/dist/skill/docs/compiler/getting-started/hand-crafted.md +178 -0
  42. package/dist/skill/docs/compiler/getting-started/index.md +192 -0
  43. package/dist/skill/docs/compiler/getting-started/patterns.md +225 -0
  44. package/dist/skill/docs/compiler/getting-started/template-blog.md +280 -0
  45. package/dist/skill/docs/compiler/getting-started/template-cloudflare.md +260 -0
  46. package/dist/skill/docs/compiler/getting-started/template-empty.md +112 -0
  47. package/dist/skill/docs/compiler/getting-started/templates.md +111 -0
  48. package/dist/skill/docs/compiler/index.md +85 -0
  49. package/dist/skill/docs/compiler/targets/hono-api/cloudflare.md +94 -0
  50. package/dist/skill/docs/compiler/targets/hono-api/database/d1.md +246 -0
  51. package/dist/skill/docs/compiler/targets/hono-api/database/index.md +16 -0
  52. package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +144 -0
  53. package/dist/skill/docs/compiler/targets/hono-api/database/using-d1.md +39 -0
  54. package/dist/skill/docs/compiler/targets/hono-api/index.md +37 -0
  55. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +323 -0
  56. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +357 -0
  57. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/caching.md +105 -0
  58. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +652 -0
  59. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +224 -0
  60. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/index.md +37 -0
  61. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +203 -0
  62. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +199 -0
  63. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/views-api.md +161 -0
  64. package/dist/skill/docs/compiler/targets/index.md +47 -0
  65. package/dist/skill/docs/compiler/targets/supabase-rls/index.md +55 -0
  66. package/dist/skill/docs/compiler/targets/supabase-rls/limitations.md +48 -0
  67. package/dist/skill/docs/compiler/targets/supabase-rls/mappings.md +99 -0
  68. package/dist/skill/docs/compiler/targets/supabase-rls/setup.md +88 -0
  69. package/dist/skill/docs/compiler/troubleshooting.md +120 -0
  70. package/dist/skill/docs/index.md +77 -0
  71. package/dist/skill/docs/stack/account-ui/customization.md +378 -0
  72. package/dist/skill/docs/stack/account-ui/environment-variables.md +325 -0
  73. package/dist/skill/docs/stack/account-ui/features/admin.md +76 -0
  74. package/dist/skill/docs/stack/account-ui/features/api-keys.md +22 -0
  75. package/dist/skill/docs/stack/account-ui/features/avatars.md +37 -0
  76. package/dist/skill/docs/stack/account-ui/features/cli-authorize.md +21 -0
  77. package/dist/skill/docs/stack/account-ui/features/index.md +291 -0
  78. package/dist/skill/docs/stack/account-ui/features/organizations.md +29 -0
  79. package/dist/skill/docs/stack/account-ui/features/passkeys.md +31 -0
  80. package/dist/skill/docs/stack/account-ui/features/passwordless.md +28 -0
  81. package/dist/skill/docs/stack/account-ui/features/sessions.md +20 -0
  82. package/dist/skill/docs/stack/account-ui/hooks.md +209 -0
  83. package/dist/skill/docs/stack/account-ui/index.md +147 -0
  84. package/dist/skill/docs/stack/account-ui/library-usage.md +257 -0
  85. package/dist/skill/docs/stack/account-ui/standalone.md +149 -0
  86. package/dist/skill/docs/stack/account-ui/with-quickback.md +160 -0
  87. package/dist/skill/docs/stack/account-ui/worker.md +362 -0
  88. package/dist/skill/docs/stack/auth/api-keys.md +15 -0
  89. package/dist/skill/docs/stack/auth/device-auth.md +14 -0
  90. package/dist/skill/docs/stack/auth/index.md +64 -0
  91. package/dist/skill/docs/stack/auth/jwt-optimization.md +245 -0
  92. package/dist/skill/docs/stack/auth/plugins/aws-ses.md +127 -0
  93. package/dist/skill/docs/stack/auth/plugins/combo-auth.md +74 -0
  94. package/dist/skill/docs/stack/auth/plugins/index.md +228 -0
  95. package/dist/skill/docs/stack/auth/plugins/upgrade-anonymous.md +155 -0
  96. package/dist/skill/docs/stack/auth/security.md +455 -0
  97. package/dist/skill/docs/stack/auth/using-auth.md +39 -0
  98. package/dist/skill/docs/stack/cms/actions.md +199 -0
  99. package/dist/skill/docs/stack/cms/components.md +479 -0
  100. package/dist/skill/docs/stack/cms/connecting.md +199 -0
  101. package/dist/skill/docs/stack/cms/dashboard.md +39 -0
  102. package/dist/skill/docs/stack/cms/index.md +158 -0
  103. package/dist/skill/docs/stack/cms/inline-editing.md +136 -0
  104. package/dist/skill/docs/stack/cms/pages.md +275 -0
  105. package/dist/skill/docs/stack/cms/record-layouts.md +151 -0
  106. package/dist/skill/docs/stack/cms/schema-format.md +437 -0
  107. package/dist/skill/docs/stack/cms/schema-registry.md +200 -0
  108. package/dist/skill/docs/stack/cms/security.md +203 -0
  109. package/dist/skill/docs/stack/cms/table-views.md +142 -0
  110. package/dist/skill/docs/stack/index.md +65 -0
  111. package/dist/skill/docs/stack/queues/handlers.md +317 -0
  112. package/dist/skill/docs/stack/queues/index.md +56 -0
  113. package/dist/skill/docs/stack/queues/using-queues.md +192 -0
  114. package/dist/skill/docs/stack/realtime/durable-objects.md +488 -0
  115. package/dist/skill/docs/stack/realtime/index.md +67 -0
  116. package/dist/skill/docs/stack/realtime/using-realtime.md +211 -0
  117. package/dist/skill/docs/stack/storage/index.md +17 -0
  118. package/dist/skill/docs/stack/storage/kv.md +204 -0
  119. package/dist/skill/docs/stack/storage/r2.md +232 -0
  120. package/dist/skill/docs/stack/storage/using-kv.md +70 -0
  121. package/dist/skill/docs/stack/storage/using-r2.md +55 -0
  122. package/dist/skill/docs/stack/vector/embeddings.md +554 -0
  123. package/dist/skill/docs/stack/vector/index.md +44 -0
  124. package/dist/skill/docs/stack/vector/using-embeddings.md +186 -0
  125. package/dist/skill/docs/stack/webhooks/inbound.md +186 -0
  126. package/dist/skill/docs/stack/webhooks/index.md +36 -0
  127. package/dist/skill/docs/stack/webhooks/outbound.md +281 -0
  128. package/package.json +1 -1
  129. package/src/skill/SKILL.md +142 -1051
  130. package/src/skill/agents/quickback-specialist/AGENT.md +36 -0
  131. package/src/skill/docs/changelog.md +1192 -0
  132. package/src/skill/docs/compiler/claude-code-skill.md +312 -0
  133. package/src/skill/docs/compiler/cloud-compiler/authentication.md +63 -0
  134. package/src/skill/docs/compiler/cloud-compiler/cli.md +307 -0
  135. package/src/skill/docs/compiler/cloud-compiler/endpoints.md +78 -0
  136. package/src/skill/docs/compiler/cloud-compiler/index.md +65 -0
  137. package/src/skill/docs/compiler/cloud-compiler/local-compiler.md +115 -0
  138. package/src/skill/docs/compiler/cloud-compiler/troubleshooting.md +76 -0
  139. package/src/skill/docs/compiler/config/agents.md +144 -0
  140. package/src/skill/docs/compiler/config/auth.md +109 -0
  141. package/src/skill/docs/compiler/config/bindings.md +176 -0
  142. package/src/skill/docs/compiler/config/domains.md +149 -0
  143. package/src/skill/docs/compiler/config/index.md +419 -0
  144. package/src/skill/docs/compiler/config/output.md +338 -0
  145. package/src/skill/docs/compiler/config/providers.md +248 -0
  146. package/src/skill/docs/compiler/config/security.md +255 -0
  147. package/src/skill/docs/compiler/config/single-tenant.md +128 -0
  148. package/src/skill/docs/compiler/config/variables.md +157 -0
  149. package/src/skill/docs/compiler/definitions/access.md +445 -0
  150. package/src/skill/docs/compiler/definitions/actions.md +884 -0
  151. package/src/skill/docs/compiler/definitions/concepts.md +52 -0
  152. package/src/skill/docs/compiler/definitions/feature.md +164 -0
  153. package/src/skill/docs/compiler/definitions/firewall.md +285 -0
  154. package/src/skill/docs/compiler/definitions/guards.md +241 -0
  155. package/src/skill/docs/compiler/definitions/index.md +219 -0
  156. package/src/skill/docs/compiler/definitions/masking.md +241 -0
  157. package/src/skill/docs/compiler/definitions/read.md +220 -0
  158. package/src/skill/docs/compiler/definitions/schema.md +697 -0
  159. package/src/skill/docs/compiler/definitions/validation.md +35 -0
  160. package/src/skill/docs/compiler/definitions/views.md +292 -0
  161. package/src/skill/docs/compiler/getting-started/claude-code.md +126 -0
  162. package/src/skill/docs/compiler/getting-started/full-example.md +431 -0
  163. package/src/skill/docs/compiler/getting-started/hand-crafted.md +178 -0
  164. package/src/skill/docs/compiler/getting-started/index.md +192 -0
  165. package/src/skill/docs/compiler/getting-started/patterns.md +225 -0
  166. package/src/skill/docs/compiler/getting-started/template-blog.md +280 -0
  167. package/src/skill/docs/compiler/getting-started/template-cloudflare.md +260 -0
  168. package/src/skill/docs/compiler/getting-started/template-empty.md +112 -0
  169. package/src/skill/docs/compiler/getting-started/templates.md +111 -0
  170. package/src/skill/docs/compiler/index.md +85 -0
  171. package/src/skill/docs/compiler/targets/hono-api/cloudflare.md +94 -0
  172. package/src/skill/docs/compiler/targets/hono-api/database/d1.md +246 -0
  173. package/src/skill/docs/compiler/targets/hono-api/database/index.md +16 -0
  174. package/src/skill/docs/compiler/targets/hono-api/database/neon.md +144 -0
  175. package/src/skill/docs/compiler/targets/hono-api/database/using-d1.md +39 -0
  176. package/src/skill/docs/compiler/targets/hono-api/index.md +37 -0
  177. package/src/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +323 -0
  178. package/src/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +357 -0
  179. package/src/skill/docs/compiler/targets/hono-api/using-the-api/caching.md +105 -0
  180. package/src/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +652 -0
  181. package/src/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +224 -0
  182. package/src/skill/docs/compiler/targets/hono-api/using-the-api/index.md +37 -0
  183. package/src/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +203 -0
  184. package/src/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +199 -0
  185. package/src/skill/docs/compiler/targets/hono-api/using-the-api/views-api.md +161 -0
  186. package/src/skill/docs/compiler/targets/index.md +47 -0
  187. package/src/skill/docs/compiler/targets/supabase-rls/index.md +55 -0
  188. package/src/skill/docs/compiler/targets/supabase-rls/limitations.md +48 -0
  189. package/src/skill/docs/compiler/targets/supabase-rls/mappings.md +99 -0
  190. package/src/skill/docs/compiler/targets/supabase-rls/setup.md +88 -0
  191. package/src/skill/docs/compiler/troubleshooting.md +120 -0
  192. package/src/skill/docs/index.md +77 -0
  193. package/src/skill/docs/stack/account-ui/customization.md +378 -0
  194. package/src/skill/docs/stack/account-ui/environment-variables.md +325 -0
  195. package/src/skill/docs/stack/account-ui/features/admin.md +76 -0
  196. package/src/skill/docs/stack/account-ui/features/api-keys.md +22 -0
  197. package/src/skill/docs/stack/account-ui/features/avatars.md +37 -0
  198. package/src/skill/docs/stack/account-ui/features/cli-authorize.md +21 -0
  199. package/src/skill/docs/stack/account-ui/features/index.md +291 -0
  200. package/src/skill/docs/stack/account-ui/features/organizations.md +29 -0
  201. package/src/skill/docs/stack/account-ui/features/passkeys.md +31 -0
  202. package/src/skill/docs/stack/account-ui/features/passwordless.md +28 -0
  203. package/src/skill/docs/stack/account-ui/features/sessions.md +20 -0
  204. package/src/skill/docs/stack/account-ui/hooks.md +209 -0
  205. package/src/skill/docs/stack/account-ui/index.md +147 -0
  206. package/src/skill/docs/stack/account-ui/library-usage.md +257 -0
  207. package/src/skill/docs/stack/account-ui/standalone.md +149 -0
  208. package/src/skill/docs/stack/account-ui/with-quickback.md +160 -0
  209. package/src/skill/docs/stack/account-ui/worker.md +362 -0
  210. package/src/skill/docs/stack/auth/api-keys.md +15 -0
  211. package/src/skill/docs/stack/auth/device-auth.md +14 -0
  212. package/src/skill/docs/stack/auth/index.md +64 -0
  213. package/src/skill/docs/stack/auth/jwt-optimization.md +245 -0
  214. package/src/skill/docs/stack/auth/plugins/aws-ses.md +127 -0
  215. package/src/skill/docs/stack/auth/plugins/combo-auth.md +74 -0
  216. package/src/skill/docs/stack/auth/plugins/index.md +228 -0
  217. package/src/skill/docs/stack/auth/plugins/upgrade-anonymous.md +155 -0
  218. package/src/skill/docs/stack/auth/security.md +455 -0
  219. package/src/skill/docs/stack/auth/using-auth.md +39 -0
  220. package/src/skill/docs/stack/cms/actions.md +199 -0
  221. package/src/skill/docs/stack/cms/components.md +479 -0
  222. package/src/skill/docs/stack/cms/connecting.md +199 -0
  223. package/src/skill/docs/stack/cms/dashboard.md +39 -0
  224. package/src/skill/docs/stack/cms/index.md +158 -0
  225. package/src/skill/docs/stack/cms/inline-editing.md +136 -0
  226. package/src/skill/docs/stack/cms/pages.md +275 -0
  227. package/src/skill/docs/stack/cms/record-layouts.md +151 -0
  228. package/src/skill/docs/stack/cms/schema-format.md +437 -0
  229. package/src/skill/docs/stack/cms/schema-registry.md +200 -0
  230. package/src/skill/docs/stack/cms/security.md +203 -0
  231. package/src/skill/docs/stack/cms/table-views.md +142 -0
  232. package/src/skill/docs/stack/index.md +65 -0
  233. package/src/skill/docs/stack/queues/handlers.md +317 -0
  234. package/src/skill/docs/stack/queues/index.md +56 -0
  235. package/src/skill/docs/stack/queues/using-queues.md +192 -0
  236. package/src/skill/docs/stack/realtime/durable-objects.md +488 -0
  237. package/src/skill/docs/stack/realtime/index.md +67 -0
  238. package/src/skill/docs/stack/realtime/using-realtime.md +211 -0
  239. package/src/skill/docs/stack/storage/index.md +17 -0
  240. package/src/skill/docs/stack/storage/kv.md +204 -0
  241. package/src/skill/docs/stack/storage/r2.md +232 -0
  242. package/src/skill/docs/stack/storage/using-kv.md +70 -0
  243. package/src/skill/docs/stack/storage/using-r2.md +55 -0
  244. package/src/skill/docs/stack/vector/embeddings.md +554 -0
  245. package/src/skill/docs/stack/vector/index.md +44 -0
  246. package/src/skill/docs/stack/vector/using-embeddings.md +186 -0
  247. package/src/skill/docs/stack/webhooks/inbound.md +186 -0
  248. package/src/skill/docs/stack/webhooks/index.md +36 -0
  249. package/src/skill/docs/stack/webhooks/outbound.md +281 -0
@@ -0,0 +1,176 @@
1
+ # Custom Bindings
2
+
3
+ Quickback's compiler owns the D1/KV/R2/ASSETS/queue blocks it needs for its own features. Anything else your worker binds to — Cloudflare Email, an extra R2 bucket, a custom queue, a service binding, your own Durable Object, Workers AI, or non-secret `[vars]` — goes under the top-level `bindings` key:
4
+
5
+ ```ts
6
+ import { defineConfig, defineRuntime, defineDatabase, defineAuth } from "@quickback-dev/cli";
7
+
8
+ export default defineConfig({
9
+ name: "studio-mail",
10
+ template: "hono",
11
+ providers: {
12
+ runtime: defineRuntime("cloudflare"),
13
+ database: defineDatabase("cloudflare-d1", { splitDatabases: true }),
14
+ auth: defineAuth("better-auth"),
15
+ },
16
+ bindings: {
17
+ sendEmail: [{ name: "EMAIL" }],
18
+ r2Buckets: [
19
+ { binding: "MAIL_RAW", bucketName: "studio-mail-raw" },
20
+ { binding: "MAIL_ATTACHMENTS", bucketName: "studio-mail-attachments" },
21
+ ],
22
+ vars: {
23
+ MAIL_SENDING_DOMAIN: "studio.example.com",
24
+ },
25
+ },
26
+ });
27
+ ```
28
+
29
+ camelCase field names map 1:1 to the snake_case TOML blocks in `wrangler.toml`. Every compile regenerates `wrangler.toml` from your config, so these entries are the source of truth — no more post-compile patch scripts.
30
+
31
+ ## Fields
32
+
33
+ ### `sendEmail`
34
+
35
+ Emits `[[send_email]]`. Use when your worker calls `env.<NAME>.send(...)` via Cloudflare Email Service.
36
+
37
+ ```ts
38
+ sendEmail: [
39
+ {
40
+ name: "EMAIL",
41
+ // Optional: restrict who the worker is allowed to send to.
42
+ destinationAddress: "alerts@example.com",
43
+ allowedDestinationAddresses: ["alerts@example.com", "ops@example.com"],
44
+ },
45
+ ]
46
+ ```
47
+
48
+ ### `r2Buckets`
49
+
50
+ Emits additional `[[r2_buckets]]` blocks alongside the compiler-owned files bucket.
51
+
52
+ ```ts
53
+ r2Buckets: [
54
+ {
55
+ binding: "MAIL_RAW",
56
+ bucketName: "studio-mail-raw",
57
+ previewBucketName: "studio-mail-raw-preview", // optional
58
+ jurisdiction: "eu", // optional
59
+ },
60
+ ]
61
+ ```
62
+
63
+ ### `queueProducers` / `queueConsumers`
64
+
65
+ Emits `[[queues.producers]]` and `[[queues.consumers]]`. Useful for app-owned queues beyond the compiler's webhook/embedding queues.
66
+
67
+ ```ts
68
+ queueProducers: [
69
+ { binding: "MAIL_QUEUE", queue: "mail-send" },
70
+ ],
71
+ queueConsumers: [
72
+ {
73
+ queue: "mail-send",
74
+ maxBatchSize: 5,
75
+ maxBatchTimeout: 30,
76
+ maxRetries: 3,
77
+ maxConcurrency: 2,
78
+ deadLetterQueue: "mail-dlq",
79
+ },
80
+ ]
81
+ ```
82
+
83
+ ### `services`
84
+
85
+ Emits `[[services]]` — service bindings to sibling workers.
86
+
87
+ ```ts
88
+ services: [
89
+ { binding: "INBOUND", service: "studio-mail-inbound", environment: "production" },
90
+ ]
91
+ ```
92
+
93
+ ### `durableObjects`
94
+
95
+ Emits `[[durable_objects.bindings]]` for app-owned Durable Objects. Don't use this for Quickback's built-in `BROADCASTER` realtime DO — that one is compiler-owned.
96
+
97
+ A DO entry has two flavors: **in-worker** (the class lives in this worker — set `from`) or **cross-worker** (the class lives in another worker — set `scriptName`). The two are mutually exclusive.
98
+
99
+ ```ts
100
+ durableObjects: [
101
+ // In-worker DO — Quickback re-exports the class from src/index.ts
102
+ // and emits a [[migrations]] block. Class file lives at
103
+ // quickback/features/loops/lib/ItemStream.ts (copied verbatim to src/).
104
+ { name: "ITEM_STREAM", className: "ItemStream", from: "features/loops/lib/ItemStream" },
105
+
106
+ // Cross-worker DO — the exporting worker owns the migration; this
107
+ // worker only declares the binding.
108
+ { name: "RATE_LIMITER", className: "RateLimiter", scriptName: "rate-limit-worker" },
109
+ ]
110
+ ```
111
+
112
+ Each in-worker DO entry accepts:
113
+
114
+ | Field | Default | Notes |
115
+ |-------|---------|-------|
116
+ | `name` | — | Wrangler binding name. Becomes `c.env.<NAME>` (typed as `DurableObjectNamespace`). |
117
+ | `className` | — | The exported TypeScript class. |
118
+ | `from` | — | Module path under `src/` (no `./`, no `.ts`). The compiler copies `quickback/lib/...` and `quickback/features/<f>/lib/...` verbatim into `src/`, so use that same relative path. |
119
+ | `migrationTag` | `qb-do-${className}` | Wrangler migration tag. Stable across regenerations — **never remove or rename a deployed tag**, or wrangler will reject the deploy. |
120
+ | `useSqlite` | `true` | SQLite-backed DO storage. Set to `false` for the legacy KV-backed mode. |
121
+ | `scriptName` | — | Cross-worker only. Mutually exclusive with `from`. |
122
+
123
+ Where the class file lives: in-worker DO classes go under `quickback/lib/` or `quickback/features/<feature>/lib/` so they survive every compile (the rest of `src/` is wiped). Both copy verbatim into the generated `src/` tree.
124
+
125
+ Removing a DO from config doesn't emit a tear-down migration — that's a wrangler concern. If you need to drop a class, hand-edit the migrations array (or use a fresh script) before redeploying.
126
+
127
+ ### `vars`
128
+
129
+ Merged into the compiler's own `[vars]` table — emitting a second `[vars]` block would be invalid TOML. Values must be `string`, `number`, or `boolean`.
130
+
131
+ ```ts
132
+ vars: {
133
+ MAIL_SENDING_DOMAIN: "studio.example.com",
134
+ MAIL_MAX_ATTACHMENTS: 10,
135
+ MAIL_DEBUG: false,
136
+ }
137
+ ```
138
+
139
+ Secrets do **not** go here. Use Wrangler's secret store instead:
140
+
141
+ ```bash
142
+ wrangler secret put MAIL_INBOUND_SECRET
143
+ ```
144
+
145
+ ### `ai`
146
+
147
+ Emits a top-level `[ai]` block. Use this if you need Workers AI bound under a name different from Quickback's internal `AI`.
148
+
149
+ ```ts
150
+ ai: { binding: "USER_AI" }
151
+ ```
152
+
153
+ ## Reserved binding names
154
+
155
+ Binding names that clash with compiler-owned bindings are rejected at validation time, with the offending field path in the error message. Reserved names depend on what your config enables:
156
+
157
+ | Name | Reserved when |
158
+ |------|---------------|
159
+ | `AUTH_DB`, `DB` | `splitDatabases: true` (default) |
160
+ | `DATABASE` | `splitDatabases: false` |
161
+ | `AUDIT_DB` | always (cross-tenant unsafe-action audit) |
162
+ | `WEBHOOKS_DB`, `WEBHOOKS_QUEUE` | a webhooks binding is configured |
163
+ | `KV` | always |
164
+ | `R2_BUCKET`, `FILES_DB` | `fileStorage: defineFileStorage("cloudflare-r2")` |
165
+ | `VECTORIZE` | a Vectorize index is configured |
166
+ | `BROADCASTER` | realtime is enabled |
167
+ | `EMAIL` | `email: { provider: "cloudflare" }` |
168
+ | `ASSETS` | `cms: true` or `account: true` |
169
+ | `AI`, `EMBEDDINGS_QUEUE` | embeddings are configured |
170
+
171
+ Pick a different name — the generated `env` on the handler side takes whatever binding you pick.
172
+
173
+ ## See also
174
+
175
+ - [Environment Variables](/compiler/config/variables) — the non-secret `[vars]` / secret split
176
+ - [Providers](/compiler/config/providers) — runtime / database / auth selection
@@ -0,0 +1,149 @@
1
+ # Multi-Domain Architecture
2
+
3
+ A single Quickback-compiled Cloudflare Worker can serve your API, CMS, Account UI, and Admin panel on separate custom domains. The compiler generates hostname-based routing so each domain serves the right content.
4
+
5
+ ## How It Works
6
+
7
+ When you configure custom domains for CMS, Account, or Admin, the compiler:
8
+
9
+ 1. Adds `custom_domain` routes to `wrangler.toml`
10
+ 2. Generates hostname-based middleware in the Worker
11
+ 3. Auto-configures cross-subdomain cookies for shared authentication
12
+ 4. Auto-infers a unified `quickback.{baseDomain}` fallback domain
13
+
14
+ All five domains point to the **same Worker** — there's only one deployment.
15
+
16
+ ## Domain Types
17
+
18
+ | Domain | Config | Serves | API Routes |
19
+ |--------|--------|--------|-----------|
20
+ | `api.example.com` | `providers.runtime.config.routes` | API only | All |
21
+ | `cms.example.com` | `cms: { domain }` | CMS SPA | Blocked (404) |
22
+ | `auth.example.com` | `account: { domain }` | Account SPA | Pass-through |
23
+ | `admin.example.com` | `account: { adminDomain }` | Account SPA | Pass-through |
24
+ | `quickback.example.com` | Auto-inferred | Everything | All |
25
+
26
+ ### CMS Domain
27
+
28
+ Serves the CMS SPA at root (`/`). API routes (`/api/`, `/auth/`, `/admin/`, `/storage/`, `/health`) return 404 — preventing direct API access on the CMS domain.
29
+
30
+ ### Account Domain
31
+
32
+ Serves the Account SPA at root (`/`). API and auth routes pass through to the Worker so authentication flows work directly on this domain.
33
+
34
+ ### Admin Domain
35
+
36
+ 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
+ ### Unified Domain
39
+
40
+ 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`.
41
+
42
+ On this domain, **everything is available** on a single origin:
43
+
44
+ | Path | Content |
45
+ |------|---------|
46
+ | `/` | Redirects to `/cms/` |
47
+ | `/cms/` | CMS SPA |
48
+ | `/account/` | Account SPA |
49
+ | `/api/v1/...` | API routes |
50
+ | `/auth/...` | Auth routes |
51
+ | `/admin/...` | Admin API routes |
52
+ | `/storage/...` | File storage |
53
+ | `/health` | Health check |
54
+ | `/openapi.json` | OpenAPI spec |
55
+
56
+ The unified domain is useful for development and debugging. You can override it with an explicit `domain` field in your config.
57
+
58
+ ## Configuration
59
+
60
+ ```typescript title="quickback/quickback.config.ts"
61
+ export default {
62
+ name: "my-app",
63
+ template: "hono",
64
+ cms: { domain: "cms.example.com", access: "admin" },
65
+ account: {
66
+ domain: "auth.example.com",
67
+ adminDomain: "admin.example.com",
68
+ name: "My App",
69
+ auth: { password: true, admin: true },
70
+ },
71
+ trustedOrigins: [
72
+ "https://auth.example.com",
73
+ "https://admin.example.com",
74
+ "https://cms.example.com",
75
+ ],
76
+ providers: {
77
+ runtime: { name: "cloudflare", config: {
78
+ routes: [{ pattern: "api.example.com", custom_domain: true }],
79
+ }},
80
+ // ...database, auth
81
+ },
82
+ };
83
+ ```
84
+
85
+ This generates the following `wrangler.toml` routes:
86
+
87
+ ```toml
88
+ routes = [
89
+ { pattern = "api.example.com", custom_domain = true },
90
+ { pattern = "cms.example.com", custom_domain = true },
91
+ { pattern = "auth.example.com", custom_domain = true },
92
+ { pattern = "admin.example.com", custom_domain = true },
93
+ { pattern = "quickback.example.com", custom_domain = true }
94
+ ]
95
+ ```
96
+
97
+ ## Cross-Subdomain Authentication
98
+
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:
100
+
101
+ - Sets `crossSubDomainCookies: { enabled: true, domain: '.example.com' }`
102
+ - Sets `sameSite: 'none'` and `secure: true` on auth cookies
103
+
104
+ This means a user who logs in on `auth.example.com` is automatically authenticated on `cms.example.com` and `admin.example.com` — no additional setup needed.
105
+
106
+ > **Automatic Detection**
107
+ >
108
+ > Cross-subdomain cookies are configured automatically. You only need to set them manually if your domains don't share a common parent (e.g., `auth.myapp.com` + `cms.different.com`).
109
+
110
+
111
+ ## Compile-Time Feature Gating
112
+
113
+ When the compiler builds the Account SPA, it excludes route files for disabled features **before** the Vite build. This means disabled features never appear in the JavaScript bundle.
114
+
115
+ | Feature Flag | Routes Excluded When `false` |
116
+ |-------------|------------------------------|
117
+ | `auth.organizations` | Dashboard, organization CRUD, org switching (`$slug`) |
118
+ | `auth.passkey` | Passkey management and setup |
119
+ | `auth.admin` | Admin panel routes |
120
+
121
+ This keeps bundle sizes minimal and prevents dead code in production. Users can't access disabled features even if they navigate to the URL directly — the routes don't exist in the build.
122
+
123
+ ## Hostname Routing Details
124
+
125
+ The compiler generates middleware that checks `new URL(c.req.url).hostname` on every request:
126
+
127
+ **CMS domain** — Blocks API routes with 404. All other paths are mapped to the `/cms/` asset prefix and served with SPA fallback to `/cms/index.html`.
128
+
129
+ **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
+
131
+ **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
+
133
+ ## Without Custom Domains
134
+
135
+ If you enable `cms` and `account` without custom domains, everything is served on a single domain:
136
+
137
+ - CMS at `/cms/` (root `/` redirects to `/cms/`)
138
+ - Account UI at `/account/`
139
+ - API at `/api/v1/`
140
+ - Auth at `/auth/`
141
+
142
+ This is the simplest setup — no DNS configuration needed, no cross-subdomain cookies. Auth cookies work naturally because everything is same-origin.
143
+
144
+ ## See Also
145
+
146
+ - [Configuration](/compiler/config) — CMS and Account config options
147
+ - [Output Structure](/compiler/config/output) — Generated file and directory layout
148
+ - [CMS](/stack/cms) — Schema-driven admin interface
149
+ - [Account UI](/stack/account-ui) — Authentication and account management