@quickback-dev/cli 0.66.20 → 0.66.22
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/commands/migrate.js +2 -2
- package/dist/commands/migrate.js.map +1 -1
- package/dist/index.js +1 -1
- package/dist/lib/migrations/drizzle-prompts.d.ts +2 -0
- package/dist/lib/migrations/drizzle-prompts.d.ts.map +1 -1
- package/dist/lib/migrations/drizzle-prompts.js +11 -0
- package/dist/lib/migrations/drizzle-prompts.js.map +1 -1
- package/dist/lib/migrations/file-envelopes.d.ts.map +1 -1
- package/dist/lib/migrations/file-envelopes.js +21 -51
- package/dist/lib/migrations/file-envelopes.js.map +1 -1
- package/dist/lib/migrations/prompt-runner.d.ts.map +1 -1
- package/dist/lib/migrations/prompt-runner.js +6 -1
- package/dist/lib/migrations/prompt-runner.js.map +1 -1
- package/dist/skill/docs/api/actions.md +13 -6
- package/dist/skill/docs/api/batch-operations.md +6 -2
- package/dist/skill/docs/api/crud.md +72 -9
- package/dist/skill/docs/api/errors.md +86 -6
- package/dist/skill/docs/api/openapi.md +1 -1
- package/dist/skill/docs/api/query-params.md +8 -7
- package/dist/skill/docs/api/typescript.md +196 -0
- package/dist/skill/docs/configure/index.md +36 -2
- package/dist/skill/docs/configure/providers.md +37 -9
- package/dist/skill/docs/define/actions/defining.md +16 -7
- package/dist/skill/docs/define/actions/record-and-standalone.md +10 -0
- package/dist/skill/docs/define/actions/scoped-db.md +18 -3
- package/dist/skill/docs/define/changesets.md +2 -0
- package/dist/skill/docs/define/firewall.md +39 -0
- package/dist/skill/docs/define/guards.md +7 -2
- package/dist/skill/docs/define/masking.md +14 -0
- package/dist/skill/docs/define/read.md +3 -0
- package/dist/skill/docs/define/relationships.md +9 -0
- package/dist/skill/docs/define/schema.md +14 -10
- package/dist/skill/docs/define/transitions.md +12 -5
- package/dist/skill/docs/define/triggers.md +2 -1
- package/dist/skill/docs/index.md +1 -0
- package/dist/skill/docs/platform/auth/plugins/agent-auth.md +1 -1
- package/dist/skill/docs/platform/database/neon.md +110 -30
- package/dist/skill/docs/platform/payments/index.md +1 -1
- package/dist/skill/docs/start/frontend.md +278 -0
- package/dist/skill/docs/start/index.md +1 -0
- package/dist/skill/docs/tooling/cli.md +28 -7
- package/dist/skill/docs/tooling/cloud-compiler/troubleshooting.md +6 -0
- package/dist/skill/docs/tooling/output.md +42 -11
- package/dist/skill/docs/tooling/troubleshooting.md +67 -0
- package/dist/skill/docs/ui/admin/actions.md +6 -2
- package/dist/skill/docs/ui/admin/index.md +1 -1
- package/dist/skill/docs/ui/admin/inline-editing.md +6 -2
- package/dist/skill/docs/ui/admin/schema-format.md +74 -36
- package/dist/skill/docs/ui/admin/schema-registry.md +22 -9
- package/dist/skill/docs/ui/admin/security.md +2 -2
- package/dist/skill/docs/ui/components/action-dialog.md +62 -0
- package/dist/skill/docs/ui/components/auth.md +90 -0
- package/dist/skill/docs/ui/components/index.md +48 -0
- package/dist/skill/docs/ui/components/install.md +118 -0
- package/dist/skill/docs/ui/components/quickback-provider.md +123 -0
- package/dist/skill/docs/ui/components/resource-form.md +80 -0
- package/dist/skill/docs/ui/components/resource-table.md +46 -0
- package/package.json +1 -1
- package/src/skill/docs/api/actions.md +13 -6
- package/src/skill/docs/api/batch-operations.md +6 -2
- package/src/skill/docs/api/crud.md +72 -9
- package/src/skill/docs/api/errors.md +86 -6
- package/src/skill/docs/api/openapi.md +1 -1
- package/src/skill/docs/api/query-params.md +8 -7
- package/src/skill/docs/api/typescript.md +196 -0
- package/src/skill/docs/configure/index.md +36 -2
- package/src/skill/docs/configure/providers.md +37 -9
- package/src/skill/docs/define/actions/defining.md +16 -7
- package/src/skill/docs/define/actions/record-and-standalone.md +10 -0
- package/src/skill/docs/define/actions/scoped-db.md +18 -3
- package/src/skill/docs/define/changesets.md +2 -0
- package/src/skill/docs/define/firewall.md +39 -0
- package/src/skill/docs/define/guards.md +7 -2
- package/src/skill/docs/define/masking.md +14 -0
- package/src/skill/docs/define/read.md +3 -0
- package/src/skill/docs/define/relationships.md +9 -0
- package/src/skill/docs/define/schema.md +14 -10
- package/src/skill/docs/define/transitions.md +12 -5
- package/src/skill/docs/define/triggers.md +2 -1
- package/src/skill/docs/index.md +1 -0
- package/src/skill/docs/platform/auth/plugins/agent-auth.md +1 -1
- package/src/skill/docs/platform/database/neon.md +110 -30
- package/src/skill/docs/platform/payments/index.md +1 -1
- package/src/skill/docs/start/frontend.md +278 -0
- package/src/skill/docs/start/index.md +1 -0
- package/src/skill/docs/tooling/cli.md +28 -7
- package/src/skill/docs/tooling/cloud-compiler/troubleshooting.md +6 -0
- package/src/skill/docs/tooling/output.md +42 -11
- package/src/skill/docs/tooling/troubleshooting.md +67 -0
- package/src/skill/docs/ui/admin/actions.md +6 -2
- package/src/skill/docs/ui/admin/index.md +1 -1
- package/src/skill/docs/ui/admin/inline-editing.md +6 -2
- package/src/skill/docs/ui/admin/schema-format.md +74 -36
- package/src/skill/docs/ui/admin/schema-registry.md +22 -9
- package/src/skill/docs/ui/admin/security.md +2 -2
- package/src/skill/docs/ui/components/action-dialog.md +62 -0
- package/src/skill/docs/ui/components/auth.md +90 -0
- package/src/skill/docs/ui/components/index.md +48 -0
- package/src/skill/docs/ui/components/install.md +118 -0
- package/src/skill/docs/ui/components/quickback-provider.md +123 -0
- package/src/skill/docs/ui/components/resource-form.md +80 -0
- package/src/skill/docs/ui/components/resource-table.md +46 -0
|
@@ -0,0 +1,278 @@
|
|
|
1
|
+
# Build a frontend
|
|
2
|
+
|
|
3
|
+
This guide builds a React app that lists, creates, edits, and closes jobs
|
|
4
|
+
against your API. It uses the [components](/ui/components) (shadcn registry
|
|
5
|
+
items) on top of the emitted [fetch client](/api/typescript#fetch-client).
|
|
6
|
+
|
|
7
|
+
```
|
|
8
|
+
my-app/
|
|
9
|
+
├── quickback.config.ts
|
|
10
|
+
├── quickback/features/jobs/ # your API definitions
|
|
11
|
+
├── src/ # generated Worker (never edit)
|
|
12
|
+
└── web/ # your React app (you own it)
|
|
13
|
+
└── src/lib/
|
|
14
|
+
├── quickback.client.ts # emitted every compile
|
|
15
|
+
└── quickback.gen.ts # emitted every compile
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
## 1. Scaffold the app
|
|
19
|
+
|
|
20
|
+
From the project root, create a Vite app with a shadcn **base-ui** style. The
|
|
21
|
+
components don't support Radix styles.
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
npx shadcn@latest init -t vite -b base -p nova -n web
|
|
25
|
+
cd web && npm install better-auth && cd ..
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
## 2. Emit the client into it
|
|
29
|
+
|
|
30
|
+
Add three keys to the scaffolded config and keep everything else:
|
|
31
|
+
|
|
32
|
+
```typescript
|
|
33
|
+
// quickback.config.ts
|
|
34
|
+
import { defineConfig } from "@quickback/compiler";
|
|
35
|
+
|
|
36
|
+
export default defineConfig({
|
|
37
|
+
// …name, providers, etc. from the scaffold
|
|
38
|
+
types: { output: "web/src/lib/quickback.gen.ts" },
|
|
39
|
+
client: "web/src/lib/quickback.client.ts",
|
|
40
|
+
// The components read GET /api/v1/schema. Its default ("sysadmin")
|
|
41
|
+
// would 403 every other user; "member" admits organization members.
|
|
42
|
+
schemaRegistry: { access: "member" },
|
|
43
|
+
});
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
The client imports its types from the first `types` output, so both files
|
|
47
|
+
live inside `web/`.
|
|
48
|
+
|
|
49
|
+
## 3. Define the API
|
|
50
|
+
|
|
51
|
+
```typescript
|
|
52
|
+
// quickback/features/jobs/jobs.ts
|
|
53
|
+
import { feature, q } from "@quickback/compiler";
|
|
54
|
+
|
|
55
|
+
export default feature("jobs", {
|
|
56
|
+
columns: {
|
|
57
|
+
id: q.id(),
|
|
58
|
+
title: q.text().required(),
|
|
59
|
+
department: q.text().required(),
|
|
60
|
+
status: q.text().default("open").required(),
|
|
61
|
+
salaryMin: q.int().optional(),
|
|
62
|
+
organizationId: q.scope("organization"),
|
|
63
|
+
...q.audit(),
|
|
64
|
+
...q.softDelete(),
|
|
65
|
+
},
|
|
66
|
+
guards: {
|
|
67
|
+
createable: ["title", "department", "salaryMin"],
|
|
68
|
+
updatable: ["title", "department", "salaryMin"],
|
|
69
|
+
protected: { status: ["close"] },
|
|
70
|
+
},
|
|
71
|
+
read: { access: { roles: ["owner", "admin", "member"] } },
|
|
72
|
+
create: { access: { roles: ["owner", "admin"] } },
|
|
73
|
+
update: { access: { roles: ["owner", "admin"] } },
|
|
74
|
+
delete: { access: { roles: ["owner", "admin"] }, mode: "soft" },
|
|
75
|
+
});
|
|
76
|
+
|
|
77
|
+
// quickback/features/jobs/actions/close.ts
|
|
78
|
+
import { z } from "zod";
|
|
79
|
+
import { eq } from "drizzle-orm";
|
|
80
|
+
import { defineAction, jobs } from "../.quickback/define-action";
|
|
81
|
+
|
|
82
|
+
export default defineAction({
|
|
83
|
+
description: "Close the job to new applications",
|
|
84
|
+
input: z.object({ reason: z.string().optional() }),
|
|
85
|
+
access: { roles: ["owner", "admin"], record: { status: { equals: "open" } } },
|
|
86
|
+
async execute({ db, record }) {
|
|
87
|
+
const [row] = await db
|
|
88
|
+
.update(jobs)
|
|
89
|
+
.set({ status: "closed" })
|
|
90
|
+
.where(eq(jobs.id, record.id))
|
|
91
|
+
.returning();
|
|
92
|
+
return row;
|
|
93
|
+
},
|
|
94
|
+
});
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
`status` is `protected`: the form shows it disabled, and only `close` can
|
|
98
|
+
change it.
|
|
99
|
+
|
|
100
|
+
```bash
|
|
101
|
+
quickback build # writes src/ and web/src/lib/quickback.{client,gen}.ts
|
|
102
|
+
npm run dev # API on http://localhost:8787
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
## 4. Add the components
|
|
106
|
+
|
|
107
|
+
In `web/components.json`, add the registry:
|
|
108
|
+
|
|
109
|
+
```json
|
|
110
|
+
{
|
|
111
|
+
"registries": {
|
|
112
|
+
"@quickback": "https://docs.quickback.dev/r/{style}/{name}.json"
|
|
113
|
+
}
|
|
114
|
+
}
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
```bash
|
|
118
|
+
cd web
|
|
119
|
+
npx shadcn add @quickback/resource-table @quickback/resource-form @quickback/action-dialog
|
|
120
|
+
npx shadcn add dialog
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
This installs `quickback-provider` too, since every item depends on it.
|
|
124
|
+
|
|
125
|
+
## 5. Sign in and render
|
|
126
|
+
|
|
127
|
+
```tsx
|
|
128
|
+
// web/src/lib/api.ts
|
|
129
|
+
import { createAuthClient } from "better-auth/react"
|
|
130
|
+
import { organizationClient } from "better-auth/client/plugins"
|
|
131
|
+
import { createClient } from "@/lib/quickback.client"
|
|
132
|
+
|
|
133
|
+
const baseURL = import.meta.env.VITE_API_URL ?? "http://localhost:8787"
|
|
134
|
+
|
|
135
|
+
export const auth = createAuthClient({ baseURL, basePath: "/auth/v1", plugins: [organizationClient()] })
|
|
136
|
+
export const client = createClient({ baseUrl: baseURL })
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
```tsx
|
|
140
|
+
// web/src/App.tsx
|
|
141
|
+
import { useState } from "react"
|
|
142
|
+
import { auth, client } from "@/lib/api"
|
|
143
|
+
import { buttonVariants } from "@/components/ui/button"
|
|
144
|
+
import { Dialog, DialogContent, DialogHeader, DialogTitle } from "@/components/ui/dialog"
|
|
145
|
+
import { QuickbackProvider } from "@/components/quickback-provider"
|
|
146
|
+
import { ResourceTable } from "@/components/resource-table"
|
|
147
|
+
import { ResourceForm } from "@/components/resource-form"
|
|
148
|
+
import { ActionDialog } from "@/components/action-dialog"
|
|
149
|
+
|
|
150
|
+
export default function App() {
|
|
151
|
+
const session = auth.useSession()
|
|
152
|
+
const member = auth.useActiveMember()
|
|
153
|
+
if (session.isPending) return null
|
|
154
|
+
if (!session.data) return <SignIn />
|
|
155
|
+
// Roles are a UI hint (masking, hiding Delete); the API stays authoritative.
|
|
156
|
+
return (
|
|
157
|
+
<QuickbackProvider client={client} roles={member.data ? [member.data.role] : undefined}>
|
|
158
|
+
<Jobs />
|
|
159
|
+
</QuickbackProvider>
|
|
160
|
+
)
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
function SignIn() {
|
|
164
|
+
const [error, setError] = useState<string>()
|
|
165
|
+
async function submit(form: FormData) {
|
|
166
|
+
const res = await auth.signIn.email({
|
|
167
|
+
email: String(form.get("email")),
|
|
168
|
+
password: String(form.get("password")),
|
|
169
|
+
})
|
|
170
|
+
if (res.error) return setError(res.error.message)
|
|
171
|
+
// Tables are firewalled to the active organization — pick one.
|
|
172
|
+
const orgs = await auth.organization.list()
|
|
173
|
+
const org = orgs.data?.[0] ?? (await auth.organization.create({ name: "Acme", slug: `acme-${Date.now()}` })).data
|
|
174
|
+
if (org) await auth.organization.setActive({ organizationId: org.id })
|
|
175
|
+
}
|
|
176
|
+
return (
|
|
177
|
+
<form action={submit} className="mx-auto flex max-w-sm flex-col gap-2 p-6">
|
|
178
|
+
<label>Email <input name="email" type="email" required /></label>
|
|
179
|
+
<label>Password <input name="password" type="password" required /></label>
|
|
180
|
+
<button className={buttonVariants()}>Sign in</button>
|
|
181
|
+
{error && <p role="alert">{error}</p>}
|
|
182
|
+
</form>
|
|
183
|
+
)
|
|
184
|
+
}
|
|
185
|
+
|
|
186
|
+
function Jobs() {
|
|
187
|
+
const [editing, setEditing] = useState<string | null>() // undefined closed, null create
|
|
188
|
+
const [closing, setClosing] = useState<string>()
|
|
189
|
+
const done = () => setEditing(undefined)
|
|
190
|
+
|
|
191
|
+
return (
|
|
192
|
+
<main className="mx-auto flex max-w-5xl flex-col gap-4 p-6">
|
|
193
|
+
<button className={buttonVariants()} onClick={() => setEditing(null)}>New job</button>
|
|
194
|
+
|
|
195
|
+
<ResourceTable
|
|
196
|
+
table="jobs"
|
|
197
|
+
onRowClick={(row) => setEditing(String(row.id))}
|
|
198
|
+
rowActions={(row) => (
|
|
199
|
+
<button className={buttonVariants({ variant: "outline", size: "sm" })} onClick={() => setClosing(String(row.id))}>
|
|
200
|
+
Close
|
|
201
|
+
</button>
|
|
202
|
+
)}
|
|
203
|
+
/>
|
|
204
|
+
|
|
205
|
+
<Dialog open={editing !== undefined} onOpenChange={(open) => !open && done()}>
|
|
206
|
+
<DialogContent>
|
|
207
|
+
<DialogHeader><DialogTitle>{editing ? "Edit job" : "New job"}</DialogTitle></DialogHeader>
|
|
208
|
+
{editing !== undefined && (
|
|
209
|
+
<ResourceForm table="jobs" id={editing ?? undefined} onSuccess={done} onCancel={done} onDeleted={done} />
|
|
210
|
+
)}
|
|
211
|
+
</DialogContent>
|
|
212
|
+
</Dialog>
|
|
213
|
+
|
|
214
|
+
<ActionDialog
|
|
215
|
+
table="jobs"
|
|
216
|
+
action="close"
|
|
217
|
+
id={closing}
|
|
218
|
+
open={closing !== undefined}
|
|
219
|
+
onOpenChange={(open) => !open && setClosing(undefined)}
|
|
220
|
+
/>
|
|
221
|
+
</main>
|
|
222
|
+
)
|
|
223
|
+
}
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
Create an account first. Either `POST /auth/v1/sign-up/email` as in the
|
|
227
|
+
[quickstart](/start/quickstart#test-your-api), or add a sign-up form with
|
|
228
|
+
`auth.signUp.email`. Then run the app:
|
|
229
|
+
|
|
230
|
+
```bash
|
|
231
|
+
npm run dev # http://localhost:5173
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
The browser sends the Better Auth session cookie with every request.
|
|
235
|
+
`http://localhost:5173` is a trusted origin by default until the project has
|
|
236
|
+
a production domain, so writes pass the CSRF check. See
|
|
237
|
+
[Auth](/ui/components/auth) for the rules, and for bearer tokens in React
|
|
238
|
+
Native.
|
|
239
|
+
|
|
240
|
+
What you get for free:
|
|
241
|
+
|
|
242
|
+
- **Only permitted fields.** The form shows `guards.createable` /
|
|
243
|
+
`updatable`, and `status` stays locked.
|
|
244
|
+
- **Errors inline.** A guard or validation `400` shows under its field. A
|
|
245
|
+
`403` shows the problem's `detail`.
|
|
246
|
+
- **Close only when open.** The action's `record` precondition runs on the
|
|
247
|
+
server. Closing a closed job shows the rejection in the dialog.
|
|
248
|
+
- **Role-aware.** Delete and `close` both require `owner` or `admin`. A
|
|
249
|
+
`member` therefore sees no Delete button, and the Close dialog shows a role
|
|
250
|
+
message instead of its form. The API enforces the same rules either way.
|
|
251
|
+
|
|
252
|
+
## 6. Ship it on the same Worker
|
|
253
|
+
|
|
254
|
+
Serve the built app from the API's own Worker. It shares the API's origin, so
|
|
255
|
+
it needs no CORS setup, and its hostname is trusted automatically.
|
|
256
|
+
|
|
257
|
+
```bash
|
|
258
|
+
cd web && VITE_API_URL=https://app.example.com npm run build && cd ..
|
|
259
|
+
rm -rf quickback/apps/web && cp -r web/dist quickback/apps/web
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
```typescript
|
|
263
|
+
// quickback.config.ts — add alongside the rest
|
|
264
|
+
apps: {
|
|
265
|
+
web: { domain: "app.example.com" },
|
|
266
|
+
},
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
`quickback build` copies `quickback/apps/web/` into the Worker's assets, then
|
|
270
|
+
`quickback deploy` ships both. See
|
|
271
|
+
[App domains](/configure/domains#app-domains). To host the app elsewhere
|
|
272
|
+
instead, add its origin to [`trustedOrigins`](/configure#trusted-origins).
|
|
273
|
+
|
|
274
|
+
## Next
|
|
275
|
+
|
|
276
|
+
- [Components](/ui/components): every prop and hook
|
|
277
|
+
- [Fetch client](/api/typescript#fetch-client): typed calls beyond the components
|
|
278
|
+
- [Query parameters](/api/query-params): what `useList` params map to
|
|
@@ -36,6 +36,7 @@ quickback/
|
|
|
36
36
|
- **[Define](/define)** — the DSL: schema, the security pillars, reads, writes, actions
|
|
37
37
|
- **[Configure](/configure)** — `quickback.config.ts`, providers, domains, bindings
|
|
38
38
|
- **[Use the API](/api)** — what the generated endpoints look like
|
|
39
|
+
- **[Build a frontend](/start/frontend)** — a React app on your API with the typed client and shadcn components
|
|
39
40
|
|
|
40
41
|
The rest of this page is the vocabulary the other pages assume.
|
|
41
42
|
|
|
@@ -135,7 +135,29 @@ generated typing surfaces:
|
|
|
135
135
|
surface. `import { feature, q, defineTable, defineConfig } from
|
|
136
136
|
"@quickback/compiler"` resolves in table files and `quickback.config.ts`,
|
|
137
137
|
so a bad builder call or an unknown resource-config key is a type error at
|
|
138
|
-
the desk, not a compile-round-trip later.
|
|
138
|
+
the desk, not a compile-round-trip later. `services/` files' `import {
|
|
139
|
+
defineQueue } from "quickback"` resolves to the same surface, and provider
|
|
140
|
+
entries type-check in both forms the build accepts — `defineDatabase(...)`
|
|
141
|
+
or the literal `{ name: "neon", config: { … } }`.
|
|
142
|
+
|
|
143
|
+
The check resolves imports the way the build does, so a clean check is not
|
|
144
|
+
undone by the compile:
|
|
145
|
+
|
|
146
|
+
- **Named table imports from feature files** —
|
|
147
|
+
`import { mailboxes } from "../../mailboxes/mailboxes"` in an action, a
|
|
148
|
+
`lib/` file, or a queue handler. A `feature()` file has only a default
|
|
149
|
+
export; the build points that path at the generated table module, and
|
|
150
|
+
`quickback/.quickback/feature-tables.d.ts` gives the check the same named
|
|
151
|
+
export, typed from the generated schema.
|
|
152
|
+
- **Queue handlers' dynamic imports** — `await import("./features/…")` is
|
|
153
|
+
written against the generated `src/` (the handler body is inlined into
|
|
154
|
+
`src/queue-consumer.ts`); the tsconfig's `rootDirs` resolves it there too.
|
|
155
|
+
- **Service handler contexts** — queue, schedule and email handlers get the
|
|
156
|
+
`db`, `env` and `services` the generated runners pass them: your project's
|
|
157
|
+
Drizzle handle, `CloudflareBindings` and `Services`
|
|
158
|
+
(`quickback/.quickback/service-runtime.d.ts`). A wrong column on a
|
|
159
|
+
`db.select()` result or an undeclared binding is a check error, as it is in
|
|
160
|
+
the build.
|
|
139
161
|
|
|
140
162
|
No compile, no server: this is your editor's view of the source, on demand.
|
|
141
163
|
|
|
@@ -145,11 +167,10 @@ Exit codes: `0` clean · `1` type errors · `2` setup missing. A fresh clone
|
|
|
145
167
|
the check resolves against. Re-run `quickback build` after schema changes so
|
|
146
168
|
they track your tables.
|
|
147
169
|
|
|
148
|
-
|
|
149
|
-
(`import { tickets } from "
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
`quickback migrate helper-imports` rewrites the safe cases for you.
|
|
170
|
+
Within a feature, the single helper import
|
|
171
|
+
(`import { defineAction, tickets } from "../.quickback/define-action"`) is
|
|
172
|
+
still the tidier form; `quickback migrate helper-imports` rewrites the safe
|
|
173
|
+
cases for you.
|
|
153
174
|
|
|
154
175
|
### Synchronize Managed Columns
|
|
155
176
|
|
|
@@ -190,7 +211,7 @@ quickback migrate helper-imports [--dry-run] # single typed helper import
|
|
|
190
211
|
|
|
191
212
|
```ts
|
|
192
213
|
import { defineAction } from "../.quickback/define-action";
|
|
193
|
-
import { applications } from "../applications"; //
|
|
214
|
+
import { applications } from "../applications"; // second import, same feature
|
|
194
215
|
```
|
|
195
216
|
|
|
196
217
|
— to the single typed import the helpers are designed for:
|
|
@@ -94,6 +94,12 @@ A failed generate or postprocessor leaves existing migration history untouched.
|
|
|
94
94
|
Do not use raw `drizzle-kit generate` as an equivalent workaround for an auth
|
|
95
95
|
upgrade: it skips Quickback's OAuth client backfills and resource-grant cleanup.
|
|
96
96
|
|
|
97
|
+
`drizzle-kit exited after answering a rename prompt without writing a migration`
|
|
98
|
+
means the generator process ended mid-prompt. A prompt only appears when there
|
|
99
|
+
is a schema diff, so this is always a failure: nothing was written and the
|
|
100
|
+
existing history is untouched. Re-run the build; if it repeats, report it with
|
|
101
|
+
the Drizzle output from the error.
|
|
102
|
+
|
|
97
103
|
## `Critical command failed: Generate features database migrations`
|
|
98
104
|
|
|
99
105
|
drizzle-kit could not load the generated **features** schema. The usual cause on
|
|
@@ -50,8 +50,10 @@ src/
|
|
|
50
50
|
# Authored-tree typing (regenerated on every compile, gitignored)
|
|
51
51
|
quickback/tsconfig.json # Typechecks the authored quickback/ tree (`quickback check`)
|
|
52
52
|
quickback/.quickback/
|
|
53
|
-
|
|
54
|
-
|
|
53
|
+
├── compiler/ # @quickback/compiler declaration snapshot — resolves
|
|
54
|
+
│ └── … # `import { feature, q, defineTable } from "@quickback/compiler"`
|
|
55
|
+
├── feature-tables.d.ts # Named table exports of feature() files, typed from the generated schema
|
|
56
|
+
└── service-runtime.d.ts # db / env / services types for queue, schedule and email handlers (when any exist)
|
|
55
57
|
quickback/features/{feature}/
|
|
56
58
|
└── .quickback/
|
|
57
59
|
└── define-action.ts # Authored-tree twin of the typed helper below
|
|
@@ -257,6 +259,16 @@ projects acquire build and deployment fixes without losing unrelated tooling.
|
|
|
257
259
|
|
|
258
260
|
These files are generated only when the corresponding features are configured:
|
|
259
261
|
|
|
262
|
+
### TypeScript artifacts
|
|
263
|
+
|
|
264
|
+
| File | Emitted | Config |
|
|
265
|
+
|------|---------|--------|
|
|
266
|
+
| `quickback.gen.ts` | By default | [`types`](/api/typescript#configuration) |
|
|
267
|
+
| `api-types.gen.ts` | By default | [`openapi.types`](/api/openapi) |
|
|
268
|
+
| `quickback.client.ts` | Opt-in | [`client`](/api/typescript#fetch-client) — a zero-dependency `fetch` client typed by `quickback.gen.ts`; the [components](/ui/components) build on it |
|
|
269
|
+
|
|
270
|
+
All three sit outside `src/`, and each accepts a custom path or a list of paths.
|
|
271
|
+
|
|
260
272
|
### Database provider setup files
|
|
261
273
|
|
|
262
274
|
Every compile emits an environment example named for the configured provider.
|
|
@@ -410,6 +422,15 @@ Set `compiler.securityContracts.report.signature.required: true` to fail compila
|
|
|
410
422
|
|
|
411
423
|
The report names the compiler that produced it twice: `compilerVersion` is the semver, and `compilerBuildId` is `<version>@<gitSha>@<builtAt>` — the same string the compiler's `/health` endpoint reports as `buildId`. The semver is a floor that can serve several hosted builds, so a drift tripwire should pin on `compilerBuildId`, not `compilerVersion`.
|
|
412
424
|
|
|
425
|
+
### Data Remediation Report
|
|
426
|
+
|
|
427
|
+
`reports/data-remediation.sql` is emitted when the project has something to check. It is **read-only as emitted** — every statement is a `SELECT`, and the compiler never runs it:
|
|
428
|
+
|
|
429
|
+
- **SQLite / D1:** a count of rows whose `.defaultNow()` or audit timestamp holds the `1970-01-01T00:00:00.000Z` epoch sentinel, per column, with a commented-out repair `UPDATE` where the row has a separate `created_at` to approximate from.
|
|
430
|
+
- **Every dialect:** per `q.url()` column, the rows whose value is not an `http(s)` URL (`javascript:`, `data:`, …).
|
|
431
|
+
|
|
432
|
+
How to run it and what the repair means: [Troubleshooting → Data issues](/tooling/troubleshooting#data-issues).
|
|
433
|
+
|
|
413
434
|
### Realtime
|
|
414
435
|
|
|
415
436
|
When any feature has `realtime` configured:
|
|
@@ -457,24 +478,28 @@ The compiler separates schemas into two files:
|
|
|
457
478
|
|
|
458
479
|
## Generated Routes
|
|
459
480
|
|
|
460
|
-
For each
|
|
481
|
+
For each table with routes, the compiler generates `src/features/{feature}/{table}.routes.ts` containing:
|
|
461
482
|
|
|
462
483
|
| Route | Generated When |
|
|
463
484
|
|-------|----------------|
|
|
464
|
-
| `GET /` | `
|
|
465
|
-
| `GET /:id` | `
|
|
485
|
+
| `GET /` | [`read`](/define/read) declared |
|
|
486
|
+
| `GET /:id` | [`read`](/define/read) declared |
|
|
487
|
+
| `GET /views/{name}` | `read.views.{name}` declared |
|
|
466
488
|
| `POST /` | `crud.create` configured |
|
|
467
489
|
| `PATCH /:id` | `crud.update` configured |
|
|
468
490
|
| `DELETE /:id` | `crud.delete` configured |
|
|
469
|
-
| `PUT /:id` | `crud.put` configured |
|
|
470
|
-
| `POST /batch` | `crud.create` exists (auto-enabled) |
|
|
471
|
-
| `PATCH /batch` | `crud.update` exists (auto-enabled) |
|
|
472
|
-
| `DELETE /batch` | `crud.delete` exists (auto-enabled) |
|
|
473
|
-
| `PUT /batch` | `crud.
|
|
474
|
-
| `GET /views/{name}` | `views` configured |
|
|
491
|
+
| `PUT /:id` | `crud.put` configured, with `generateId: false` and `guards: false` |
|
|
492
|
+
| `POST /batch` | `crud.create` exists (auto-enabled; `crud.batchCreate: false` opts out) |
|
|
493
|
+
| `PATCH /batch` | `crud.update` exists (auto-enabled; `crud.batchUpdate: false` opts out) |
|
|
494
|
+
| `DELETE /batch` | `crud.delete` exists (auto-enabled; `crud.batchDelete: false` opts out) |
|
|
495
|
+
| `PUT /batch` | `crud.batchUpsert`, or `crud.create` + `crud.update` when `PUT` is enabled |
|
|
475
496
|
| `POST /:id/{action}` | Record-based actions defined |
|
|
476
497
|
| `POST /{action}` | Standalone actions defined |
|
|
477
498
|
|
|
499
|
+
`crud.list` and `crud.get` are rejected at compile time — collection and
|
|
500
|
+
single-record reads come from `read`. A verb with `routes: false` or mapped to
|
|
501
|
+
an action (`crud.create.action`) emits no raw route and no batch variant.
|
|
502
|
+
|
|
478
503
|
Routes are mounted under `/api/v1/{feature}` by default, or
|
|
479
504
|
`/api/v2/{feature}` when `contract: { routes: "v2" }` is set. The standard API shape
|
|
480
505
|
selects semantics and leaves these paths alone.
|
|
@@ -541,6 +566,12 @@ is drift on a live database with no clean fix-forward.
|
|
|
541
566
|
Only `meta/_journal.json` is expected to change, because that is where a new
|
|
542
567
|
entry lands.
|
|
543
568
|
|
|
569
|
+
The generated header and footer comments count as part of the file. New
|
|
570
|
+
migrations are stamped with the current header; an existing one keeps the
|
|
571
|
+
header it was first stamped with, byte for byte, because deploy ledgers hash
|
|
572
|
+
applied migrations. See [Troubleshooting](/tooling/troubleshooting#recompile-changed-the-comments-at-the-top-of-an-old-migration)
|
|
573
|
+
if an earlier compiler already rewrote one.
|
|
574
|
+
|
|
544
575
|
> If `quickback migrations doctor` reports snapshot drift — more journal entries
|
|
545
576
|
> than snapshot files — that drift came from your project's history, not from
|
|
546
577
|
> compiling. Compile does not delete snapshots it was never given.
|
|
@@ -107,6 +107,33 @@ Quickback now adds a D1-specific safety pass around Drizzle-generated migrations
|
|
|
107
107
|
|
|
108
108
|
If `quickback build` 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.
|
|
109
109
|
|
|
110
|
+
### Recompile changed the comments at the top of an old migration
|
|
111
|
+
|
|
112
|
+
A recompile hands every existing migration back byte-for-byte, including the
|
|
113
|
+
generated header comment in whatever wording it was first stamped with
|
|
114
|
+
(`quickback compile` or `quickback build`). Earlier compilers did not:
|
|
115
|
+
|
|
116
|
+
- a header stamped as `quickback compile` was restamped as `quickback build`;
|
|
117
|
+
- the compiler's own comment banner directly under the header — on the
|
|
118
|
+
Postgres RLS migration (`NNNN_quickback_rls_*.sql`) and the table-triggers
|
|
119
|
+
migration (`NNNN_quickback_triggers_*.sql`) — was deleted, and a later
|
|
120
|
+
recompile deleted the comment block after it too.
|
|
121
|
+
|
|
122
|
+
Only comments changed; no SQL statement was touched. What that means depends
|
|
123
|
+
on how you deploy:
|
|
124
|
+
|
|
125
|
+
- **Browser deploys (Cloudflare connection).** The deploy ledger hashes each
|
|
126
|
+
applied migration, so the rewritten file refused the redeploy with
|
|
127
|
+
`migration "…" already ran against this database with different content`.
|
|
128
|
+
Nothing was applied. Redeploy — Start keeps the bytes that were actually
|
|
129
|
+
applied, and the compiler now returns them unchanged.
|
|
130
|
+
- **`quickback deploy`, `wrangler d1 migrations apply`, `npm run db:migrate`.**
|
|
131
|
+
These record migrations by name or timestamp, not content, so nothing was
|
|
132
|
+
refused and the database is unaffected. Leave the file as it is on disk:
|
|
133
|
+
whatever shape it has now stays stable across recompiles. If you want the
|
|
134
|
+
original comments back, restore the file from git — it is a comment-only
|
|
135
|
+
change.
|
|
136
|
+
|
|
110
137
|
## Runtime Issues
|
|
111
138
|
|
|
112
139
|
### 401 on all requests
|
|
@@ -154,6 +181,46 @@ grep -r "missingExportName" quickback/.archives/src-2026-04-27T16-31-02-014/
|
|
|
154
181
|
|
|
155
182
|
Anything in `src/` not produced by the latest compile is removed on every compile — see [CLI → Compile Definitions](/tooling/cli#compile-definitions) for the full contract.
|
|
156
183
|
|
|
184
|
+
## Data Issues
|
|
185
|
+
|
|
186
|
+
Every compile that has something to check emits `reports/data-remediation.sql` in the project root. It is **read-only as emitted**: every statement is a `SELECT`, the repair `UPDATE`s are commented out, and neither the compiler nor the CLI ever runs it. Run it deliberately, read the results, then decide.
|
|
187
|
+
|
|
188
|
+
On D1, pass the file to `--command` so the results print (run it from the project root; `DB` is the features database binding — the report's header names yours):
|
|
189
|
+
|
|
190
|
+
```bash
|
|
191
|
+
npx wrangler d1 execute DB --remote --command "$(cat reports/data-remediation.sql)"
|
|
192
|
+
# the wrangler dev database instead:
|
|
193
|
+
npx wrangler d1 execute DB --local --command "$(cat reports/data-remediation.sql)"
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
Don't use `--file` with `--remote` here: that path is D1's bulk import, which takes the database offline while it runs and prints no result rows. On Postgres: `psql "$DATABASE_URL" -f reports/data-remediation.sql`.
|
|
197
|
+
|
|
198
|
+
### Timestamps read 1970-01-01 (SQLite / D1)
|
|
199
|
+
|
|
200
|
+
From compiler v0.33.2 (2026-05-21) until the fix, a Drizzle insert on SQLite / D1 that omitted a timestamp column persisted `1970-01-01T00:00:00.000Z` instead of the insert time. The column carries that constant as its DDL default so `ALTER TABLE ADD COLUMN` works, and Drizzle preferred it over the column's `$defaultFn`. Affected:
|
|
201
|
+
|
|
202
|
+
- **Every `.defaultNow()` column** (q or raw Drizzle), on every insert that omitted it — including ordinary `POST` / batch / upsert requests.
|
|
203
|
+
- **`createdAt` / `modifiedAt`**, only on inserts that did not go through the request `db` — queue and cron handlers' `db`, `createDb()` handles, and your own Drizzle instances. Requests and actions stamp both explicitly, so their rows are correct.
|
|
204
|
+
|
|
205
|
+
Postgres is not affected: `.defaultNow()` there is a real `DEFAULT now()`.
|
|
206
|
+
|
|
207
|
+
Recompiling fixes new writes. Existing rows keep the epoch — the real times were never recorded, so nothing can recover them. The report counts sentinel rows per column. Where the table also has a trustworthy `created_at`, it carries a commented repair like:
|
|
208
|
+
|
|
209
|
+
```sql
|
|
210
|
+
-- UPDATE "applications" SET "applied_at" = "created_at" WHERE "applied_at" = '1970-01-01T00:00:00.000Z' AND "created_at" <> '1970-01-01T00:00:00.000Z';
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
> The repair is an **approximation**: it writes the row's creation time, not the value the column should have held. That is right for "created" or "applied" style columns written at insert, and wrong for anything that means something else. Run a repair only for columns where that trade is acceptable. Take a backup first (`npx wrangler d1 export <features-database-name> --remote --output backup.sql` — the `database_name` of the `DB` binding in `wrangler.toml`), then run the one statement, uncommented, with `--command`. `created_at` itself has no proxy on the row; the report says so instead of offering a repair.
|
|
214
|
+
|
|
215
|
+
|
|
216
|
+
Raw SQL still reaches the DDL default. If you insert with ``db.run(sql`INSERT …`)``, set the timestamp columns yourself.
|
|
217
|
+
|
|
218
|
+
### Stored `javascript:` / `data:` URLs
|
|
219
|
+
|
|
220
|
+
Until the fix, `q.url()` accepted any scheme the WHATWG URL parser does, including `javascript:` and `data:`. A UI that renders such a value as a link is a stored-XSS hole. `q.url()` now accepts only absolute `http(s)` URLs. The bundled CMS never renders url values as links, and the Account consent page links only `http(s)` values.
|
|
221
|
+
|
|
222
|
+
For each `q.url()` column, the report lists the rows whose value is not `http(s)`. There is no automatic repair. Fix, clear, or delete each row yourself. Until you have, make sure your own UI only links `http(s)` values — for example, check `new URL(value).protocol`.
|
|
223
|
+
|
|
157
224
|
## See Also
|
|
158
225
|
|
|
159
226
|
- [Cloud Compiler Troubleshooting](/tooling/cloud-compiler/troubleshooting) — CLI and authentication issues
|
|
@@ -59,12 +59,16 @@ Clicking an action opens a modal dialog with:
|
|
|
59
59
|
|
|
60
60
|
The dialog generates the appropriate input control for each field:
|
|
61
61
|
|
|
62
|
-
|
|
|
62
|
+
| `inputFields[].type` | Input Control | Notes |
|
|
63
63
|
|----------|--------------|-------|
|
|
64
64
|
| `string` | Text input or FK typeahead | Free text unless the field resolves to an emitted `fkTarget` |
|
|
65
65
|
| `number` | Number input | Step 0.01, supports decimals |
|
|
66
66
|
| `boolean` | Checkbox | With label text |
|
|
67
|
-
| `
|
|
67
|
+
| `enum` | Text input | The allowed values are in `inputFields[].enum` |
|
|
68
|
+
| `array<…>` | Text input | Comma-separated values, split on save |
|
|
69
|
+
|
|
70
|
+
The types come from the action's input JSON Schema — see
|
|
71
|
+
[ActionInputField](/ui/admin/schema-format#actioninputfield).
|
|
68
72
|
|
|
69
73
|
Required fields are marked with a red asterisk. Default values from the schema are pre-filled.
|
|
70
74
|
|
|
@@ -201,7 +201,7 @@ That is a deliberate trade: the old gate answered a wrong-role caller with a `30
|
|
|
201
201
|
|
|
202
202
|
The gates that carry real data:
|
|
203
203
|
|
|
204
|
-
1. **`/api/v1/schema`** — the metadata endpoint. Admits `sysadmin`, plus any caller with a membership when `access: "member"`. Otherwise `403` with `CMS_ACCESS_DENIED` and a hint naming the requirement. Without the registry there is no CMS.
|
|
204
|
+
1. **`/api/v1/schema`** — the metadata endpoint. Admits `sysadmin`, plus any caller with a membership when `access: "member"`. Otherwise `403` with `CMS_ACCESS_DENIED` and a hint naming the requirement (`401 AUTH_MISSING` when not signed in). Without the registry there is no CMS.
|
|
205
205
|
2. **`custom_view` routes** — saved views follow whoever is admitted: the `sysadmin` tier in `"sysadmin"` mode, org membership *or* sysadmin in `"member"` mode.
|
|
206
206
|
3. **Account UI link** — the profile CMS action is hidden for callers who wouldn't get in. For admitted members it activates the selected organization before opening the CMS.
|
|
207
207
|
|
|
@@ -137,11 +137,15 @@ The CMS generates create and edit forms from the table's guard configuration:
|
|
|
137
137
|
|
|
138
138
|
### Create Form
|
|
139
139
|
|
|
140
|
-
Shows all fields listed in `guards.createable
|
|
140
|
+
Shows all fields listed in the registry's `guards.createable`, which is the
|
|
141
|
+
compiler-resolved set `POST` accepts. That set is populated even when the
|
|
142
|
+
table declares no `guards`. Required fields (notNull without a default) are marked with a red asterisk. Validation rules from the schema (min/max length, enum constraints, email format) are enforced client-side.
|
|
141
143
|
|
|
142
144
|
### Edit Form
|
|
143
145
|
|
|
144
|
-
Shows all fields listed in `guards.updatable
|
|
146
|
+
Shows all fields listed in the registry's `guards.updatable` (the resolved set
|
|
147
|
+
`PATCH` accepts). Only fields you changed are sent, so an untouched value that
|
|
148
|
+
was read back masked is never written over the real one. Additionally:
|
|
145
149
|
|
|
146
150
|
- **Immutable fields** appear as disabled inputs with a lock icon
|
|
147
151
|
- **Protected fields** appear as disabled inputs with the note "Updated via actions only"
|