@gusto/create-baerly-storage 0.1.2 → 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 +57 -32
- package/dist/templates/react-cloudflare/README.md +8 -5
- package/dist/templates/react-cloudflare/package.json +7 -7
- package/dist/templates/react-cloudflare/src/web/App.tsx +1 -2
- package/dist/templates/react-cloudflare/src/web/NoteList.tsx +2 -2
- package/dist/templates/react-cloudflare/src/web/client.ts +8 -0
- package/dist/templates/react-cloudflare/wrangler.jsonc +1 -1
- package/dist/templates/react-node/AGENTS.md +56 -30
- package/dist/templates/react-node/README.md +8 -7
- package/dist/templates/react-node/package.json +5 -5
- package/dist/templates/react-node/src/web/App.tsx +1 -2
- package/dist/templates/react-node/src/web/NoteList.tsx +2 -2
- package/dist/templates/react-node/src/web/client.ts +8 -0
- package/package.json +4 -10
|
@@ -7,6 +7,8 @@ so the day-1 happy path works with zero env vars, plus a
|
|
|
7
7
|
one-collection `notes` schema you extend; flip to Cloudflare Access
|
|
8
8
|
or a shared secret before deploy — see "Production auth" below.
|
|
9
9
|
|
|
10
|
+
**The only persistent component is your R2 bucket** — there is no Worker to keep warm, no database daemon to operate, no idle bill, and maintenance is automatic and write-triggered (no cron, no sidecar, no scheduler).
|
|
11
|
+
|
|
10
12
|
## What you got
|
|
11
13
|
|
|
12
14
|
```
|
|
@@ -16,7 +18,7 @@ react-cloudflare/
|
|
|
16
18
|
├── tsconfig.app.json # client TS project (src/web)
|
|
17
19
|
├── tsconfig.worker.json # Worker TS project (src/server)
|
|
18
20
|
├── vite.config.ts # Vite + @vitejs/plugin-react + @cloudflare/vite-plugin
|
|
19
|
-
├── wrangler.jsonc # Worker manifest — R2 binding, assets, vars
|
|
21
|
+
├── wrangler.jsonc # Worker manifest — R2 binding, assets, vars
|
|
20
22
|
├── index.html # SPA shell — Vite's entry point
|
|
21
23
|
├── baerly.config.ts # app, tenant, target, NoteSchema, `Note` type
|
|
22
24
|
├── AGENTS.md # deeper guide: hooks, schema, auth, deploy
|
|
@@ -46,7 +48,7 @@ share an origin (`http://localhost:5173`). First run downloads the
|
|
|
46
48
|
|
|
47
49
|
Open <http://localhost:5173>. Type a note, hit "Add note." Open a
|
|
48
50
|
second tab — inserts, edits, and deletes in one tab appear in the
|
|
49
|
-
other over the `/v1/since
|
|
51
|
+
other over the `/v1/since?collection=notes&cursor=...` long-poll.
|
|
50
52
|
|
|
51
53
|
`pnpm build` runs `tsc -b && vite build`; the SPA lands in
|
|
52
54
|
`dist/client/` for the `assets:` binding in `wrangler.jsonc` to
|
|
@@ -56,7 +58,7 @@ serve on deploy.
|
|
|
56
58
|
|
|
57
59
|
```sh
|
|
58
60
|
baerly deploy # reads baerly.config.ts:target, runs wrangler deploy
|
|
59
|
-
baerly doctor --target=cloudflare # verify bindings, secrets,
|
|
61
|
+
baerly doctor --target=cloudflare # verify bindings, secrets, optional triggers
|
|
60
62
|
```
|
|
61
63
|
|
|
62
64
|
`baerly doctor --target=cloudflare` warns on `auth: "none"` for
|
|
@@ -91,7 +93,8 @@ follow `AGENTS.md` → "Going to production":
|
|
|
91
93
|
`wrangler.jsonc:vars`. The `cloudflareAccess()` preset
|
|
92
94
|
(re-exported from `@gusto/baerly-storage/auth`) reads the JWT off
|
|
93
95
|
`Cf-Access-Jwt-Assertion`, validates it against your team's JWKS,
|
|
94
|
-
and
|
|
96
|
+
and pins `tenantPrefix` to `config.tenant` unless you pass an
|
|
97
|
+
explicit tenant claim.
|
|
95
98
|
- **Pattern B — `auth: "shared-secret"`.** Single-tenant
|
|
96
99
|
server-to-server callers. Flip `auth` in `baerly.config.ts`, set
|
|
97
100
|
`SHARED_SECRET` via `wrangler secret put`, and re-enable
|
|
@@ -109,7 +112,7 @@ export is a mechanical translator, not a vendor migration.
|
|
|
109
112
|
## Pointers
|
|
110
113
|
|
|
111
114
|
- `baerly.config.ts` — app config + Zod schema.
|
|
112
|
-
- `src/server/index.ts` — Worker fetch
|
|
115
|
+
- `src/server/index.ts` — Worker fetch entry.
|
|
113
116
|
- `src/web/NoteList.tsx` — `useQuery` reactive read.
|
|
114
117
|
- `wrangler.jsonc` — Cloudflare Worker manifest.
|
|
115
118
|
- `AGENTS.md` / `CLAUDE.md` — agent-facing guide (byte-identical).
|
|
@@ -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
|
import { useState } from "react";
|
|
2
|
-
import { useMutation, useQuery } from "@gusto/baerly-storage/client/react";
|
|
3
2
|
import type { Note } from "../../baerly.config.ts";
|
|
3
|
+
import { useMutation, useQuery } from "./client.ts";
|
|
4
4
|
|
|
5
5
|
const NoteRow = ({ note }: { note: Note }) => {
|
|
6
6
|
const [isEditing, setIsEditing] = useState(false);
|
|
@@ -68,7 +68,7 @@ const NoteRow = ({ note }: { note: Note }) => {
|
|
|
68
68
|
};
|
|
69
69
|
|
|
70
70
|
export const NoteList = () => {
|
|
71
|
-
const result = useQuery((c) => c.collection("notes").all()
|
|
71
|
+
const result = useQuery((c) => c.collection("notes").all(), []);
|
|
72
72
|
if (result.status === "error") {
|
|
73
73
|
return <p className="error">Error: {result.error.message}</p>;
|
|
74
74
|
}
|
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { createBaerlyClient } from "@gusto/baerly-storage/client";
|
|
2
|
+
import { createBaerlyReact } from "@gusto/baerly-storage/client/react";
|
|
2
3
|
import config from "../../baerly.config.ts";
|
|
3
4
|
|
|
4
5
|
// Same-origin baseUrl works in both dev and production. With
|
|
@@ -11,3 +12,10 @@ export const client = createBaerlyClient({
|
|
|
11
12
|
baseUrl: "",
|
|
12
13
|
config,
|
|
13
14
|
});
|
|
15
|
+
|
|
16
|
+
// The bound React surface. `createBaerlyReact<typeof config>()` pins
|
|
17
|
+
// every hook to your collections, so inside a `useQuery` /
|
|
18
|
+
// `useMutation` callback `c.collection("notes")` infers the `Note`
|
|
19
|
+
// row type — no casts. Import these hooks from this module (not from
|
|
20
|
+
// the package) so they stay bound.
|
|
21
|
+
export const { BaerlyProvider, useQuery, useMutation } = createBaerlyReact<typeof config>();
|
|
@@ -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
|
|
@@ -544,23 +565,26 @@ the cache key changes when the filter does:
|
|
|
544
565
|
|
|
545
566
|
```tsx
|
|
546
567
|
import { useState } from "react";
|
|
547
|
-
import { useQuery } from "@gusto/baerly-storage/client/react";
|
|
548
568
|
import { STATUSES, type Note } from "../../baerly.config.ts";
|
|
569
|
+
import { useQuery } from "./client.ts";
|
|
549
570
|
|
|
550
571
|
type Filter = "all" | Note["status"];
|
|
551
572
|
|
|
552
573
|
const [filter, setFilter] = useState<Filter>("all");
|
|
574
|
+
// `useQuery` comes from the bound factory in `client.ts`, so
|
|
575
|
+
// `c.collection("notes")` infers the `Note` row — no `<Note>`, no cast.
|
|
553
576
|
const result = useQuery(
|
|
554
577
|
(c) =>
|
|
555
578
|
filter === "all"
|
|
556
|
-
? c.collection
|
|
557
|
-
: c.collection
|
|
579
|
+
? c.collection("notes").all()
|
|
580
|
+
: c.collection("notes").where({ status: filter }).all(),
|
|
558
581
|
[filter],
|
|
559
582
|
);
|
|
560
583
|
```
|
|
561
584
|
|
|
562
585
|
`useQuery` re-runs the callback when `deps` changes OR when the
|
|
563
|
-
`/v1/since
|
|
586
|
+
`/v1/since?collection=<name>&cursor=<opaque>` long-poll batches a
|
|
587
|
+
non-empty change for any subscribed
|
|
564
588
|
collection. Idle long-poll cycles (empty batches) drop at the
|
|
565
589
|
`subscription-pool` layer, so a steady-state collection costs zero list
|
|
566
590
|
reads. Add a `<select>` bound to `setFilter` and the list narrows live.
|
|
@@ -574,7 +598,7 @@ const filtered = useQuery(
|
|
|
574
598
|
(c) =>
|
|
575
599
|
filter === "all"
|
|
576
600
|
? useQuery.skip
|
|
577
|
-
: c.collection
|
|
601
|
+
: c.collection("notes").where({ status: filter }).all(),
|
|
578
602
|
[filter],
|
|
579
603
|
);
|
|
580
604
|
if (filtered.status === "skipped") return <FullList />;
|
|
@@ -584,7 +608,9 @@ For dependent reads, compose two `useQuery` calls — the second one
|
|
|
584
608
|
returns `useQuery.skip` until the first resolves to `"ok"`:
|
|
585
609
|
|
|
586
610
|
```tsx
|
|
587
|
-
|
|
611
|
+
// `comments` must be declared in baerly.config.ts — the bound hooks
|
|
612
|
+
// only know your declared collections (an undeclared name is a type error).
|
|
613
|
+
const parent = useQuery((c) => c.collection("notes").get(id), [id]);
|
|
588
614
|
const replies = useQuery(
|
|
589
615
|
(c) =>
|
|
590
616
|
parent.status === "ok"
|
|
@@ -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
|
}
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { useState } from "react";
|
|
2
|
-
import { useMutation, useQuery } from "@gusto/baerly-storage/client/react";
|
|
3
2
|
import type { Note } from "../../baerly.config.ts";
|
|
3
|
+
import { useMutation, useQuery } from "./client.ts";
|
|
4
4
|
|
|
5
5
|
const NoteRow = ({ note }: { note: Note }) => {
|
|
6
6
|
const [isEditing, setIsEditing] = useState(false);
|
|
@@ -68,7 +68,7 @@ const NoteRow = ({ note }: { note: Note }) => {
|
|
|
68
68
|
};
|
|
69
69
|
|
|
70
70
|
export const NoteList = () => {
|
|
71
|
-
const result = useQuery((c) => c.collection("notes").all()
|
|
71
|
+
const result = useQuery((c) => c.collection("notes").all(), []);
|
|
72
72
|
if (result.status === "error") {
|
|
73
73
|
return <p className="error">Error: {result.error.message}</p>;
|
|
74
74
|
}
|
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { createBaerlyClient } from "@gusto/baerly-storage/client";
|
|
2
|
+
import { createBaerlyReact } from "@gusto/baerly-storage/client/react";
|
|
2
3
|
import config from "../../baerly.config.ts";
|
|
3
4
|
|
|
4
5
|
// Same-origin baseUrl works in both dev and production. With
|
|
@@ -11,3 +12,10 @@ export const client = createBaerlyClient({
|
|
|
11
12
|
baseUrl: "",
|
|
12
13
|
config,
|
|
13
14
|
});
|
|
15
|
+
|
|
16
|
+
// The bound React surface. `createBaerlyReact<typeof config>()` pins
|
|
17
|
+
// every hook to your collections, so inside a `useQuery` /
|
|
18
|
+
// `useMutation` callback `c.collection("notes")` infers the `Note`
|
|
19
|
+
// row type — no casts. Import these hooks from this module (not from
|
|
20
|
+
// the package) so they stay bound.
|
|
21
|
+
export const { BaerlyProvider, useQuery, useMutation } = createBaerlyReact<typeof config>();
|
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
|
},
|