@gusto/create-baerly-storage 0.3.0 → 0.4.1

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,16 +1,17 @@
1
1
  ---
2
2
  title: AGENTS.md — agent guidance for react-node
3
3
  audience: agent
4
- summary: How to develop and deploy react-node, a baerly app.
5
- tags: [agent-entry, baerly]
4
+ summary: How to develop and deploy react-node, 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,13 +38,15 @@ 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-node` is a baerly app scaffolded with `create-baerly-storage` for the
43
- Node target — any host that runs `node server.js` (Railway, Render,
44
- Fly without Docker, Heroku, a VM, a container scheduler). The
45
- Node-side server lives in `src/server/`; the React client lives in
46
- `src/web/`. Configuration lives in `baerly.config.ts`.
44
+ `react-node` is a baerly-storage app scaffolded with
45
+ `create-baerly-storage` for the Node target: any host that runs
46
+ `node server.js` (Railway, Render, Fly without Docker, Heroku, a VM, a
47
+ container scheduler). The Node-side server lives in `src/server/`; the
48
+ React client lives in `src/web/`. Configuration lives in
49
+ `baerly.config.ts`.
47
50
 
48
51
  Single package, single `vite` process: `baerlyDev()` from
49
52
  `@gusto/baerly-storage/dev/vite` mounts the Node HTTP listener as Connect
@@ -65,19 +68,18 @@ multi-stage distroless `Dockerfile`, a `.dockerignore`, and a
65
68
  `healthcheck.js` at the project root — wired to the same
66
69
  `pnpm install && pnpm build && pnpm start` flow.
67
70
 
68
- Public API docs: https://docs.baerly.dev/ (the JSDoc on
69
- `baerly-storage`'s `Db` and `Collection` is the canonical reference;
70
- read it via your editor's TS LS or via the published types).
71
+ Public API docs: the JSDoc on `baerly-storage`'s `Db` and `Collection`
72
+ is the canonical reference; read it via your editor's TS LS, the
73
+ published types, or `node_modules/@gusto/baerly-storage/dist/API.md`.
71
74
 
72
75
  ## Toolchain
73
76
 
74
77
  - **Package manager:** pnpm. The emitted repo pins
75
78
  `packageManager: pnpm@11.1.2`.
76
79
  - **Test runner:** vitest.
77
- - **Type checker:** TypeScript 5.6+. (The baerly-storage monorepo
78
- itself uses TypeScript 7 via `@typescript/native-preview`; this
79
- template tracks the broadly-compatible TS major so scaffolded
80
- apps work with the wider ecosystem.)
80
+ - **Type checker:** TypeScript 6.x, as pinned in `package.json`.
81
+ (The baerly-storage monorepo itself uses TypeScript 7 via
82
+ `@typescript/native-preview`.)
81
83
  - **`erasableSyntaxOnly`** is enabled in every `tsconfig*.json` so the
82
84
  code stays compatible with type-stripping runtimes (Node's
83
85
  `--experimental-strip-types`, esbuild's strip path). The flag bans
@@ -96,7 +98,7 @@ read it via your editor's TS LS or via the published types).
96
98
  | `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 |
97
99
  | `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 |
98
100
  | `pnpm typecheck` | TS typecheck across the `app` + `server` project references (`tsc -b --noEmit`) | seconds |
99
- | `pnpm test` | `vitest run --passWithNoTests` — standalone `vitest.config.ts` (Node env) | seconds |
101
+ | `pnpm test` | `vitest run` — standalone `vitest.config.ts` (Node env) | seconds |
100
102
  | `pnpm dev` | Run `vite` — `baerlyDev()` mounts the Node HTTP listener as Connect middleware next to the SPA dev server; same origin on :5173 | seconds to start |
101
103
  | `pnpm build` | `tsc -b && vite build` — emits `dist/client/` for the `baerlyNode({ webRoot })` static-serve branch | seconds |
102
104
  | `pnpm start` | `node --experimental-strip-types src/server/index.ts` — production entry; serves the SPA from `dist/client/` via `webRoot` | seconds to start |
@@ -113,7 +115,7 @@ http://localhost:5173/<path>`) before declaring the task complete.
113
115
 
