@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.
- package/dist/index.js +54 -28
- package/dist/index.js.map +1 -1
- package/dist/templates/minimal-cloudflare/AGENTS.md +28 -25
- package/dist/templates/minimal-cloudflare/README.md +24 -21
- package/dist/templates/minimal-cloudflare/package.json +7 -7
- package/dist/templates/minimal-node/.baerly/scaffold.json +1 -1
- package/dist/templates/minimal-node/.env.example +12 -5
- package/dist/templates/minimal-node/AGENTS.md +61 -52
- package/dist/templates/minimal-node/README.md +71 -40
- package/dist/templates/minimal-node/package.json +5 -5
- package/dist/templates/minimal-node/src/server/index.ts +22 -30
- package/dist/templates/minimal-node/src/server/resolve-storage.ts +18 -0
- package/dist/templates/minimal-node/vite.config.ts +0 -2
- package/dist/templates/react-cloudflare/AGENTS.md +31 -27
- package/dist/templates/react-cloudflare/README.md +19 -13
- package/dist/templates/react-cloudflare/index.html +1 -1
- package/dist/templates/react-cloudflare/package.json +11 -11
- package/dist/templates/react-node/.env.example +12 -5
- package/dist/templates/react-node/AGENTS.md +73 -59
- package/dist/templates/react-node/README.md +62 -33
- package/dist/templates/react-node/package.json +9 -9
- package/dist/templates/react-node/src/server/index.ts +18 -29
- package/dist/templates/react-node/src/server/resolve-storage.ts +18 -0
- package/dist/templates/react-node/vite.config.ts +0 -2
- package/package.json +14 -3
|
@@ -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
|
|
43
|
-
Node target
|
|
44
|
-
Fly without Docker, Heroku, a VM, a
|
|
45
|
-
Node-side server lives in `src/server/`; the
|
|
46
|
-
`src/web/`. Configuration lives in
|
|
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:
|
|
69
|
-
|
|
70
|
-
|
|
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
|
|
78
|
-
itself uses TypeScript 7 via
|
|
79
|
-
|
|
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
|
|
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 —
|
|
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_*`,
|
|
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
|
|
262
|
-
|
|
263
|
-
scan with a metric bump —
|
|
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
|
|
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
|
|
390
|
+
apps or tenancy enforced outside baerly-storage.
|
|
388
391
|
|
|
389
392
|
<!-- pattern-c:end -->
|
|
390
|
-
- **Storage backend** — `src/server/index.ts`
|
|
391
|
-
`
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
`
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
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
|
|
409
|
+
- **Switching from static creds to EKS** — in
|
|
404
410
|
`src/server/index.ts`, swap `credentials: { accessKeyId,
|
|
405
|
-
secretAccessKey }` for `credentials:
|
|
406
|
-
|
|
407
|
-
`import { s3Storage,
|
|
408
|
-
|
|
409
|
-
`
|
|
410
|
-
|
|
411
|
-
`
|
|
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`.
|
|
421
|
-
|
|
422
|
-
`
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
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.
|
|
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
|
-
-
|
|
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
|
-
|
|
487
|
-
op pricing start to dominate;
|
|
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
|
|
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
|
-
|
|
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
|
|
4
|
-
any host that runs `node server.js` (Railway,
|
|
5
|
-
Docker, Heroku, a VM, a container scheduler, your
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
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
|
|
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 (
|
|
66
|
-
|
|
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
|
|
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
|
-
`
|
|
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
|
|
111
|
-
your process manager
|
|
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.
|
|
155
|
-
thresholds, S3 list-prefix latency and per-class operation
|
|
156
|
-
|
|
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
|
-
-
|
|
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
|
|
163
|
-
`baerly export --target=postgres` walks your log entries (already Debezium-style CDC change events) into a
|
|
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
|
|
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": "
|
|
17
|
-
"react": "^19.
|
|
18
|
-
"react-dom": "^19.
|
|
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": "^
|
|
22
|
+
"@types/node": "^26.0.1",
|
|
23
23
|
"@types/react": "^19.2.17",
|
|
24
|
-
"@types/react-dom": "^19.
|
|
25
|
-
"@vitejs/plugin-react": "^6.0.
|
|
26
|
-
"happy-dom": "^20.10.
|
|
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.
|
|
29
|
-
"vitest": "^4.1.
|
|
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:
|
|
11
|
-
*
|
|
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
|
|
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
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
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
|
-
|
|
26
|
-
|
|
27
|
-
|
|
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.
|
|
4
|
-
"description": "
|
|
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.
|
|
38
|
+
"@clack/prompts": "^1.6.0",
|
|
28
39
|
"citty": "^0.2.2",
|
|
29
40
|
"picocolors": "^1.1.1"
|
|
30
41
|
},
|