@gusto/create-baerly-storage 0.3.0 → 0.4.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.
@@ -1,15 +1,23 @@
1
1
  # minimal-node
2
2
 
3
- A baerly app scaffolded with `@gusto/create-baerly-storage` for the **Node** target —
4
- any host that runs `node server.js` (Railway, Render, Fly without
5
- Docker, Heroku, a VM, a container scheduler, your laptop). Uses
6
- `@gusto/baerly-storage/node` against an S3-compatible bucket (AWS S3, R2 via
7
- S3-compat, Minio, etc.). Ships `auth: "none"` so the day-1 happy
8
- path works with zero env vars; flip to a shared secret or wire
9
- `bearerJwt` against your OIDC IdP before deploy — see "Going to
10
- production" below.
11
-
12
- **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).
3
+ A baerly-storage app scaffolded with `@gusto/create-baerly-storage` for
4
+ the **Node** target — any host that runs `node server.js` (Railway,
5
+ Render, Fly without Docker, Heroku, a VM, a container scheduler, your
6
+ laptop). Runs zero-config on local filesystem storage out of the box;
7
+ promote to an S3-compatible bucket via `@gusto/baerly-storage/node` for
8
+ production. AWS S3 and Cloudflare R2 are the production-supported
9
+ targets; MinIO is the local conformance target, and other endpoints
10
+ require `baerly doctor --bucket` plus owner validation. Ships
11
+ `auth: "none"` so the day-1 happy path works with zero env vars; flip
12
+ to a shared secret or wire `bearerJwt` against your OIDC IdP before
13
+ deploy — see "Going to production" below.
14
+
15
+ **In production, the S3-compatible bucket is the durable state**
16
+ (locally, a `./.baerly-data` directory stands in). The Node process is
17
+ trusted app code with bucket credentials; it applies the
18
+ baerly-storage protocol, but it is not a database server. No daemon,
19
+ lock table, scheduler, or idle database bill; maintenance is automatic
20
+ and write-triggered.
13
21
 
14
22
  To ship a production Dockerfile alongside, scaffold with
15
23
  `--with=docker` — the add-on writes a multi-stage distroless Dockerfile,
@@ -25,13 +33,13 @@ minimal-node/
25
33
  ├── tsconfig.server.json # Node server TS project (src/server)
26
34
  ├── vite.config.ts # Vite SPA build → dist/client/
27
35
  ├── index.html # SPA shell — Vite's entry point
28
- ├── .env.example # storage creds, verifier, observability
36
+ ├── .env.example # storage selection (local-fs default) + PORT
29
37
  ├── baerly.config.ts # app, tenant, target, domain
30
38
  ├── AGENTS.md # deeper guide: predicates, schemas,
31
39
  │ # auth recipes, graduation
32
40
  ├── src/
33
41
  │ ├── server/
34
- │ │ └── index.ts # baerlyNode({ config, storage, verifier, webRoot }).listen(PORT)
42
+ │ │ └── index.ts # baerlyNode({ config, storage, webRoot }).listen(PORT)
35
43
  │ └── web/
36
44
  │ └── main.ts # SPA client entry — bundled into dist/client/
37
45
  └── README.md
@@ -47,27 +55,43 @@ pnpm dev
47
55
  `pnpm dev` runs `vite`. `baerlyDev()` from `@gusto/baerly-storage/dev/vite`
48
56
  mounts the Node HTTP listener as Connect middleware on the same Vite
49
57
  process that serves the SPA, so `GET /` hits the SPA on