114
116
  | Path | What it is |
115
117
  | -------------------------- | ---------------------------------------------------------------------------------------------------------------- |
116
- | `src/server/index.ts` | Server entry — composes `s3Storage` / `r2Storage` + a verifier and calls `baerlyNode({ ... }).listen(PORT)` |
118
+ | `src/server/index.ts` | Server entry — defaults to zero-config `localFsStorage()` (persists to `./.baerly-data`); promotes to `s3Storage` (AWS) when `BUCKET` is set or `r2Storage` (Cloudflare R2) when `R2_ACCOUNT_ID` is set; composes a verifier and calls `baerlyNode({ ... }).listen(PORT)` |
117
119
  | `src/web/` | React+Vite frontend. Served by the Node listener via `baerlyNode({ webRoot })` in production. |
118
120
  | `index.html` | SPA shell — Vite's entry point at the project root; references `/src/web/main.tsx`. |
119
121
  | `vite.config.ts` | Vite + `@vitejs/plugin-react` + `baerlyDev()` — mounts the Node HTTP listener as middleware so SPA + `/v1/*` share `:5173` in dev |
@@ -121,7 +123,7 @@ http://localhost:5173/<path>`) before declaring the task complete.
121
123
  | `tsconfig.app.json` | Client TS project (`src/web/`, DOM lib, `jsx: react-jsx`) |
122
124
  | `tsconfig.server.json` | Node server TS project (`src/server/`, Node lib) |
123
125
  | `baerly.config.ts` | App config — `app`, `tenant`, `target`, `collections` (schemas live here). Also exports the inferred `Note` row type used by the web client. |
124
- | `.env.example` | Source of truth for env vars the Node entry reads (`BUCKET`, `AWS_*`, the optional `BAERLY_MAINTENANCE_*` ops-plane tuners, etc.; `SHARED_SECRET` / `JWKS_URL` only needed if you adopt the "Going to production" auth recipes) |
126
+ | `.env.example` | Source of truth for env vars the default Node entry reads (`BUCKET`, `AWS_*`, optional `R2_ACCOUNT_ID`, optional `PORT`) |
125
127
 
126
128
  > **`baerly.config.ts` is dual-included.** Both `tsconfig.app.json`
127
129
  > and `tsconfig.server.json` `include` this file, so it must only
@@ -258,9 +260,10 @@ http://localhost:5173/<path>`) before declaring the task complete.
258
260
  });
259
261
  ```
260
262
 
261
- The adapter threads `collections` into `Db.create({ ... })` for
262
- you. Predicates the planner can't route fall back to the full
263
- scan with a metric bump — correctness is preserved.
263
+ The adapter passes your `config` into
264
+ `Db.create({ storage, app, tenant, config })` for you. Predicates the
265
+ planner can't route fall back to the full scan with a metric bump —
266
+ correctness is preserved.
264
267
 
265
268
  - **Schemas (live feature)** — schemas are validated on the server
266
269
  for every `insert` / `update` / `replace` when bound. Declare via
@@ -306,7 +309,7 @@ http://localhost:5173/<path>`) before declaring the task complete.
306
309
  (without the `doc` wrapper) returns
307
310
  `400 SchemaError "Request body must be { doc: object }"` — the
308
311
  wording is locked by `assertJsonBodyField` in the kernel. Canonical
309
- reference: the `Routes` type and the JSDoc on `createRouter` in
312
+ reference: the JSDoc on `createRouter` in
310
313
  `baerly-storage`.
311
314
 
312
315
  - **Auth** — your scaffold ships `auth: "none"` in `baerly.config.ts`:
@@ -384,31 +387,36 @@ Dev sees `JWKS_URL` as `undefined`, spread short-circuits, and
384
387
  `config.auth: "none"` runs. Prod sets `JWKS_URL` + `JWT_ISSUER` +
385
388
  `JWT_AUDIENCE` and `bearerJwt` engages. Use `tenantClaim` when your
