@gusto/create-baerly-storage 0.2.0 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +202 -0
- package/dist/index.js.map +1 -1
- package/dist/templates/addons/docker/Dockerfile +8 -2
- package/dist/templates/minimal-cloudflare/AGENTS.md +115 -79
- package/dist/templates/minimal-cloudflare/README.md +22 -15
- package/dist/templates/minimal-cloudflare/package.json +6 -6
- package/dist/templates/minimal-cloudflare/wrangler.jsonc +1 -1
- package/dist/templates/minimal-node/AGENTS.md +80 -61
- package/dist/templates/minimal-node/README.md +11 -9
- package/dist/templates/minimal-node/package.json +4 -4
- package/dist/templates/react-cloudflare/AGENTS.md +48 -27
- package/dist/templates/react-cloudflare/README.md +8 -5
- package/dist/templates/react-cloudflare/package.json +7 -7
- package/dist/templates/react-cloudflare/wrangler.jsonc +1 -1
- package/dist/templates/react-node/AGENTS.md +47 -25
- package/dist/templates/react-node/README.md +8 -7
- package/dist/templates/react-node/package.json +5 -5
- package/package.json +4 -10
|
@@ -18,17 +18,17 @@
|
|
|
18
18
|
"zod": "^4.4.3"
|
|
19
19
|
},
|
|
20
20
|
"devDependencies": {
|
|
21
|
-
"@cloudflare/vite-plugin": "^1.
|
|
21
|
+
"@cloudflare/vite-plugin": "^1.40.1",
|
|
22
22
|
"@cloudflare/workers-types": "^4",
|
|
23
|
-
"@types/node": "^
|
|
24
|
-
"@types/react": "^19.2.
|
|
23
|
+
"@types/node": "^25.9.2",
|
|
24
|
+
"@types/react": "^19.2.17",
|
|
25
25
|
"@types/react-dom": "^19.0.0",
|
|
26
26
|
"@vitejs/plugin-react": "^6.0.2",
|
|
27
|
-
"happy-dom": "^20.
|
|
27
|
+
"happy-dom": "^20.10.2",
|
|
28
28
|
"typescript": "^6.0.3",
|
|
29
|
-
"vite": "^8.0.
|
|
30
|
-
"vitest": "^4.1.
|
|
31
|
-
"wrangler": "^4.
|
|
29
|
+
"vite": "^8.0.16",
|
|
30
|
+
"vitest": "^4.1.8",
|
|
31
|
+
"wrangler": "^4.99.0"
|
|
32
32
|
},
|
|
33
33
|
"packageManager": "pnpm@11.1.2"
|
|
34
34
|
}
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
// Cloudflare Worker manifest. See `AGENTS.md` for what each field
|
|
3
|
-
// drives (R2 binding, assets, vars
|
|
3
|
+
// drives (R2 binding, assets, vars) and how
|
|
4
4
|
// the verifier consumes the vars.
|
|
5
5
|
"$schema": "node_modules/wrangler/config-schema.json",
|
|
6
6
|
"name": "react-cloudflare",
|
|
@@ -135,22 +135,34 @@ http://localhost:5173/<path>`) before declaring the task complete.
|
|
|
135
135
|
|
|
136
136
|
## When editing X, read Y
|
|
137
137
|
|
|
138
|
-
- **Typed collections** —
|
|
138
|
+
- **Typed collections** — two ways to get a typed row, in DX order.
|
|
139
|
+
The generic on `client.collection<N>(name)` is the collection
|
|
140
|
+
**name** (constrained to `CollectionNames<typeof config>`), not the
|
|
141
|
+
row type — so don't pass a row type to it.
|
|
139
142
|
1. **Bind the config.** This template's `src/web/client.ts`
|
|
140
143
|
already passes `config` to `createBaerlyClient({ baseUrl,
|
|
141
144
|
config })`, so `client.collection("notes")` returns
|
|
142
145
|
`ClientCollection<Row>` with `Row` derived from the
|
|
143
146
|
`NoteSchema` declared in `baerly.config.ts`. No generic
|
|
144
|
-
needed.
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
2. **
|
|
148
|
-
|
|
149
|
-
|
|
147
|
+
needed. When you need to name that row type elsewhere, use
|
|
148
|
+
`RowOf<typeof config, "notes">` (re-exported from
|
|
149
|
+
`@gusto/baerly-storage`) — not a generic on `.collection()`.
|
|
150
|
+
2. **Cast the handle (undeclared collection).** This template's
|
|
151
|
+
`client` is bound to `config`, so its names narrow to the
|
|
152
|
+
declared collections. To reach a collection that isn't in
|
|
153
|
+
`config`, build an unbound client
|
|
154
|
+
(`createBaerlyClient({ baseUrl })` with no `config`) — its names
|
|
155
|
+
widen to `string` and its row defaults to `DocumentData`. Cast at
|
|
156
|
+
the construction site for a narrower shape that still satisfies
|
|
157
|
+
the kernel's `DocumentData` constraint
|
|
158
|
+
(`{ [k: string]: DocumentValue }`):
|
|
150
159
|
```ts
|
|
160
|
+
import { createBaerlyClient, type ClientCollection } from "@gusto/baerly-storage/client";
|
|
151
161
|
import type { DocumentData } from "@gusto/baerly-storage";
|
|
152
162
|
interface Bookmark extends DocumentData { _id: string; url: string }
|
|
153
|
-
|
|
163
|
+
const raw = createBaerlyClient({ baseUrl: "" });
|
|
164
|
+
const bookmarks = raw.collection("bookmarks") as ClientCollection<Bookmark>;
|
|
165
|
+
await bookmarks.all();
|
|
154
166
|
```
|
|
155
167
|
A plain `interface Bookmark { _id: string; url: string }`
|
|
156
168
|
(no index signature) will fail with TS2344 — the constraint
|
|
@@ -273,7 +285,7 @@ http://localhost:5173/<path>`) before declaring the task complete.
|
|
|
273
285
|
|
|
274
286
|
On a validation failure the server throws
|
|
275
287
|
`BaerlyError{ code: "SchemaError", issues: [{ path, message }] }`;
|
|
276
|
-
HTTP clients see a
|
|
288
|
+
HTTP clients see a 400 with the same envelope. Validation runs
|
|
277
289
|
on the post-image so `update` and `replace` see the full doc, not
|
|
278
290
|
just the patch.
|
|
279
291
|
|
|
@@ -302,9 +314,11 @@ http://localhost:5173/<path>`) before declaring the task complete.
|
|
|
302
314
|
is ignored. The adapter reads `config.auth` to pick its verifier;
|
|
303
315
|
a `verifier:` on `baerlyNode({ ... })` overrides it. The schema-
|
|
304
316
|
bound `notes` collection (`baerly.config.ts:NoteSchema`) runs
|
|
305
|
-
server-side regardless of the auth posture. `baerly
|
|
306
|
-
--target=node`
|
|
307
|
-
|
|
317
|
+
server-side regardless of the auth posture. There is no `baerly
|
|
318
|
+
doctor --target=node` backend today; verify bucket CAS with
|
|
319
|
+
`baerly doctor --bucket=<s3-uri>` and probe `/v1/healthz` after
|
|
320
|
+
deploy. See "Going to production" below for the two production-fit
|
|
321
|
+
recipes.
|
|
308
322
|
|
|
309
323
|
### Going to production
|
|
310
324
|
|
|
@@ -324,9 +338,9 @@ auth: "shared-secret", // ← flip from "none"
|
|
|
324
338
|
|
|
325
339
|
Dev: put `SHARED_SECRET=dev-shared-secret` in `.env`. Prod: set
|
|
326
340
|
`SHARED_SECRET` in the process environment (your PaaS / secret
|
|
327
|
-
manager).
|
|
328
|
-
|
|
329
|
-
`
|
|
341
|
+
manager). The Node process fails closed if `auth: "shared-secret"`
|
|
342
|
+
is set without `SHARED_SECRET` reachable from `process.env`; verify
|
|
343
|
+
the live bucket separately with `baerly doctor --bucket=<s3-uri>`.
|
|
330
344
|
|
|
331
345
|
<!-- pattern-b:end -->
|
|
332
346
|
<!-- pattern-c:start -->
|
|
@@ -360,6 +374,7 @@ await baerlyNode({
|
|
|
360
374
|
jwks: process.env["JWKS_URL"],
|
|
361
375
|
issuer: process.env["JWT_ISSUER"]!,
|
|
362
376
|
audience: process.env["JWT_AUDIENCE"]!,
|
|
377
|
+
tenantPrefix: config.tenant, // or tenantClaim: "tenant"
|
|
363
378
|
}),
|
|
364
379
|
}),
|
|
365
380
|
}).listen(Number(process.env["PORT"] ?? 8080));
|
|
@@ -367,7 +382,9 @@ await baerlyNode({
|
|
|
367
382
|
|
|
368
383
|
Dev sees `JWKS_URL` as `undefined`, spread short-circuits, and
|
|
369
384
|
`config.auth: "none"` runs. Prod sets `JWKS_URL` + `JWT_ISSUER` +
|
|
370
|
-
`JWT_AUDIENCE` and `bearerJwt` engages.
|
|
385
|
+
`JWT_AUDIENCE` and `bearerJwt` engages. Use `tenantClaim` when your
|
|
386
|
+
IdP issues one tenant per token; use `tenantPrefix` for single-tenant
|
|
387
|
+
apps or tenancy enforced outside Baerly.
|
|
371
388
|
|
|
372
389
|
<!-- pattern-c:end -->
|
|
373
390
|
- **Storage backend** — `src/server/index.ts` picks between
|
|
@@ -431,7 +448,8 @@ Dev sees `JWKS_URL` as `undefined`, spread short-circuits, and
|
|
|
431
448
|
into the predicate so the index planner can prune
|
|
432
449
|
(`db.collection("notes").where({ ... }).all()`), or maintain a
|
|
433
450
|
side-projection (Postgres/SQLite/search index) populated
|
|
434
|
-
incrementally from the `/v1/since
|
|
451
|
+
incrementally from the `/v1/since?collection=<name>&cursor=<opaque>`
|
|
452
|
+
log feed or from a write hook —
|
|
435
453
|
never re-scan per request.
|
|
436
454
|
|
|
437
455
|
## Maintenance
|
|
@@ -450,7 +468,7 @@ maintenance, so the published idle-reader cost bound holds.
|
|
|
450
468
|
A bucket maintains itself as long as it takes writes. A bucket served read-only does
|
|
451
469
|
not auto-compact and pays a small, bounded replay — fine at small scale, a signal to
|
|
452
470
|
graduate once a collection is large. See docs/about/graduation.md for the per-tier
|
|
453
|
-
envelope and the BAERLY_MAINTENANCE_
|
|
471
|
+
envelope and the `BAERLY_MAINTENANCE_*` operator env vars (you almost never need them).
|
|
454
472
|
|
|
455
473
|
Operator opt-in: call runScheduledMaintenance from @gusto/baerly-storage/maintenance on
|
|
456
474
|
your own schedule. Not required for steady-state operation.
|
|
@@ -465,7 +483,7 @@ model puts the soft ceiling at:
|
|
|
465
483
|
- **~10 GB / tenant**
|
|
466
484
|
- **~100 collections / tenant**
|
|
467
485
|
|
|
468
|
-
Past those, S3 list-prefix latency,
|
|
486
|
+
Past those, S3 list-prefix latency, snapshot fold cost, and per-class
|
|
469
487
|
op pricing start to dominate; you're better off on a real database.
|
|
470
488
|
Pick your graduation target:
|
|
471
489
|
- **Cloudflare Workers + lock-in OK:** [D1](https://developers.cloudflare.com/d1/) — cheaper per-write at M-size.
|
|
@@ -473,13 +491,16 @@ Pick your graduation target:
|
|
|
473
491
|
- **Single-instance Node:** SQLite via Litestream.
|
|
474
492
|
|
|
475
493
|
Either way, the export below is mechanical because log entries are
|
|
476
|
-
|
|
494
|
+
Debezium-style CDC change events — graduation is a Baerly win,
|
|
477
495
|
not a churn event.
|
|
478
496
|
|
|
479
|
-
**Estimate your current rate:**
|
|
480
|
-
|
|
481
|
-
|
|
482
|
-
|
|
497
|
+
**Estimate your current rate:** for Node/self-hosted buckets,
|
|
498
|
+
`baerly admin usage --target=node --bucket=<bucket-uri> --app=<app>
|
|
499
|
+
--tenant=<tenant>` lists recent log entries per collection and computes
|
|
500
|
+
writes/min. On Cloudflare, use canonical logs for trend history and
|
|
501
|
+
`baerly cost --bucket=<bucket-uri> --collection=<collection>` for the
|
|
502
|
+
current operation-cost projection until the usage scanner is wired to
|
|
503
|
+
R2 bindings.
|
|
483
504
|
|
|
484
505
|
**Export when ready:** `baerly export --target=sqlite|postgres|d1
|
|
485
506
|
--bucket=<...> --app=<...> --tenant=<...> --collection=<...>` writes a
|
|
@@ -562,7 +583,8 @@ const result = useQuery(
|
|
|
562
583
|
```
|
|
563
584
|
|
|
564
585
|
`useQuery` re-runs the callback when `deps` changes OR when the
|
|
565
|
-
`/v1/since
|
|
586
|
+
`/v1/since?collection=<name>&cursor=<opaque>` long-poll batches a
|
|
587
|
+
non-empty change for any subscribed
|
|
566
588
|
collection. Idle long-poll cycles (empty batches) drop at the
|
|
567
589
|
`subscription-pool` layer, so a steady-state collection costs zero list
|
|
568
590
|
reads. Add a `<select>` bound to `setFilter` and the list narrows live.
|
|
@@ -10,6 +10,8 @@ one-collection `notes` schema you extend; flip to a shared secret
|
|
|
10
10
|
or wire `bearerJwt` against your OIDC IdP before deploy — see
|
|
11
11
|
"Production auth" below.
|
|
12
12
|
|
|
13
|
+
**The only persistent component is your S3-compatible bucket** — there is no separate database server or daemon to deploy alongside the node process, no idle bill, and maintenance is automatic and write-triggered (no cron, no sidecar, no scheduler).
|
|
14
|
+
|
|
13
15
|
To ship a production Dockerfile alongside, scaffold with
|
|
14
16
|
`--with=docker` — the add-on writes a multi-stage distroless Dockerfile,
|
|
15
17
|
`.dockerignore`, and `healthcheck.js` into this same shape.
|
|
@@ -30,7 +32,7 @@ react-node/
|
|
|
30
32
|
├── CLAUDE.md # same content (Claude Code reads this)
|
|
31
33
|
├── src/
|
|
32
34
|
│ ├── server/
|
|
33
|
-
│ │ └── index.ts # baerlyNode({
|
|
35
|
+
│ │ └── index.ts # baerlyNode({ config, storage, verifier, webRoot }).listen(PORT)
|
|
34
36
|
│ └── web/
|
|
35
37
|
│ ├── main.tsx # React entry
|
|
36
38
|
│ ├── App.tsx # Provider + new-note form (useMutation)
|
|
@@ -51,14 +53,14 @@ pnpm dev
|
|
|
51
53
|
mounts the Node HTTP listener as Connect middleware on the same Vite
|
|
52
54
|
process that serves the SPA, so `GET /` hits the SPA on
|
|
53
55
|
`http://localhost:5173/` and anything baerly handles (e.g.
|
|
54
|
-
`GET /v1/healthz`, `POST /v1/notes`) is served on the same origin —
|
|
56
|
+
`GET /v1/healthz`, `POST /v1/c/notes`) is served on the same origin —
|
|
55
57
|
one process, one port, SPA + HMR + `/v1/*` in one command. Storage is
|
|
56
58
|
`LocalFsStorage` rooted at `.baerly-data/`, so first-touch needs no
|
|
57
59
|
S3 creds, no JWKS, and no second process.
|
|
58
60
|
|
|
59
61
|
Open <http://localhost:5173>. Type a note, hit "Add note." Open a
|
|
60
62
|
second tab — inserts, edits, and deletes in one tab appear in the
|
|
61
|
-
other over the `/v1/since
|
|
63
|
+
other over the `/v1/since?collection=notes&cursor=...` long-poll.
|
|
62
64
|
|
|
63
65
|
For production-shaped local runs (S3 and the bundled SPA served
|
|
64
66
|
from `dist/client/`):
|
|
@@ -137,7 +139,7 @@ the `NoteSchema` still validates writes server-side. Before deploy,
|
|
|
137
139
|
follow `AGENTS.md` → "Going to production":
|
|
138
140
|
|
|
139
141
|
- **Pattern B — `auth: "shared-secret"`.** Single-tenant
|
|
140
|
-
server-to-server callers (CI
|
|
142
|
+
server-to-server callers (CI and internal services). Flip
|
|
141
143
|
`auth` in `baerly.config.ts` and put `SHARED_SECRET` in
|
|
142
144
|
`process.env` (your PaaS / secret manager).
|
|
143
145
|
- **Pattern C — JWKS-backed JWT (recommended for multi-tenant).**
|
|
@@ -158,8 +160,7 @@ start to dominate, and you're better off on a real database:
|
|
|
158
160
|
- **~100 collections / tenant**
|
|
159
161
|
|
|
160
162
|
When you cross the soft ceiling, graduation is mechanical:
|
|
161
|
-
`baerly export --target=postgres` walks your log entries (already
|
|
162
|
-
Postgres-logical-replication-shaped) into a real DB. If your
|
|
163
|
+
`baerly export --target=postgres` walks your log entries (already Debezium-style CDC change events) into a real DB. If your
|
|
163
164
|
deploy target is Cloudflare Workers and you'll accept Cloudflare
|
|
164
165
|
lock-in, [D1](https://developers.cloudflare.com/d1/) is cheaper
|
|
165
166
|
per-write at M-size and is a natural next step. If you're on
|
|
@@ -172,7 +173,7 @@ not a churn event.
|
|
|
172
173
|
|
|
173
174
|
```sh
|
|
174
175
|
baerly export --target=postgres \
|
|
175
|
-
--bucket=react-node --app=react-node --tenant=<your-tenant> \
|
|
176
|
+
--bucket=s3://react-node --app=react-node --tenant=<your-tenant> \
|
|
176
177
|
--collection=<collection-name> --output=./out.sql
|
|
177
178
|
```
|
|
178
179
|
|
|
@@ -19,14 +19,14 @@
|
|
|
19
19
|
"zod": "^4.4.3"
|
|
20
20
|
},
|
|
21
21
|
"devDependencies": {
|
|
22
|
-
"@types/node": "^
|
|
23
|
-
"@types/react": "^19.2.
|
|
22
|
+
"@types/node": "^25.9.2",
|
|
23
|
+
"@types/react": "^19.2.17",
|
|
24
24
|
"@types/react-dom": "^19.0.0",
|
|
25
25
|
"@vitejs/plugin-react": "^6.0.2",
|
|
26
|
-
"happy-dom": "^20.
|
|
26
|
+
"happy-dom": "^20.10.2",
|
|
27
27
|
"typescript": "^6.0.3",
|
|
28
|
-
"vite": "^8.0.
|
|
29
|
-
"vitest": "^4.1.
|
|
28
|
+
"vite": "^8.0.16",
|
|
29
|
+
"vitest": "^4.1.8"
|
|
30
30
|
},
|
|
31
31
|
"packageManager": "pnpm@11.1.2"
|
|
32
32
|
}
|
package/package.json
CHANGED
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@gusto/create-baerly-storage",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.3.0",
|
|
4
4
|
"description": "Scaffold a new baerly-storage app. Run via `pnpm create @gusto/baerly-storage@latest -- my-app --target=cloudflare`.",
|
|
5
5
|
"homepage": "https://github.com/Gusto/baerly-storage#readme",
|
|
6
6
|
"bugs": {
|
|
7
7
|
"url": "https://github.com/Gusto/baerly-storage/issues"
|
|
8
8
|
},
|
|
9
|
-
"license": "
|
|
9
|
+
"license": "Apache-2.0",
|
|
10
10
|
"author": "Eric Baer",
|
|
11
11
|
"repository": {
|
|
12
12
|
"type": "git",
|
|
@@ -20,17 +20,11 @@
|
|
|
20
20
|
"dist"
|
|
21
21
|
],
|
|
22
22
|
"type": "module",
|
|
23
|
-
"exports": {
|
|
24
|
-
".": {
|
|
25
|
-
"types": "./src/index.ts",
|
|
26
|
-
"import": "./src/index.ts"
|
|
27
|
-
}
|
|
28
|
-
},
|
|
29
23
|
"publishConfig": {
|
|
30
|
-
"access": "
|
|
24
|
+
"access": "public"
|
|
31
25
|
},
|
|
32
26
|
"dependencies": {
|
|
33
|
-
"@clack/prompts": "^1.
|
|
27
|
+
"@clack/prompts": "^1.5.1",
|
|
34
28
|
"citty": "^0.2.2",
|
|
35
29
|
"picocolors": "^1.1.1"
|
|
36
30
|
},
|