50
- `http://localhost:5173/` and anything baerly handles (e.g.
58
+ `http://localhost:5173/` and anything baerly-storage handles (e.g.
51
59
  `GET /v1/healthz`) is served on the same origin — one process, one
52
60
  port, SPA + HMR + `/v1/*` in one command. Storage is `LocalFsStorage`
53
61
  rooted at `.baerly-data/`, so first-touch needs no S3 creds, no JWKS,
54
62
  and no second process.
55
63
 
56
- For production-shaped local runs (S3 and the bundled SPA served
57
- from `dist/client/`):
64
+ For production-shaped local runs (the built SPA served from
65
+ `dist/client/` alongside `/v1/*`):
58
66
 
59
67
  ```sh
60
68
  pnpm build
69
+ pnpm start
70
+ ```
71
+
72
+ `pnpm start` defaults to `localFsStorage()` (persists to
73
+ `./.baerly-data`, zero credentials, single-node only). To opt into
74
+ S3 or R2:
75
+
76
+ ```sh
77
+ # AWS S3
61
78
  BUCKET=... AWS_ACCESS_KEY_ID=... AWS_SECRET_ACCESS_KEY=... pnpm start
79
+
80
+ # Cloudflare R2
81
+ R2_ACCOUNT_ID=... BUCKET=... AWS_ACCESS_KEY_ID=... AWS_SECRET_ACCESS_KEY=... pnpm start
62
82
  ```
63
83
 
64
84
  The server reads `BUCKET`, `AWS_ACCESS_KEY_ID`,
65
- `AWS_SECRET_ACCESS_KEY` at startup. The default `auth: "none"`
66
- posture needs no auth env vars; if you adopt Pattern B / C from
67
- "Going to production" below, also set `SHARED_SECRET` (Pattern B)
68
- or `JWKS_URL` + `JWT_ISSUER` + `JWT_AUDIENCE` (Pattern C). Optional:
69
- `R2_ACCOUNT_ID` (switches the storage factory from `s3Storage` to
70
- `r2Storage`), `AWS_REGION`, `PORT`, `TENANT`, `WEB_ROOT`.
85
+ `AWS_SECRET_ACCESS_KEY` at startup; when those are absent it falls
86
+ back to `localFsStorage()` for local runs. **In a detected deployment
87
+ (`NODE_ENV=production` or a known PaaS) it refuses to start and requires
88
+ a bucket** — local-fs is local-dev only (single-process, no
89
+ cross-process CAS or crash durability). The default `auth: "none"`
90
+ posture needs no auth env vars. The default entrypoint also reads
91
+ optional `AWS_REGION` and `PORT`. There is no `WEB_ROOT` env var — the SPA
92
+ path is the hard-coded `webRoot: "dist/client"` in
93
+ `src/server/index.ts`. Auth, tenant, and maintenance env vars require
94
+ adopting the documented code/config recipe first.
71
95
 
72
96
  Maintenance (compaction + GC) is automatic and in-band: it runs
73
97
  inline on the rare write that crosses a maintenance trigger — no env
@@ -77,9 +101,9 @@ snapshot ceiling and `BAERLY_MAINTENANCE_DISABLE=1` is a kill switch.
77
101
  For an explicit out-of-band sweep, call `runScheduledMaintenance`
78
102
  from `@gusto/baerly-storage`.
79
103
 
80
- After `pnpm build`, `http://localhost:8080/` serves the built SPA
81
- out of `dist/client/` and `http://localhost:8080/v1/*` is the
82
- baerly HTTP surface — single origin, no CORS.
104
+ After `pnpm build`, `pnpm start` serves the Vite-built SPA from
105
+ `dist/client/` on `http://localhost:8080/` and the baerly-storage HTTP
106
+ surface on `http://localhost:8080/v1/*` — single origin, no CORS.
83
107
 
84
108
  `pnpm typecheck` runs `tsc -b --noEmit` across both project
85
109
  references.
@@ -89,7 +113,12 @@ references.
89
113
  This scaffold runs anywhere `node server.js` runs. The `package.json`
90
114
  exposes `build` (Vite SPA + TS check) and `start`
91
115
  (`node --experimental-strip-types src/server/index.ts`); arrange your
92
- host to run `pnpm install && pnpm build`, then `pnpm start`.
116
+ host to run `pnpm install && pnpm build`, then `pnpm start` with the
117
+ storage/auth env vars exported or configured in the process manager.
118
+ A deployment must set a durable bucket (`BUCKET` + `AWS_*`, or
119
+ `R2_ACCOUNT_ID` + creds); the server fails loud rather than running on
120
+ local-fs, which is local-dev only. Self-hosting without a cloud bucket,
121
+ run MinIO on the box or use SQLite + Litestream.
93
122
 
94
123
  Concrete shapes:
95
124
 
@@ -98,10 +127,12 @@ Concrete shapes:
98
127
  repo, set env vars from `.env.example` in the dashboard, deploy.
99
128
  The platform's buildpack detects Node and runs the root scripts.
100
129
  - **VM / bare-metal**: clone, install Node 24+, copy `.env.example`
101
- to `.env`, run `pnpm install && pnpm build && pnpm start` under
102
- your process manager of choice (systemd, pm2, etc.).
130
+ to `.env` as a template, then export those values or configure them
131
+ in your process manager (Node does not load `.env` automatically).
132
+ Run `pnpm install && pnpm build && pnpm start` under systemd, pm2,
133
+ or your process manager of choice.
103
134
  - **Container** (Docker, k8s, ECS, Fly Machines with a Dockerfile):
104
- scaffold with `pnpm create @gusto/baerly-storage@latest --target=node --with=docker` to add
135
+ scaffold with `pnpm create @gusto/baerly-storage@latest my-app --target=node --with=docker` to add
105
136
  a production Dockerfile, `.dockerignore`, and `healthcheck.js`
106
137
  alongside this shape, then `docker build .`.
107
138
 
@@ -115,9 +146,9 @@ Verify: `curl https://<your-service>/v1/healthz`.
115
146
  users: `@gusto/create-baerly-storage` mirrors `AGENTS.md` to `CLAUDE.md` at
116
147
  scaffold time.)