386
389
  IdP issues one tenant per token; use `tenantPrefix` for single-tenant
387
- apps or tenancy enforced outside Baerly.
390
+ apps or tenancy enforced outside baerly-storage.
388
391
 
389
392
  <!-- pattern-c:end -->
390
- - **Storage backend** — `src/server/index.ts` picks between
391
- `s3Storage` (AWS) and `r2Storage` (Cloudflare R2 via S3-compat)
392
- based on whether `R2_ACCOUNT_ID` is set. To use **Minio**
393
- (self-hosted dev S3) or **GCS** (HMAC keys), swap the import to
394
- `minioStorage` / `gcsStorage` from `@gusto/baerly-storage/node`. All
395
- four factories take the same shape — a single bucket-name +
396
- credentials object — and hide `aws4fetch` / `@xmldom/xmldom`
397
- behind the package boundary. JSDoc `@example` blocks for each
398
- factory are visible in your editor's TS hover. The bucket name
399
- comes from the `BUCKET` env var; AWS credentials are read from
393
+ - **Storage backend** — `src/server/index.ts` resolves storage by env:
394
+ `R2_ACCOUNT_ID` → Cloudflare R2, else `BUCKET` → AWS S3, else
395
+ zero-config `localFsStorage()` (persists to `./.baerly-data`, no
396
+ credentials, local dev only). **In a detected deployment
397
+ (`NODE_ENV=production` or a known PaaS) the server fails loud and
398
+ requires a bucket** — local-fs is single-process with no cross-process
399
+ CAS or crash durability, so it is never a production store (there is no
400
+ opt-in). AWS S3 and Cloudflare R2 are the production-supported stores;
401
+ self-hosting without a cloud bucket, run **MinIO** on the box (also the
402
+ local/dev conformance target) or graduate to SQLite + Litestream. Other S3-compatible endpoints need a
403
+ green `baerly doctor --bucket` plus owner validation; GCS S3-interop
404
+ is not supported for database use today. The bucket name comes from
405
+ the `BUCKET` env var; AWS credentials are read from
400
406
  `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` (and optional
401
407
  `AWS_REGION`).
402
408
 
