@gusto/create-baerly-storage 0.2.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.
- package/LICENSE +202 -0
- package/dist/index.js +54 -28
- package/dist/index.js.map +1 -1
- package/dist/templates/addons/docker/Dockerfile +8 -2
- package/dist/templates/minimal-cloudflare/AGENTS.md +140 -101
- package/dist/templates/minimal-cloudflare/README.md +43 -33
- package/dist/templates/minimal-cloudflare/package.json +7 -7
- package/dist/templates/minimal-cloudflare/wrangler.jsonc +1 -1
- 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 +135 -107
- package/dist/templates/minimal-node/README.md +77 -44
- 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 +77 -52
- package/dist/templates/react-cloudflare/README.md +25 -16
- package/dist/templates/react-cloudflare/index.html +1 -1
- package/dist/templates/react-cloudflare/package.json +12 -12
- package/dist/templates/react-cloudflare/wrangler.jsonc +1 -1
- package/dist/templates/react-node/.env.example +12 -5
- package/dist/templates/react-node/AGENTS.md +117 -81
- package/dist/templates/react-node/README.md +67 -37
- package/dist/templates/react-node/package.json +10 -10
- 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 +16 -11
|
@@ -1,13 +1,23 @@
|
|
|
1
1
|
# minimal-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
|
-
|
|
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.
|
|
11
21
|
|
|
12
22
|
To ship a production Dockerfile alongside, scaffold with
|
|
13
23
|
`--with=docker` — the add-on writes a multi-stage distroless Dockerfile,
|
|
@@ -23,13 +33,13 @@ minimal-node/
|
|
|
23
33
|
├── tsconfig.server.json # Node server TS project (src/server)
|
|
24
34
|
├── vite.config.ts # Vite SPA build → dist/client/
|
|
25
35
|
├── index.html # SPA shell — Vite's entry point
|
|
26
|
-
├── .env.example # storage
|
|
36
|
+
├── .env.example # storage selection (local-fs default) + PORT
|
|
27
37
|
├── baerly.config.ts # app, tenant, target, domain
|
|
28
38
|
├── AGENTS.md # deeper guide: predicates, schemas,
|
|
29
39
|
│ # auth recipes, graduation
|
|
30
40
|
├── src/
|
|
31
41
|
│ ├── server/
|
|
32
|
-
│ │ └── index.ts # baerlyNode({
|
|
42
|
+
│ │ └── index.ts # baerlyNode({ config, storage, webRoot }).listen(PORT)
|
|
33
43
|
│ └── web/
|
|
34
44
|
│ └── main.ts # SPA client entry — bundled into dist/client/
|
|
35
45
|
└── README.md
|
|
@@ -45,27 +55,43 @@ pnpm dev
|
|
|
45
55
|
`pnpm dev` runs `vite`. `baerlyDev()` from `@gusto/baerly-storage/dev/vite`
|
|
46
56
|
mounts the Node HTTP listener as Connect middleware on the same Vite
|
|
47
57
|
process that serves the SPA, so `GET /` hits the SPA on
|
|
48
|
-
`http://localhost:5173/` and anything baerly handles (e.g.
|
|
58
|
+
`http://localhost:5173/` and anything baerly-storage handles (e.g.
|
|
49
59
|
`GET /v1/healthz`) is served on the same origin — one process, one
|
|
50
60
|
port, SPA + HMR + `/v1/*` in one command. Storage is `LocalFsStorage`
|
|
51
61
|
rooted at `.baerly-data/`, so first-touch needs no S3 creds, no JWKS,
|
|
52
62
|
and no second process.
|
|
53
63
|
|
|
54
|
-
For production-shaped local runs (
|
|
55
|
-
|
|
64
|
+
For production-shaped local runs (the built SPA served from
|
|
65
|
+
`dist/client/` alongside `/v1/*`):
|
|
56
66
|
|
|
57
67
|
```sh
|
|
58
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
|
|
59
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
|
|
60
82
|
```
|
|
61
83
|
|
|
62
84
|
The server reads `BUCKET`, `AWS_ACCESS_KEY_ID`,
|
|
63
|
-
`AWS_SECRET_ACCESS_KEY` at startup
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
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.
|
|
69
95
|
|
|
70
96
|
Maintenance (compaction + GC) is automatic and in-band: it runs
|
|
71
97
|
inline on the rare write that crosses a maintenance trigger — no env
|
|
@@ -75,9 +101,9 @@ snapshot ceiling and `BAERLY_MAINTENANCE_DISABLE=1` is a kill switch.
|
|
|
75
101
|
For an explicit out-of-band sweep, call `runScheduledMaintenance`
|
|
76
102
|
from `@gusto/baerly-storage`.
|
|
77
103
|
|
|
78
|
-
After `pnpm build`, `
|
|
79
|
-
|
|
80
|
-
|
|
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.
|
|
81
107
|
|
|
82
108
|
`pnpm typecheck` runs `tsc -b --noEmit` across both project
|
|
83
109
|
references.
|
|
@@ -87,7 +113,12 @@ references.
|
|
|
87
113
|
This scaffold runs anywhere `node server.js` runs. The `package.json`
|
|
88
114
|
exposes `build` (Vite SPA + TS check) and `start`
|
|
89
115
|
(`node --experimental-strip-types src/server/index.ts`); arrange your
|
|
90
|
-
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.
|
|
91
122
|
|
|
92
123
|
Concrete shapes:
|
|
93
124
|
|
|
@@ -96,10 +127,12 @@ Concrete shapes:
|
|
|
96
127
|
repo, set env vars from `.env.example` in the dashboard, deploy.
|
|
97
128
|
The platform's buildpack detects Node and runs the root scripts.
|
|
98
129
|
- **VM / bare-metal**: clone, install Node 24+, copy `.env.example`
|
|
99
|
-
to `.env
|
|
100
|
-
your process manager
|
|
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.
|
|
101
134
|
- **Container** (Docker, k8s, ECS, Fly Machines with a Dockerfile):
|
|
102
|
-
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
|
|
103
136
|
a production Dockerfile, `.dockerignore`, and `healthcheck.js`
|
|
104
137
|
alongside this shape, then `docker build .`.
|
|
105
138
|
|
|
@@ -108,34 +141,34 @@ Verify: `curl https://<your-service>/v1/healthz`.
|
|
|
108
141
|
## Next steps
|
|
109
142
|
|
|
110
143
|
1. **Read `AGENTS.md`** for the agent-facing guide — predicates,
|
|
111
|
-
indexes, schemas, auth recipes (JWKS setup),
|
|
112
|
-
maintenance
|
|
144
|
+
indexes, schemas, auth recipes (JWKS setup), write-triggered
|
|
145
|
+
maintenance, and the graduation criteria. (Claude Code
|
|
113
146
|
users: `@gusto/create-baerly-storage` mirrors `AGENTS.md` to `CLAUDE.md` at
|
|
114
147
|
scaffold time.)
|
|
115
148
|
2. **Declare your first collection schema** in `baerly.config.ts`
|
|
116
|
-
via `defineConfig({ collections: { ... } })
|
|
117
|
-
`Db.create({
|
|
118
|
-
bad inserts return
|
|
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.
|
|
119
152
|
3. **Set up production auth** — follow `AGENTS.md` → "Going to
|
|
120
153
|
production". Pattern B flips `auth: "shared-secret"` and reads
|
|
121
154
|
`SHARED_SECRET` from `process.env`; Pattern C wires `bearerJwt`
|
|
122
155
|
against your OIDC IdP via an env-aware factory `verifier:`
|
|
123
156
|
override (`JWKS_URL` + `JWT_ISSUER` + `JWT_AUDIENCE`).
|
|
124
|
-
`baerly doctor --
|
|
157
|
+
Verify the bucket with `baerly doctor --bucket=<s3-uri>` and the
|
|
158
|
+
deployed service with `curl https://<your-service>/v1/healthz`.
|
|
125
159
|
|
|
126
160
|
## When to graduate
|
|
127
161
|
|
|
128
|
-
baerly is designed for the small-to-medium operating point.
|
|
129
|
-
thresholds, S3 list-prefix latency and per-class operation
|
|
130
|
-
|
|
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:
|
|
131
165
|
|
|
132
|
-
- **~30 writes / minute / collection**
|
|
133
|
-
-
|
|
134
|
-
- **~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)
|
|
135
169
|
|
|
136
|
-
When you cross
|
|
137
|
-
`baerly export --target=postgres` walks your log entries (already
|
|
138
|
-
Postgres-logical-replication-shaped) 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
|
|
139
172
|
deploy target is Cloudflare Workers and you'll accept Cloudflare
|
|
140
173
|
lock-in, [D1](https://developers.cloudflare.com/d1/) is cheaper
|
|
141
174
|
per-write at M-size and is a natural next step. If you're on
|
|
@@ -143,12 +176,12 @@ AWS, on-prem, or want your data portable, managed Postgres is
|
|
|
143
176
|
the typical destination. Either way — graduation is a Baerly win,
|
|
144
177
|
not a churn event.
|
|
145
178
|
|
|
146
|
-
**Export to a
|
|
179
|
+
**Export to a database service** (swap `--target=` for `sqlite`,
|
|
147
180
|
`postgres`, or `d1`):
|
|
148
181
|
|
|
149
182
|
```sh
|
|
150
183
|
baerly export --target=postgres \
|
|
151
|
-
--bucket=minimal-node --app=minimal-node --tenant=<your-tenant> \
|
|
184
|
+
--bucket=s3://minimal-node --app=minimal-node --tenant=<your-tenant> \
|
|
152
185
|
--collection=<collection-name> --output=./out.sql
|
|
153
186
|
```
|
|
154
187
|
|
|
@@ -164,7 +197,7 @@ with zero env vars; every request resolves to `config.tenant`.
|
|
|
164
197
|
Before deploy, follow `AGENTS.md` → "Going to production":
|
|
165
198
|
|
|
166
199
|
- **Pattern B — `auth: "shared-secret"`.** Single-tenant
|
|
167
|
-
server-to-server callers (CI
|
|
200
|
+
server-to-server callers (CI and internal services). Flip
|
|
168
201
|
`auth` in `baerly.config.ts` and put `SHARED_SECRET` in
|
|
169
202
|
`process.env` (your PaaS / secret manager).
|
|
170
203
|
- **Pattern C — JWKS-backed JWT (recommended for multi-tenant).**
|
|
@@ -13,14 +13,14 @@
|
|
|
13
13
|
},
|
|
14
14
|
"dependencies": {
|
|
15
15
|
"@gusto/baerly-storage": "workspace:*",
|
|
16
|
-
"aws4fetch": "
|
|
16
|
+
"aws4fetch": "1.0.20"
|
|
17
17
|
},
|
|
18
18
|
"devDependencies": {
|
|
19
|
-
"@types/node": "^
|
|
20
|
-
"happy-dom": "^20.
|
|
19
|
+
"@types/node": "^26.0.1",
|
|
20
|
+
"happy-dom": "^20.10.6",
|
|
21
21
|
"typescript": "^6.0.3",
|
|
22
|
-
"vite": "^8.
|
|
23
|
-
"vitest": "^4.1.
|
|
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:
|
|
9
|
-
*
|
|
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
|
|
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
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
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
|
-
|
|
24
|
-
|
|
25
|
-
|
|
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
|
-
|
|
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
|
|
43
|
-
The Worker-side server lives in `src/server/`;
|
|
44
|
-
in `src/web/`. Configuration lives in
|
|
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:
|
|
59
|
-
|
|
60
|
-
|
|
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
|
|
68
|
-
itself uses TypeScript 7 via
|
|
69
|
-
|
|
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
|
|
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 |
|
|
@@ -104,7 +106,7 @@ http://localhost:5173/<path>`) before declaring the task complete.
|
|
|
104
106
|
| Path | What it is |
|
|
105
107
|
| -------------------------- | ---------------------------------------------------------------------------------------------------------------- |
|
|
106
108
|
| `src/server/index.ts` | Server entry — `/v1/*` routing + SPA fallback via `env.ASSETS` |
|
|
107
|
-
| `wrangler.jsonc` | Cloudflare Worker manifest — name, R2 binding, Assets binding, vars
|
|
109
|
+
| `wrangler.jsonc` | Cloudflare Worker manifest — name, R2 binding, Assets binding, vars |
|
|
108
110
|
| `src/web/` | React+Vite frontend. Served by the Worker via Workers Assets in production. |
|
|
109
111
|
| `index.html` | SPA shell — Vite's entry point at the project root; references `/src/web/main.tsx`. |
|
|
110
112
|
| `vite.config.ts` | Vite + `@vitejs/plugin-react` + `@cloudflare/vite-plugin` — runs the Worker inside `workerd` in dev |
|
|
@@ -125,22 +127,34 @@ http://localhost:5173/<path>`) before declaring the task complete.
|
|
|
125
127
|
|
|
126
128
|
## When editing X, read Y
|
|
127
129
|
|
|
128
|
-
- **Typed collections** —
|
|
130
|
+
- **Typed collections** — two ways to get a typed row, in DX order.
|
|
131
|
+
The generic on `client.collection<N>(name)` is the collection
|
|
132
|
+
**name** (constrained to `CollectionNames<typeof config>`), not the
|
|
133
|
+
row type — so don't pass a row type to it.
|
|
129
134
|
1. **Bind the config.** This template's `src/web/client.ts`
|
|
130
135
|
already passes `config` to `createBaerlyClient({ baseUrl,
|
|
131
136
|
config })`, so `client.collection("notes")` returns
|
|
132
137
|
`ClientCollection<Row>` with `Row` derived from the
|
|
133
138
|
`NoteSchema` declared in `baerly.config.ts`. No generic
|
|
134
|
-
needed.
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
2. **
|
|
138
|
-
|
|
139
|
-
|
|
139
|
+
needed. When you need to name that row type elsewhere, use
|
|
140
|
+
`RowOf<typeof config, "notes">` (re-exported from
|
|
141
|
+
`@gusto/baerly-storage`) — not a generic on `.collection()`.
|
|
142
|
+
2. **Cast the handle (undeclared collection).** This template's
|
|
143
|
+
`client` is bound to `config`, so its names narrow to the
|
|
144
|
+
declared collections. To reach a collection that isn't in
|
|
145
|
+
`config`, build an unbound client
|
|
146
|
+
(`createBaerlyClient({ baseUrl })` with no `config`) — its names
|
|
147
|
+
widen to `string` and its row defaults to `DocumentData`. Cast at
|
|
148
|
+
the construction site for a narrower shape that still satisfies
|
|
149
|
+
the kernel's `DocumentData` constraint
|
|
150
|
+
(`{ [k: string]: DocumentValue }`):
|
|
140
151
|
```ts
|
|
152
|
+
import { createBaerlyClient, type ClientCollection } from "@gusto/baerly-storage/client";
|
|
141
153
|
import type { DocumentData } from "@gusto/baerly-storage";
|
|
142
154
|
interface Bookmark extends DocumentData { _id: string; url: string }
|
|
143
|
-
|
|
155
|
+
const raw = createBaerlyClient({ baseUrl: "" });
|
|
156
|
+
const bookmarks = raw.collection("bookmarks") as ClientCollection<Bookmark>;
|
|
157
|
+
await bookmarks.all();
|
|
144
158
|
```
|
|
145
159
|
A plain `interface Bookmark { _id: string; url: string }`
|
|
146
160
|
(no index signature) will fail with TS2344 — the constraint
|
|
@@ -266,7 +280,7 @@ http://localhost:5173/<path>`) before declaring the task complete.
|
|
|
266
280
|
|
|
267
281
|
On a validation failure the server throws
|
|
268
282
|
`BaerlyError{ code: "SchemaError", issues: [{ path, message }] }`;
|
|
269
|
-
HTTP clients see a
|
|
283
|
+
HTTP clients see a 400 with the same envelope. Validation runs
|
|
270
284
|
on the post-image so `update` and `replace` see the full doc, not
|
|
271
285
|
just the patch.
|
|
272
286
|
|
|
@@ -287,7 +301,7 @@ http://localhost:5173/<path>`) before declaring the task complete.
|
|
|
287
301
|
(without the `doc` wrapper) returns
|
|
288
302
|
`400 SchemaError "Request body must be { doc: object }"` — the
|
|
289
303
|
wording is locked by `assertJsonBodyField` in the kernel. Canonical
|
|
290
|
-
reference: the
|
|
304
|
+
reference: the JSDoc on `createRouter` in
|
|
291
305
|
`baerly-storage`.
|
|
292
306
|
|
|
293
307
|
- **Auth** — your scaffold ships `auth: "none"` in `baerly.config.ts`:
|
|
@@ -353,6 +367,7 @@ export default baerlyWorker<AppEnv>((env) => ({
|
|
|
353
367
|
verifier: cloudflareAccess({
|
|
354
368
|
teamDomain: env.CF_ACCESS_TEAM_DOMAIN,
|
|
355
369
|
audienceTag: env.CF_ACCESS_AUDIENCE_TAG,
|
|
370
|
+
tenantPrefix: config.tenant,
|
|
356
371
|
}),
|
|
357
372
|
}),
|
|
358
373
|
}));
|
|
@@ -362,12 +377,14 @@ Set both `CF_ACCESS_TEAM_DOMAIN` and `CF_ACCESS_AUDIENCE_TAG` in
|
|
|
362
377
|
`wrangler.jsonc:vars` for prod (they're public identifiers, not
|
|
363
378
|
secrets). Dev `wrangler dev` sees them as `undefined`, the spread
|
|
364
379
|
short-circuits, and `config.auth: "none"` runs. Prod sees them set
|
|
365
|
-
and `cloudflareAccess` engages.
|
|
380
|
+
and `cloudflareAccess` engages. Every verified token is pinned to
|
|
381
|
+
`config.tenant`; pass `tenantClaim` instead only when your Access JWT
|
|
382
|
+
actually carries a tenant claim.
|
|
366
383
|
|
|
367
384
|
<!-- pattern-a:end -->
|
|
368
385
|
<!-- pattern-b:start -->
|
|
369
386
|
**Pattern B — `auth: "shared-secret"`.** Single-tenant
|
|
370
|
-
server-to-server callers (CI
|
|
387
|
+
server-to-server callers (CI and internal services). No factory
|
|
371
388
|
code changes; only `baerly.config.ts` flips:
|
|
372
389
|
|
|
373
390
|
```ts
|
|
@@ -411,10 +428,11 @@ from the runtime env.
|
|
|
411
428
|
|
|
412
429
|
<!-- pattern-b:end -->
|
|
413
430
|
- **Extending the Worker with a custom route** — `baerlyWorker(...)`
|
|
414
|
-
owns `/v1
|
|
431
|
+
owns `/v1/*`, including `/v1/healthz`. For server-side endpoints the SPA
|
|
415
432
|
client can't run on its own (the canonical case: an endpoint that
|
|
416
|
-
|
|
417
|
-
reads + by-id mutations only), wrap the
|
|
433
|
+
fans a write across several documents server-side, since
|
|
434
|
+
`createBaerlyClient` is reads + by-id mutations only), wrap the
|
|
435
|
+
worker `fetch`:
|
|
418
436
|
|
|
419
437
|
```ts
|
|
420
438
|
// src/server/index.ts
|
|
@@ -447,10 +465,10 @@ from the runtime env.
|
|
|
447
465
|
tenant: config.tenant,
|
|
448
466
|
config,
|
|
449
467
|
});
|
|
450
|
-
// …db.
|
|
468
|
+
// …db.collection(...).insert(doc), db.collection(...).get(id), etc.
|
|
451
469
|
return new Response(null, { status: 204 });
|
|
452
470
|
}
|
|
453
|
-
// Fall through to the baerly cascade for /v1
|
|
471
|
+
// Fall through to the baerly cascade for /v1/*, including /v1/healthz.
|
|
454
472
|
return baerly.fetch!(req, env, ctx);
|
|
455
473
|
},
|
|
456
474
|
} satisfies ExportedHandler<BaerlyEnv>;
|
|
@@ -498,7 +516,8 @@ from the runtime env.
|
|
|
498
516
|
into the predicate so the index planner can prune
|
|
499
517
|
(`db.collection("notes").where({ ... }).all()`), or maintain a
|
|
500
518
|
side-projection (D1/KV/search index) populated incrementally from
|
|
501
|
-
the `/v1/since
|
|
519
|
+
the `/v1/since?collection=<name>&cursor=<opaque>` log feed or from
|
|
520
|
+
a write hook — never re-scan per
|
|
502
521
|
request.
|
|
503
522
|
|
|
504
523
|
## Maintenance
|
|
@@ -517,7 +536,7 @@ maintenance, so the published idle-reader cost bound holds.
|
|
|
517
536
|
A bucket maintains itself as long as it takes writes. A bucket served read-only does
|
|
518
537
|
not auto-compact and pays a small, bounded replay — fine at small scale, a signal to
|
|
519
538
|
graduate once a collection is large. See docs/about/graduation.md for the per-tier
|
|
520
|
-
envelope and the BAERLY_MAINTENANCE_
|
|
539
|
+
envelope and the `BAERLY_MAINTENANCE_*` operator env vars (you almost never need them).
|
|
521
540
|
|
|
522
541
|
Operator opt-in: call runScheduledMaintenance from @gusto/baerly-storage/maintenance on
|
|
523
542
|
your own schedule. Not required for steady-state operation.
|
|
@@ -525,28 +544,32 @@ your own schedule. Not required for steady-state operation.
|
|
|
525
544
|
|
|
526
545
|
## When to graduate
|
|
527
546
|
|
|
528
|
-
baerly is designed for the small-to-medium operating point.
|
|
529
|
-
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:
|
|
530
549
|
|
|
531
|
-
- **~30 writes / minute / collection**
|
|
532
|
-
-
|
|
533
|
-
- **~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)
|
|
534
553
|
|
|
535
|
-
|
|
536
|
-
op pricing start to dominate;
|
|
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.
|
|
537
557
|
Pick your graduation target:
|
|
538
558
|
- **Cloudflare Workers + lock-in OK:** [D1](https://developers.cloudflare.com/d1/) — cheaper per-write at M-size.
|
|
539
559
|
- **Off-Workers or portability matters:** managed Postgres.
|
|
540
560
|
- **Single-instance Node:** SQLite via Litestream.
|
|
541
561
|
|
|
542
562
|
Either way, the export below is mechanical because log entries are
|
|
543
|
-
|
|
544
|
-
not a churn event.
|
|
563
|
+
Debezium-style CDC change events — graduation is a baerly-storage
|
|
564
|
+
win, not a churn event.
|
|
545
565
|
|
|
546
|
-
**Estimate your current rate:**
|
|
547
|
-
|
|
548
|
-
|
|
549
|
-
|
|
566
|
+
**Estimate your current rate:** for Node/self-hosted buckets,
|
|
567
|
+
`baerly admin usage --target=node --bucket=<bucket-uri> --app=<app>
|
|
568
|
+
--tenant=<tenant>` lists recent log entries per collection and computes
|
|
569
|
+
writes/min. On Cloudflare, use canonical logs for trend history and
|
|
570
|
+
`baerly cost --bucket=<bucket-uri> --collection=<collection>` for the
|
|
571
|
+
current operation-cost projection until the usage scanner is wired to
|
|
572
|
+
R2 bindings.
|
|
550
573
|
|
|
551
574
|
**Export when ready:** `baerly export --target=sqlite|postgres|d1
|
|
552
575
|
--bucket=<...> --app=<...> --tenant=<...> --collection=<...>` writes a
|
|
@@ -629,7 +652,8 @@ const result = useQuery(
|
|
|
629
652
|
```
|
|
630
653
|
|
|
631
654
|
`useQuery` re-runs the callback when `deps` changes OR when the
|
|
632
|
-
`/v1/since
|
|
655
|
+
`/v1/since?collection=<name>&cursor=<opaque>` long-poll batches a
|
|
656
|
+
non-empty change for any subscribed
|
|
633
657
|
collection. Idle long-poll cycles (empty batches) drop at the
|
|
634
658
|
`subscription-pool` layer, so a steady-state collection costs zero list
|
|
635
659
|
reads. Add a `<select>` bound to `setFilter` and the list narrows live.
|
|
@@ -697,14 +721,15 @@ JSON-merge-patch (RFC 7386) semantics apply on `update()`:
|
|
|
697
721
|
omitting `tags` from an update preserves the existing value;
|
|
698
722
|
passing `tags: null` deletes the field; passing `tags: []` sets
|
|
699
723
|
it to an empty array. Note that `null` is the deletion sentinel,
|
|
700
|
-
not a storable value — `DocumentValue` doesn't include `null`,
|
|
701
|
-
|
|
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`.
|
|
702
727
|
That's why this recipe uses `.optional()` and not `.nullable()`.
|
|
703
728
|
|
|
704
729
|
## Pointers
|
|
705
730
|
|
|
706
731
|
- `baerly.config.ts` — app config + `NoteSchema` + inferred `Note` type.
|
|
707
732
|
- `src/server/index.ts` — Worker entry.
|
|
708
|
-
- `wrangler.jsonc` — Cloudflare Worker manifest (R2 binding, `assets:`, vars
|
|
733
|
+
- `wrangler.jsonc` — Cloudflare Worker manifest (R2 binding, `assets:`, vars).
|
|
709
734
|
- `vite.config.ts` — Vite + `@vitejs/plugin-react` + `@cloudflare/vite-plugin`.
|
|
710
735
|
- `package.json` — root scripts + dependencies.
|