117
148
  2. **Declare your first collection schema** in `baerly.config.ts`
118
- via `defineConfig({ collections: { ... } })` and pass it to
119
- `Db.create({ ..., collections })`. Schema validation is live;
120
- bad inserts return 400.
149
+ via `defineConfig({ collections: { ... } })`. The Node adapter
150
+ passes that config to `Db.create({ storage, app, tenant, config })`,
151
+ so schema validation is live and bad inserts return 400.
121
152
  3. **Set up production auth** — follow `AGENTS.md` → "Going to
122
153
  production". Pattern B flips `auth: "shared-secret"` and reads
123
154
  `SHARED_SECRET` from `process.env`; Pattern C wires `bearerJwt`
@@ -128,16 +159,16 @@ Verify: `curl https://<your-service>/v1/healthz`.
128
159
 
129
160
  ## When to graduate
130
161
 
131
- baerly is designed for the small-to-medium operating point. Past these
132
- thresholds, S3 list-prefix latency and per-class operation pricing
133
- start to dominate, and you're better off on a real database:
162
+ baerly-storage is designed for the small-to-medium operating point.
163
+ Past these thresholds, S3 list-prefix latency and per-class operation
164
+ pricing starts to dominate, and you've outgrown the workload envelope — move to a database service:
134
165
 
135
- - **~30 writes / minute / collection**
136
- - **~10 GB / tenant**
137
- - **~100 collections / tenant**
166
+ - **~30 writes / minute / collection** — per-collection throughput estimate (CAS-livelock model)
167
+ - **>10 GB / tenant** — R2 free-tier storage cost line (a billing signal, not a protocol ceiling)
168
+ - **~100 collections / tenant** — soft fan-out guideline (linear cost, bench-grounded; nothing enforces it)
138
169
 
139
- When you cross the soft ceiling, graduation is mechanical:
140
- `baerly export --target=postgres` walks your log entries (already Debezium-style CDC change events) into a real DB. If your
170
+ When you cross these signals, graduation is mechanical:
171
+ `baerly export --target=postgres` walks your log entries (already Debezium-style CDC change events) into a database service. If your
141
172
  deploy target is Cloudflare Workers and you'll accept Cloudflare