403
- - **Switching from static creds to EKS Pod Identity** — in
409
+ - **Switching from static creds to EKS** — in
404
410
  `src/server/index.ts`, swap `credentials: { accessKeyId,
405
- secretAccessKey }` for `credentials: fromEksPodIdentity()` and add
406
- `fromEksPodIdentity` to your import:
407
- `import { s3Storage, fromEksPodIdentity } from "@gusto/baerly-storage/node"`.
408
- The agent reads `AWS_CONTAINER_CREDENTIALS_FULL_URI` +
409
- `AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE` (EKS injects both). For
410
- IRSA / ECS / EC2 / other AWS contexts, see
411
- `packages/adapter-node/AGENTS.md` — pass any
411
+ secretAccessKey }` for `credentials: fromEks()` and add `fromEks`
412
+ to your import:
413
+ `import { s3Storage, fromEks } from "@gusto/baerly-storage/node"`.
414
+ `fromEks()` auto-detects the cluster's mechanism — EKS Pod Identity
415
+ (`AWS_CONTAINER_CREDENTIALS_FULL_URI` +
416
+ `AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE`) or IRSA (`AWS_ROLE_ARN` +
417
+ `AWS_WEB_IDENTITY_TOKEN_FILE`), both EKS-injected; to pin one, use
418
+ `fromEksPodIdentity()` or `fromWebIdentity()`. For ECS / EC2 / other
419
+ AWS contexts, see `packages/adapter-node/AGENTS.md` — pass any
412
420
  `() => Promise<Credentials>` or an `@aws-sdk/credential-providers`
413
421
  factory through the seam.
414
422
 
@@ -417,12 +425,16 @@ apps or tenancy enforced outside Baerly.
417
425
  `node --experimental-strip-types src/server/index.ts`. Arrange the
418
426
  host to run `pnpm install && pnpm build` (populates
419
427
  `dist/client/` for the `webRoot` static-serve branch) before
420
- `pnpm start`. Set env vars from `.env.example` in the host's
421
- config — at minimum `BUCKET`, `AWS_ACCESS_KEY_ID`,
422
- `AWS_SECRET_ACCESS_KEY`. The default scaffold's `auth: "none"`
423
- needs no auth env vars; if you adopt Pattern B / C from "Going to
424
- production" above, also set `SHARED_SECRET` (Pattern B) or
425
- `JWKS_URL` + `JWT_ISSUER` + `JWT_AUDIENCE` (Pattern C).
428
+ `pnpm start`. A deployment **must** configure a durable bucket:
429
+ `BUCKET` + `AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY` (S3) or
430
+ `R2_ACCOUNT_ID` + those creds (R2). With none set, the server fails
431
+ loud in a detected deployment (`NODE_ENV=production` or a known PaaS)
432
+ rather than running on local-fs, which is local-dev only. Self-hosting
433
+ without a cloud bucket, run MinIO on the box or use SQLite + Litestream.
434
+ The default scaffold's `auth: "none"` needs no
435
+ auth env vars; if you adopt Pattern B / C from "Going to production" above,
436
+ also set `SHARED_SECRET` (Pattern B) or `JWKS_URL` + `JWT_ISSUER` +
437
+ `JWT_AUDIENCE` (Pattern C).
426
438
 
427
439
  Shapes: **managed PaaS** (Railway, Render, DO App Platform, Fly
428
440
  without Docker, Heroku) auto-detects Node and runs the root
@@ -476,23 +488,24 @@ your own schedule. Not required for steady-state operation.
476
488
 
477
489
  ## When to graduate
478
490
 
479
- baerly is designed for the small-to-medium operating point. The cost
480
- model puts the soft ceiling at:
491
+ baerly-storage is designed for the small-to-medium operating point.
492
+ The cost model puts the soft ceiling at:
481
493
 
482
- - **~30 writes / minute / collection**
483
- - **~10 GB / tenant**
484
- - **~100 collections / tenant**
494
+ - **~30 writes / minute / collection** (throughput ceiling — model/estimate)
495
+ - **>10 GB / tenant stored** (R2 free-tier storage line — a cost signal, not a protocol ceiling)
496
+ - **~100 collections / tenant** (soft fan-out guideline — bench-grounded linear cost)
485
497
 
486
- Past those, S3 list-prefix latency, snapshot fold cost, and per-class
487
- op pricing start to dominate; you're better off on a real database.
498
+ At M-size (~30 writes/min) the projected cost is ~$26/mo on S3 (~$18/mo on R2). Past
499
+ those, per-class op pricing and fan-out scan cost start to dominate;
500
+ you've outgrown the workload envelope — move to a database service (D1 / Postgres) suited to higher scale.
488
501
  Pick your graduation target:
489
502
  - **Cloudflare Workers + lock-in OK:** [D1](https://developers.cloudflare.com/d1/) — cheaper per-write at M-size.
490
503
  - **Off-Workers or portability matters:** managed Postgres.
491
504
  - **Single-instance Node:** SQLite via Litestream.
492
505
 
493
506
  Either way, the export below is mechanical because log entries are
494
- Debezium-style CDC change events — graduation is a Baerly win,
495
- not a churn event.
507
+ Debezium-style CDC change events — graduation is a baerly-storage
508
+ win, not a churn event.
496
509
 
497
510
  **Estimate your current rate:** for Node/self-hosted buckets,
498
511
  `baerly admin usage --target=node --bucket=<bucket-uri> --app=<app>
@@ -652,8 +665,9 @@ JSON-merge-patch (RFC 7386) semantics apply on `update()`:
652
665
  omitting `tags` from an update preserves the existing value;
653
666
  passing `tags: null` deletes the field; passing `tags: []` sets
654
667
  it to an empty array. Note that `null` is the deletion sentinel,
655
- not a storable value — `DocumentValue` doesn't include `null`,
656
- so `find()` returns deleted fields as `undefined`, not `null`.
668
+ not a storable value — `DocumentValue` doesn't include `null`, so
669
+ subsequent `get()` / query results expose deleted optional fields as
670
+ `undefined`, not `null`.
657
671
  That's why this recipe uses `.optional()` and not `.nullable()`.
658
672
 
659
673
  ## Pointers
@@ -1,16 +1,24 @@
1
1
  # react-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, plus a React + Vite SPA and a
9
- one-collection `notes` schema you extend; flip to a shared secret
10
- or wire `bearerJwt` against your OIDC IdP before deploy — see
11
- "Production auth" below.
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).
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, plus a
12
+ React + Vite SPA and a one-collection `notes` schema you extend; flip
13
+ to a shared secret or wire `bearerJwt` against your OIDC IdP before
14
+ deploy — see "Production auth" below.
15
+
16
+ **In production, the S3-compatible bucket is the durable state**
17
+ (locally, a `./.baerly-data` directory stands in). The Node process is
18
+ trusted app code with bucket credentials; it applies the
19
+ baerly-storage protocol, but it is not a database server. No daemon,
20
+ lock table, scheduler, or idle database bill; maintenance is automatic
21
+ and write-triggered.
14
22
 
15
23
  To ship a production Dockerfile alongside, scaffold with
16
24
  `--with=docker` — the add-on writes a multi-stage distroless Dockerfile,
@@ -26,7 +34,7 @@ react-node/
26
34
  ├── tsconfig.server.json # Node server TS project (src/server)
27
35
  ├── vite.config.ts # Vite + @vitejs/plugin-react + baerlyDev()
28
36
  ├── index.html # SPA shell — Vite's entry point
29
- ├── .env.example # storage creds, verifier, observability
37
+ ├── .env.example # storage selection (local-fs default) + PORT
30
38
  ├── baerly.config.ts # app, tenant, target, NoteSchema, `Note` type
31
39
  ├── AGENTS.md # deeper guide: hooks, schema, auth, deploy
32
40
  ├── CLAUDE.md # same content (Claude Code reads this)
@@ -48,11 +56,10 @@ pnpm install
48
56
  pnpm dev
49
57
  ```
50
58
 
51
-
52
59
  `pnpm dev` runs `vite`. `baerlyDev()` from `@gusto/baerly-storage/dev/vite`
53
60
  mounts the Node HTTP listener as Connect middleware on the same Vite
54
61
  process that serves the SPA, so `GET /` hits the SPA on
55
- `http://localhost:5173/` and anything baerly handles (e.g.
62
+ `http://localhost:5173/` and anything baerly-storage handles (e.g.
56
63
  `GET /v1/healthz`, `POST /v1/c/notes`) is served on the same origin —
57
64
  one process, one port, SPA + HMR + `/v1/*` in one command. Storage is
58
65
  `LocalFsStorage` rooted at `.baerly-data/`, so first-touch needs no
@@ -62,21 +69,36 @@ Open <http://localhost:5173>. Type a note, hit "Add note." Open a
62
69
  second tab — inserts, edits, and deletes in one tab appear in the
63
70
  other over the `/v1/since?collection=notes&cursor=...` long-poll.
64
71
 
65
- For production-shaped local runs (S3 and the bundled SPA served
66
- from `dist/client/`):
72
+ For production-shaped local runs (the bundled SPA served from
73
+ `dist/client/`):
67
74
 
68
75
  ```sh
69
76
  pnpm build
77
+ pnpm start
78
+ ```
79
+
80
+ `pnpm start` defaults to `localFsStorage()` (persists to
81
+ `./.baerly-data`, zero credentials, single-node only). To opt into
82
+ S3 or R2:
83
+
84
+ ```sh
85
+ # AWS S3
70
86
  BUCKET=... AWS_ACCESS_KEY_ID=... AWS_SECRET_ACCESS_KEY=... pnpm start
87
+
88
+ # Cloudflare R2
89
+ R2_ACCOUNT_ID=... BUCKET=... AWS_ACCESS_KEY_ID=... AWS_SECRET_ACCESS_KEY=... pnpm start
71
90
  ```