142
173
  lock-in, [D1](https://developers.cloudflare.com/d1/) is cheaper
143
174
  per-write at M-size and is a natural next step. If you're on
@@ -145,7 +176,7 @@ AWS, on-prem, or want your data portable, managed Postgres is
145
176
  the typical destination. Either way — graduation is a Baerly win,
146
177
  not a churn event.
147
178
 
148
- **Export to a real database** (swap `--target=` for `sqlite`,
179
+ **Export to a database service** (swap `--target=` for `sqlite`,
149
180
  `postgres`, or `d1`):
150
181
 
151
182
  ```sh
@@ -13,14 +13,14 @@
13
13
  },
14
14
  "dependencies": {
15
15
  "@gusto/baerly-storage": "workspace:*",
16
- "aws4fetch": "^1.0.20"
16
+ "aws4fetch": "1.0.20"
17
17
  },
18
18
  "devDependencies": {
19
- "@types/node": "^25.9.2",
20
- "happy-dom": "^20.10.2",
19
+ "@types/node": "^26.0.1",
20
+ "happy-dom": "^20.10.6",
21
21
  "typescript": "^6.0.3",
22
- "vite": "^8.0.16",
23
- "vitest": "^4.1.8"
22
+ "vite": "^8.1.2",
23
+ "vitest": "^4.1.9"
24
24
  },
25
25
  "packageManager": "pnpm@11.1.2"
26
26
  }
@@ -5,42 +5,34 @@
5
5
  * with no header check. See AGENTS.md "Going to production" for
6
6
  * the recipe to flip `auth` or wire a custom verifier.
7
7
  *
8
- * Storage: AWS S3 by default; set `R2_ACCOUNT_ID` to switch to
9
- * Cloudflare R2 via the S3-compat endpoint.
8
+ * Storage: zero-config `LocalFsStorage` rooted at ./.baerly-data for
9
+ * local development — no credentials. Set `BUCKET` (+ AWS creds) for AWS
10
+ * S3, or `R2_ACCOUNT_ID` (+ creds) for Cloudflare R2. In a detected
11
+ * deployment (NODE_ENV=production or a known PaaS) the server REFUSES to
12
+ * start without a bucket — local-fs is a local-dev convenience only
13
+ * (single-process, no cross-process CAS, no crash durability), never a
14
+ * production store — so a missing/typo'd bucket fails loud instead of
15
+ * silently losing data.
10
16
  */
11
- import { baerlyNode, r2Storage, s3Storage } from "@gusto/baerly-storage/node";
12
- import type { Storage } from "@gusto/baerly-storage";
17
+ import { baerlyNode } from "@gusto/baerly-storage/node";
13
18
  import config from "../../baerly.config.ts";
19
+ import { resolveStorage } from "./resolve-storage.ts";
14
20
 
15
- const reqEnv = (name: string): string => {
16
- const v = process.env[name];
17
- if (v === undefined || v === "") {
18
- throw new Error(`Missing required env var: ${name}`);
19
- }
20
- return v;
21
- };
21
+ // Pick the storage backend from the environment (R2 / S3 / local-fs),
22
+ // failing loud if a deployment has no bucket. The policy lives in
23
+ // `./resolve-storage.ts` — edit it there to change how your app maps
24
+ // env vars to storage.
25
+ const { storage, label: storageLabel } = resolveStorage();
22
26
 
23
- const storage: Storage =
24
- process.env["R2_ACCOUNT_ID"] !== undefined
25
- ? r2Storage({
26
- accountId: reqEnv("R2_ACCOUNT_ID"),
27
- bucket: reqEnv("BUCKET"),
28
- credentials: {
29
- accessKeyId: reqEnv("AWS_ACCESS_KEY_ID"),
30
- secretAccessKey: reqEnv("AWS_SECRET_ACCESS_KEY"),
31
- },
32
- })
33
- : s3Storage({
34
- region: process.env["AWS_REGION"] ?? "us-east-1",
35
- bucket: reqEnv("BUCKET"),
36
- credentials: {
37
- accessKeyId: reqEnv("AWS_ACCESS_KEY_ID"),
38
- secretAccessKey: reqEnv("AWS_SECRET_ACCESS_KEY"),
39
- },
40
- });
27
+ // Announce the effective backend so the chosen store (and any surprise
28
+ // local-fs fallback) is visible in the deploy logs, not a surprise.
29
+ console.log(`[baerly] storage=${storageLabel}`);
41
30
 
42
31
  const PORT = Number(process.env["PORT"] ?? 8080);
43
32
 
44
- await baerlyNode({ config, storage }).listen(PORT);
33
+ // `webRoot` serves the Vite-built SPA from `dist/client/` (the
34
+ // `vite.config.ts` `build.outDir`) in production; `/v1/*` is handled
35
+ // by the kernel, everything else falls back to the SPA shell.
36
+ await baerlyNode({ config, storage, webRoot: "dist/client" }).listen(PORT);
45
37
 
46
38
  console.log(`minimal-node listening on :${PORT}`);
@@ -0,0 +1,18 @@
1
+ /**
2
+ * Storage selection is your app's policy, surfaced here as an editable
3
+ * seam. The default is the library's `resolveStorageFromEnv`, in priority
4
+ * order:
5
+ * 1. R2_ACCOUNT_ID set → Cloudflare R2 (S3-compat endpoint)
6
+ * 2. BUCKET set → AWS S3
7
+ * 3. neither, local dev → LocalFsStorage (zero credentials)
8
+ * 4. neither, deployed → throw. It never silently falls back to a
9
+ * non-durable store (local-fs or in-memory) in a deployment — that
10
+ * is the failure mode that loses data in production.
11
+ *
12
+ * Replace this re-export with your own `(env) => ResolvedStorage` if your
13
+ * policy differs (a custom endpoint, MinIO, GCS, …). The resolver is
14
+ * exported and tested in `@gusto/baerly-storage/node` so every app shares
15
+ * one safe default instead of hand-rolling one.
16
+ */
17
+ export { resolveStorageFromEnv as resolveStorage } from "@gusto/baerly-storage/node";
18
+ export type { ResolvedStorage } from "@gusto/baerly-storage/node";
@@ -1,4 +1,3 @@
1
- import { resolve } from "node:path";
2
1
  import { defineConfig } from "vite";
3
2
  import { baerlyDev } from "@gusto/baerly-storage/dev/vite";
4
3
  import config from "./baerly.config.ts";
@@ -9,7 +8,6 @@ export default defineConfig({
9
8
  plugins: [
10
9
  baerlyDev({
11
10
  config,
12
- dataDir: resolve(import.meta.dirname, ".baerly-data"),
13
11
  }),
14
12
  ],
15
13
  });
@@ -1,16 +1,17 @@
1
1
  ---
2
2
  title: AGENTS.md — agent guidance for react-cloudflare
3
3
  audience: agent
4
- summary: How to develop and deploy react-cloudflare, a baerly app.
5
- tags: [agent-entry, baerly]
4
+ summary: How to develop and deploy react-cloudflare, a baerly-storage app.
5
+ tags: [agent-entry, baerly-storage]
6
6
  ---
7
7
 
8
8
  # AGENTS.md
9
9
 
10
+ <!-- stop:start -->
10
11
  ## STOP — read this before writing any storage code
11
12
 
12
13
  Your training data is dense with Postgres + Prisma/Drizzle, Mongo,
13
- and Firebase patterns. **None of them apply here.** This is a baerly
14
+ and Firebase patterns. **None of them apply here.** This is a baerly-storage
14
15
  app — a small, LLM-legible document database with a narrow API on top
15
16
  of S3-compatible storage. Before writing or modifying storage code,
16
17
  read:
@@ -18,7 +19,7 @@ read:
18
19
  - **`node_modules/@gusto/baerly-storage/dist/API.md`** — hand-authored
19
20
  public-API quickref. Read first. Lists every method, every error
20
21
  code, every example. If a pattern you want to use isn't here, it
21
- doesn't exist in baerly.
22
+ doesn't exist in baerly-storage.
22
23
  - **`node_modules/@gusto/baerly-storage/dist/*.d.ts`** — authoritative type
23
24
  signatures. `Db`, `Collection<T>`, `Query<T>`, and `Predicate<T>` are
24
25
  the whole API surface.
@@ -37,11 +38,13 @@ Common anti-patterns that compile but are wrong:
37
38
  picks the index automatically from `IndexDefinition`s in
38
39
  `baerly.config.ts`. See **Indexes** below.
39
40
 
41
+ <!-- stop:end -->
40
42
  ## What this is
41
43
 
42
- `react-cloudflare` is a baerly app scaffolded with `create-baerly-storage`.
43
- The Worker-side server lives in `src/server/`; the React client lives
44
- in `src/web/`. Configuration lives in `baerly.config.ts`.
44
+ `react-cloudflare` is a baerly-storage app scaffolded with
45
+ `create-baerly-storage`. The Worker-side server lives in `src/server/`;
46
+ the React client lives in `src/web/`. Configuration lives in
47
+ `baerly.config.ts`.
45
48
 
46
49
  Single package, single `vite` process: `@cloudflare/vite-plugin` runs
47
50
  the Worker inside `workerd` alongside the SPA dev server, and
@@ -55,19 +58,18 @@ shape declared in `baerly.config.ts`. The bare server-only version is
55
58
  `pnpm create @gusto/baerly-storage <app> --target=cloudflare`; this one is
56
59
  `--target=cloudflare --starter=react`.
57
60
 
58
- Public API docs: https://docs.baerly.dev/ (the JSDoc on
59
- `baerly-storage`'s `Db` and `Collection` is the canonical reference;
60
- read it via your editor's TS LS or via the published types).
61
+ Public API docs: the JSDoc on `baerly-storage`'s `Db` and `Collection`
62
+ is the canonical reference; read it via your editor's TS LS, the
63
+ published types, or `node_modules/@gusto/baerly-storage/dist/API.md`.
61
64
 
62
65
  ## Toolchain
63
66
 
64
67
  - **Package manager:** pnpm. The emitted repo pins
65
68
  `packageManager: pnpm@11.1.2`.
66
69
  - **Test runner:** vitest.
67
- - **Type checker:** TypeScript 5.6+. (The baerly-storage monorepo
68
- itself uses TypeScript 7 via `@typescript/native-preview`; this
69
- template tracks the broadly-compatible TS major so scaffolded
70
- apps work with the wider ecosystem.)
70
+ - **Type checker:** TypeScript 6.x, as pinned in `package.json`.
71
+ (The baerly-storage monorepo itself uses TypeScript 7 via
72
+ `@typescript/native-preview`.)
71
73
  - **`erasableSyntaxOnly`** is enabled in every `tsconfig*.json` so the
72
74
  code stays compatible with type-stripping runtimes (Node's
73
75
  `--experimental-strip-types`, esbuild's strip path). The flag bans
@@ -86,7 +88,7 @@ read it via your editor's TS LS or via the published types).
86
88
  | `pnpm install` | One-time bootstrap — the scaffold ships without `node_modules/`, so `pnpm verify` / `pnpm dev` fail with `Cannot find package '…'` until this runs once | seconds to a minute |
87
89
  | `pnpm verify` | `pnpm run typecheck && pnpm run test` — the green-light gate; what an agent should run as the smoke check before claiming the change works | seconds |
88
90
  | `pnpm typecheck` | TS typecheck across the worker + web project references (`tsc -b --noEmit`) | seconds |
89
- | `pnpm test` | `vitest run --passWithNoTests` — standalone `vitest.config.ts` (Node env, ignores `vite.config.ts` so the Cloudflare plugin doesn't load) | seconds |
91
+ | `pnpm test` | `vitest run` — standalone `vitest.config.ts` (Node env, ignores `vite.config.ts` so the Cloudflare plugin doesn't load) | seconds |
90
92
  | `pnpm dev` | Run `vite` — the Cloudflare plugin runs the Worker inside `workerd` next to the SPA dev server; same origin on :5173 | seconds to start |
91
93
  | `pnpm build` | `tsc -b && vite build` — emits `dist/client/` for the Workers Assets binding | seconds |
92
94
  | `pnpm deploy` | `wrangler deploy` — ships Worker + assets in one shipment (auto-creates R2 on first run via `--x-provision`) | seconds |
@@ -299,7 +301,7 @@ http://localhost:5173/<path>`) before declaring the task complete.
299
301
  (without the `doc` wrapper) returns
300
302
  `400 SchemaError "Request body must be { doc: object }"` — the
301
303
  wording is locked by `assertJsonBodyField` in the kernel. Canonical
302
- reference: the `Routes` type and the JSDoc on `createRouter` in
304
+ reference: the JSDoc on `createRouter` in
303
305
  `baerly-storage`.
304
306
 
305
307
  - **Auth** — your scaffold ships `auth: "none"` in `baerly.config.ts`:
@@ -542,23 +544,24 @@ your own schedule. Not required for steady-state operation.
542
544
 
543
545
  ## When to graduate
544
546
 
545
- baerly is designed for the small-to-medium operating point. The cost
546
- model puts the soft ceiling at:
547
+ baerly-storage is designed for the small-to-medium operating point.
548
+ The cost model puts the soft ceiling at:
547
549
 
548
- - **~30 writes / minute / collection**
549
- - **~10 GB / tenant**
550
- - **~100 collections / tenant**
550
+ - **~30 writes / minute / collection** (throughput ceiling — model/estimate)
551
+ - **>10 GB / tenant stored** (R2 free-tier storage line — a cost signal, not a protocol ceiling)
552
+ - **~100 collections / tenant** (soft fan-out guideline — bench-grounded linear cost)
551
553
 
552
- Past those, S3 list-prefix latency, snapshot fold cost, and per-class
553
- op pricing start to dominate; you're better off on a real database.
554
+ At M-size (~30 writes/min) the projected cost is ~$18/mo on R2. Past
555
+ those, per-class op pricing and fan-out scan cost start to dominate;
556
+ you've outgrown the workload envelope — move to a database service (D1 / Postgres) suited to higher scale.
554
557
  Pick your graduation target:
555
558
  - **Cloudflare Workers + lock-in OK:** [D1](https://developers.cloudflare.com/d1/) — cheaper per-write at M-size.
556
559
  - **Off-Workers or portability matters:** managed Postgres.
557
560
  - **Single-instance Node:** SQLite via Litestream.
558
561
 
559
562
  Either way, the export below is mechanical because log entries are
560
- Debezium-style CDC change events — graduation is a Baerly win,
561
- not a churn event.
563
+ Debezium-style CDC change events — graduation is a baerly-storage
564
+ win, not a churn event.
562
565
 
563
566
  **Estimate your current rate:** for Node/self-hosted buckets,
564
567
  `baerly admin usage --target=node --bucket=<bucket-uri> --app=<app>
@@ -718,8 +721,9 @@ JSON-merge-patch (RFC 7386) semantics apply on `update()`:
718
721
  omitting `tags` from an update preserves the existing value;
719
722
  passing `tags: null` deletes the field; passing `tags: []` sets
720
723
  it to an empty array. Note that `null` is the deletion sentinel,
721
- not a storable value — `DocumentValue` doesn't include `null`,
722
- so `find()` returns deleted fields as `undefined`, not `null`.
724
+ not a storable value — `DocumentValue` doesn't include `null`, so
725
+ subsequent `get()` / query results expose deleted optional fields as
726
+ `undefined`, not `null`.
723
727
  That's why this recipe uses `.optional()` and not `.nullable()`.
724
728
 
725
729
  ## Pointers
@@ -1,13 +1,17 @@
1
1
  # react-cloudflare
2
2
 
3
- A baerly app scaffolded with `@gusto/create-baerly-storage` for the **Cloudflare
4
- Workers** target, with a React + Vite SPA. Single-bucket R2-backed
5
- deployment via `@gusto/baerly-storage/cloudflare`. Ships `auth: "none"`
6
- so the day-1 happy path works with zero env vars, plus a
7
- one-collection `notes` schema you extend; flip to Cloudflare Access
8
- or a shared secret before deploy — see "Production auth" below.
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).
3
+ A baerly-storage app scaffolded with `@gusto/create-baerly-storage` for
4
+ the **Cloudflare Workers** target, with a React + Vite SPA.
5
+ Single-bucket R2-backed deployment via
6
+ `@gusto/baerly-storage/cloudflare`. Ships `auth: "none"` so the day-1
7
+ happy path works with zero env vars, plus a one-collection `notes`
8
+ schema you extend; flip to Cloudflare Access or a shared secret before
9
+ deploy — see "Production auth" below.
10
+
11
+ **The R2 bucket is the durable state.** The Worker is trusted app code
12
+ with an R2 binding; it applies the baerly-storage protocol, but it is
13
+ not a database server. No daemon, lock table, scheduler, or idle
14
+ database bill; maintenance is automatic and write-triggered.
11
15
 
12
16
  ## What you got
13
17
 
@@ -103,11 +107,13 @@ follow `AGENTS.md` → "Going to production":
103
107
 
104
108
  ## When to graduate
105
109
 
106
- baerly is sized for the small-to-medium operating point. Past
107
- ~30 writes/min/collection, ~10 GB/tenant, or ~100 collections/
108
- tenant, graduate to D1 or Postgres via `baerly export
109
- --target=postgres`. Your data was already in your bucket; the
110
- export is a mechanical translator, not a vendor migration.
110
+ baerly-storage is sized for the small-to-medium operating point. Past
111
+ ~30 writes/min/collection (throughput estimate), the R2 free-tier
112
+ storage cost line (>10 GB/tenant), or the soft fan-out guideline
113
+ (~100 collections/tenant — linear cost, nothing enforces it),
114
+ graduate to D1 or Postgres via `baerly export --target=postgres`.
115
+ Your data was already in your bucket; the export is a mechanical
116
+ translator, not a vendor migration.
111
117
 
112
118
  ## Pointers
113
119
 
@@ -1,4 +1,4 @@
1
- <!DOCTYPE html>
1
+ <!doctype html>
2
2
  <html lang="en">
3
3
  <head>
4
4
  <meta charset="UTF-8" />
@@ -13,22 +13,22 @@
13
13
  },
14
14
  "dependencies": {
15
15
  "@gusto/baerly-storage": "workspace:*",
16
- "react": "^19.0.0",
17
- "react-dom": "^19.0.0",
16
+ "react": "^19.2.7",
17
+ "react-dom": "^19.2.7",
18
18
  "zod": "^4.4.3"
19
19
  },
20
20
  "devDependencies": {
21
- "@cloudflare/vite-plugin": "^1.40.1",
22
- "@cloudflare/workers-types": "^4",
23
- "@types/node": "^25.9.2",
21
+ "@cloudflare/vite-plugin": "^1.42.4",
22
+ "@cloudflare/workers-types": "^4.20260630.1",
23
+ "@types/node": "^26.0.1",
24
24
  "@types/react": "^19.2.17",
25
- "@types/react-dom": "^19.0.0",
26
- "@vitejs/plugin-react": "^6.0.2",
27
- "happy-dom": "^20.10.2",
25
+ "@types/react-dom": "^19.2.3",
26
+ "@vitejs/plugin-react": "^6.0.3",
27
+ "happy-dom": "^20.10.6",
28
28
  "typescript": "^6.0.3",
29
- "vite": "^8.0.16",
30
- "vitest": "^4.1.8",
31
- "wrangler": "^4.99.0"
29
+ "vite": "^8.1.2",
30
+ "vitest": "^4.1.9",
31
+ "wrangler": "^4.106.0"
32
32
  },
33
33
  "packageManager": "pnpm@11.1.2"
34
34
  }
@@ -1,13 +1,20 @@
1
- # Storage credentials (AWS S3 default; R2 when R2_ACCOUNT_ID is set).
2
- # For Minio / GCS, edit `src/server/index.ts` to use the matching
3
- # factory from `baerly-storage/node` (`minioStorage` / `gcsStorage`).
1
+ # Storage selection. Defaults to local filesystem storage
2
+ # (./.baerly-data, zero credentials) for local dev. A deployment
3
+ # (NODE_ENV=production or a known PaaS) requires a bucket below — the
4
+ # server fails loud rather than running on local-fs, which is local-dev
5
+ # only. Self-hosting without a cloud bucket? Run MinIO on the box, or use
6
+ # SQLite + Litestream.
7
+ # MinIO is for local conformance. Other S3-compatible endpoints require
8
+ # `baerly doctor --bucket` plus owner validation; GCS S3-interop is not
9
+ # supported for database use today.
10
+ # AWS S3: set BUCKET + AWS creds (AWS_REGION optional).
4
11
  AWS_ACCESS_KEY_ID=
5
12
  AWS_SECRET_ACCESS_KEY=
6
13
  AWS_REGION=us-east-1
7
14
  BUCKET=
8
15
  # Set to your Cloudflare R2 account ID (left half of the
9
- # https://<account>.r2.cloudflarestorage.com endpoint) to switch
10
- # storage from AWS S3 to R2. Leave unset for AWS S3.
16
+ # https://<account>.r2.cloudflarestorage.com endpoint) to use R2
17
+ # instead of AWS S3 (still set BUCKET + AWS_* creds). Leave unset for S3.
11
18
  # R2_ACCOUNT_ID=
12
19
 
13
20
  # Server