72
91
 
73
92
  The server reads `BUCKET`, `AWS_ACCESS_KEY_ID`,
74
- `AWS_SECRET_ACCESS_KEY` at startup. The default `auth: "none"`
93
+ `AWS_SECRET_ACCESS_KEY` at startup; when those are absent it falls
94
+ back to `localFsStorage()` for local runs. **In a detected deployment
95
+ (`NODE_ENV=production` or a known PaaS) it refuses to start and requires
96
+ a bucket** — local-fs is local-dev only (single-process, no
97
+ cross-process CAS or crash durability). The default `auth: "none"`
75
98
  posture needs no auth env vars; if you adopt Pattern B / C from
76
99
  "Production auth" below, also set `SHARED_SECRET` (Pattern B) or
77
100
  `JWKS_URL` + `JWT_ISSUER` + `JWT_AUDIENCE` (Pattern C). Optional:
78
- `R2_ACCOUNT_ID` (switches the storage factory from `s3Storage` to
79
- `r2Storage`), `AWS_REGION`, `PORT`, `TENANT`, `WEB_ROOT`.
101
+ `AWS_REGION`, `PORT`.
80
102
 
81
103
  Maintenance (compaction + GC) is automatic and in-band: it runs
82
104
  inline on the rare write that crosses a maintenance trigger — no env
@@ -88,7 +110,7 @@ from `@gusto/baerly-storage`.
88
110
 
89
111
  After `pnpm build`, `http://localhost:8080/` serves the built SPA
90
112
  out of `dist/client/` and `http://localhost:8080/v1/*` is the
91
- baerly HTTP surface — single origin, no CORS.
113
+ baerly-storage HTTP surface — single origin, no CORS.
92
114
 
93
115
  `pnpm typecheck` runs `tsc -b --noEmit` across both project
94
116
  references.
@@ -98,7 +120,12 @@ references.
98
120
  This scaffold runs anywhere `node server.js` runs. The `package.json`
99
121
  exposes `build` (Vite SPA + TS check) and `start`
100
122
  (`node --experimental-strip-types src/server/index.ts`); arrange your
101
- host to run `pnpm install && pnpm build`, then `pnpm start`.
123
+ host to run `pnpm install && pnpm build`, then `pnpm start` with the
124
+ storage/auth env vars exported or configured in the process manager.
125
+ A deployment must set a durable bucket (`BUCKET` + `AWS_*`, or
126
+ `R2_ACCOUNT_ID` + creds); the server fails loud rather than running on
127
+ local-fs, which is local-dev only. Self-hosting without a cloud bucket,
128
+ run MinIO on the box or use SQLite + Litestream.
102
129
 
103
130
  Concrete shapes:
104
131
 
@@ -107,10 +134,12 @@ Concrete shapes:
107
134
  repo, set env vars from `.env.example` in the dashboard, deploy.
108
135
  The platform's buildpack detects Node and runs the root scripts.
109
136
  - **VM / bare-metal**: clone, install Node 24+, copy `.env.example`
110
- to `.env`, run `pnpm install && pnpm build && pnpm start` under
111
- your process manager of choice (systemd, pm2, etc.).
137
+ to `.env` as a template, then export those values or configure them
138
+ in your process manager (Node does not load `.env` automatically).
139
+ Run `pnpm install && pnpm build && pnpm start` under systemd, pm2,
140
+ or your process manager of choice.
112
141
  - **Container** (Docker, k8s, ECS, Fly Machines with a Dockerfile):
113
- scaffold with `pnpm create @gusto/baerly-storage@latest --target=node --with=docker` to add
142
+ scaffold with `pnpm create @gusto/baerly-storage@latest my-app --target=node --with=docker` to add
114
143
  a production Dockerfile, `.dockerignore`, and `healthcheck.js`
115
144
  alongside this shape, then `docker build .`.
116
145
 
@@ -151,16 +180,16 @@ follow `AGENTS.md` → "Going to production":
151
180
 
152
181
  ## When to graduate
153
182
 
154
- baerly is designed for the small-to-medium operating point. Past these
155
- thresholds, S3 list-prefix latency and per-class operation pricing
156
- start to dominate, and you're better off on a real database:
183
+ baerly-storage is designed for the small-to-medium operating point.
184
+ Past these thresholds, S3 list-prefix latency and per-class operation
185
+ pricing starts to dominate, and you've outgrown the workload envelope — move to a database service:
157
186
 
158
- - **~30 writes / minute / collection**
159
- - **~10 GB / tenant**
160
- - **~100 collections / tenant**
187
+ - **~30 writes / minute / collection** — per-collection throughput estimate (CAS-livelock model)
188
+ - **>10 GB / tenant** — R2 free-tier storage cost line (a billing signal, not a protocol ceiling)
189
+ - **~100 collections / tenant** — soft fan-out guideline (linear cost, bench-grounded; nothing enforces it)
161
190
 
162
- When you cross the soft ceiling, graduation is mechanical:
163
- `baerly export --target=postgres` walks your log entries (already Debezium-style CDC change events) into a real DB. If your
191
+ When you cross these signals, graduation is mechanical:
192
+ `baerly export --target=postgres` walks your log entries (already Debezium-style CDC change events) into a database service. If your
164
193
  deploy target is Cloudflare Workers and you'll accept Cloudflare
165
194
  lock-in, [D1](https://developers.cloudflare.com/d1/) is cheaper
166
195
  per-write at M-size and is a natural next step. If you're on
@@ -168,7 +197,7 @@ AWS, on-prem, or want your data portable, managed Postgres is
168
197
  the typical destination. Either way — graduation is a Baerly win,
169
198
  not a churn event.
170
199
 
171
- **Export to a real database** (swap `--target=` for `sqlite`,
200
+ **Export to a database service** (swap `--target=` for `sqlite`,
172
201
  `postgres`, or `d1`):
173
202
 
174
203
  ```sh
@@ -13,20 +13,20 @@
13
13
  },
14
14
  "dependencies": {
15
15
  "@gusto/baerly-storage": "workspace:*",
16
- "aws4fetch": "^1.0.20",
17
- "react": "^19.0.0",
18
- "react-dom": "^19.0.0",
16
+ "aws4fetch": "1.0.20",
17
+ "react": "^19.2.7",
18
+ "react-dom": "^19.2.7",
19
19
  "zod": "^4.4.3"
20
20
  },
21
21
  "devDependencies": {
22
- "@types/node": "^25.9.2",
22
+ "@types/node": "^26.0.1",
23
23
  "@types/react": "^19.2.17",
24
- "@types/react-dom": "^19.0.0",
25
- "@vitejs/plugin-react": "^6.0.2",
26
- "happy-dom": "^20.10.2",
24
+ "@types/react-dom": "^19.2.3",
25
+ "@vitejs/plugin-react": "^6.0.3",
26
+ "happy-dom": "^20.10.6",
27
27
  "typescript": "^6.0.3",
28
- "vite": "^8.0.16",
29
- "vitest": "^4.1.8"
28
+ "vite": "^8.1.2",
29
+ "vitest": "^4.1.9"
30
30
  },
31
31
  "packageManager": "pnpm@11.1.2"
32
32
  }
@@ -7,39 +7,28 @@
7
7
  * every write. See AGENTS.md "Going to production" for the recipe
8
8
  * to flip `auth` or wire a custom verifier.
9
9
  *
10
- * Storage: AWS S3 by default; set `R2_ACCOUNT_ID` to switch to
11
- * Cloudflare R2 via the S3-compat endpoint.
10
+ * Storage: zero-config `LocalFsStorage` rooted at ./.baerly-data for
11
+ * local development — no credentials. Set `BUCKET` (+ AWS creds) for AWS
12
+ * S3, or `R2_ACCOUNT_ID` (+ creds) for Cloudflare R2. In a detected
13
+ * deployment (NODE_ENV=production or a known PaaS) the server REFUSES to
14
+ * start without a bucket — local-fs is a local-dev convenience only
15
+ * (single-process, no cross-process CAS, no crash durability), never a
16
+ * production store — so a missing/typo'd bucket fails loud instead of
17
+ * silently losing data.
12
18
  */
13
- import { baerlyNode, r2Storage, s3Storage } from "@gusto/baerly-storage/node";
14
- import type { Storage } from "@gusto/baerly-storage";
19
+ import { baerlyNode } from "@gusto/baerly-storage/node";
15
20
  import config from "../../baerly.config.ts";
21
+ import { resolveStorage } from "./resolve-storage.ts";
16
22
 
17
- const reqEnv = (name: string): string => {
18
- const v = process.env[name];
19
- if (v === undefined || v === "") {
20
- throw new Error(`Missing required env var: ${name}`);
21
- }
22
- return v;
23
- };
23
+ // Pick the storage backend from the environment (R2 / S3 / local-fs),
24
+ // failing loud if a deployment has no bucket. The policy lives in
25
+ // `./resolve-storage.ts` — edit it there to change how your app maps
26
+ // env vars to storage.
27
+ const { storage, label: storageLabel } = resolveStorage();
24
28
 
25
- const storage: Storage =
26
- process.env["R2_ACCOUNT_ID"] !== undefined
27
- ? r2Storage({
28
- accountId: reqEnv("R2_ACCOUNT_ID"),
29
- bucket: reqEnv("BUCKET"),
30
- credentials: {
31
- accessKeyId: reqEnv("AWS_ACCESS_KEY_ID"),
32
- secretAccessKey: reqEnv("AWS_SECRET_ACCESS_KEY"),
33
- },
34
- })
35
- : s3Storage({
36
- region: process.env["AWS_REGION"] ?? "us-east-1",
37
- bucket: reqEnv("BUCKET"),
38
- credentials: {
39
- accessKeyId: reqEnv("AWS_ACCESS_KEY_ID"),
40
- secretAccessKey: reqEnv("AWS_SECRET_ACCESS_KEY"),
41
- },
42
- });
29
+ // Announce the effective backend so the chosen store (and any surprise
30
+ // local-fs fallback) is visible in the deploy logs, not a surprise.
31
+ console.log(`[baerly] storage=${storageLabel}`);
43
32
 
44
33
  const PORT = Number(process.env["PORT"] ?? 8080);
45
34
 
@@ -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 react from "@vitejs/plugin-react";
4
3
  import { baerlyDev } from "@gusto/baerly-storage/dev/vite";
@@ -11,7 +10,6 @@ export default defineConfig({
11
10
  react(),
12
11
  baerlyDev({
13
12
  config,
14
- dataDir: resolve(import.meta.dirname, ".baerly-data"),
15
13
  }),
16
14
  ],
17
15
  });
package/package.json CHANGED
@@ -1,7 +1,18 @@
1
1
  {
2
2
  "name": "@gusto/create-baerly-storage",
3
- "version": "0.3.0",
4
- "description": "Scaffold a new baerly-storage app. Run via `pnpm create @gusto/baerly-storage@latest -- my-app --target=cloudflare`.",
3
+ "version": "0.4.1",
4
+ "description": "Create an app with a document database on S3 or Cloudflare R2 — TypeScript scaffold for Workers and Node",
5
+ "keywords": [
6
+ "boilerplate",
7
+ "cloudflare-workers",
8
+ "document-database",
9
+ "r2",
10
+ "s3",
11
+ "scaffold",
12
+ "serverless",
13
+ "starter",
14
+ "typescript"
15
+ ],
5
16
  "homepage": "https://github.com/Gusto/baerly-storage#readme",
6
17
  "bugs": {
7
18
  "url": "https://github.com/Gusto/baerly-storage/issues"
@@ -24,7 +35,7 @@
24
35
  "access": "public"
25
36
  },
26
37
  "dependencies": {
27
- "@clack/prompts": "^1.5.1",
38
+ "@clack/prompts": "^1.6.0",
28
39
  "citty": "^0.2.2",
29
40
  "picocolors": "^1.1.1"
30
41
  },