@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 minimal-cloudflare
|
|
3
3
|
audience: agent
|
|
4
|
-
summary: How to develop and deploy minimal-cloudflare, a baerly app.
|
|
5
|
-
tags: [agent-entry, baerly]
|
|
4
|
+
summary: How to develop and deploy minimal-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,30 +38,31 @@ 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
|
-
`minimal-cloudflare` is a baerly app scaffolded with
|
|
43
|
-
The Worker-side server lives in `src/server/`;
|
|
44
|
-
lives in `src/web/`. Configuration lives in
|
|
44
|
+
`minimal-cloudflare` is a baerly-storage app scaffolded with
|
|
45
|
+
`create-baerly-storage`. The Worker-side server lives in `src/server/`;
|
|
46
|
+
the optional 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
|
|
48
51
|
`wrangler.jsonc:assets` ships the built `dist/client/` bundle next to
|
|
49
52
|
the Worker on deploy. Same origin in dev and prod, one deploy.
|
|
50
53
|
|
|
51
|
-
Public API docs:
|
|
52
|
-
|
|
53
|
-
|
|
54
|
+
Public API docs: the JSDoc on `baerly-storage`'s `Db` and `Collection`
|
|
55
|
+
is the canonical reference; read it via your editor's TS LS, the
|
|
56
|
+
published types, or `node_modules/@gusto/baerly-storage/dist/API.md`.
|
|
54
57
|
|
|
55
58
|
## Toolchain
|
|
56
59
|
|
|
57
60
|
- **Package manager:** pnpm. The emitted repo pins
|
|
58
61
|
`packageManager: pnpm@11.1.2`.
|
|
59
62
|
- **Test runner:** vitest.
|
|
60
|
-
- **Type checker:** TypeScript
|
|
61
|
-
itself uses TypeScript 7 via
|
|
62
|
-
|
|
63
|
-
apps work with the wider ecosystem.)
|
|
63
|
+
- **Type checker:** TypeScript 6.x, as pinned in `package.json`.
|
|
64
|
+
(The baerly-storage monorepo itself uses TypeScript 7 via
|
|
65
|
+
`@typescript/native-preview`.)
|
|
64
66
|
- **`erasableSyntaxOnly`** is enabled in every `tsconfig*.json` so the
|
|
65
67
|
code stays compatible with type-stripping runtimes (Node's
|
|
66
68
|
`--experimental-strip-types`, esbuild's strip path). The flag bans
|
|
@@ -79,7 +81,7 @@ read it via your editor's TS LS or via the published types).
|
|
|
79
81
|
| `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 |
|
|
80
82
|
| `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 |
|
|
81
83
|
| `pnpm typecheck` | TS typecheck across the worker + web project references (`tsc -b --noEmit`) | seconds |
|
|
82
|
-
| `pnpm test` | `vitest run
|
|
84
|
+
| `pnpm test` | `vitest run` — standalone `vitest.config.ts` (Node env, ignores `vite.config.ts` so the Cloudflare plugin doesn't load). The template ships `src/notes.test.ts` by default. | seconds |
|
|
83
85
|
| `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 |
|
|
84
86
|
| `pnpm build` | `tsc -b && vite build` — emits `dist/client/` for the Workers Assets binding | seconds |
|
|
85
87
|
| `pnpm deploy` | `wrangler deploy` — ships Worker + assets in one shipment (auto-creates R2 on first run via `--x-provision`) | seconds |
|
|
@@ -304,7 +306,7 @@ http://localhost:5173/<path>`) before declaring the task complete.
|
|
|
304
306
|
(without the `doc` wrapper) returns
|
|
305
307
|
`400 SchemaError "Request body must be { doc: object }"` — the
|
|
306
308
|
wording is locked by `assertJsonBodyField` in the kernel. Canonical
|
|
307
|
-
reference: the
|
|
309
|
+
reference: the JSDoc on `createRouter` in
|
|
308
310
|
`baerly-storage`.
|
|
309
311
|
|
|
310
312
|
- **Auth** — your scaffold ships `auth: "none"` in `baerly.config.ts`:
|
|
@@ -538,15 +540,16 @@ your own schedule. Not required for steady-state operation.
|
|
|
538
540
|
|
|
539
541
|
## When to graduate
|
|
540
542
|
|
|
541
|
-
baerly is designed for the small-to-medium operating point.
|
|
542
|
-
model puts the soft ceiling at:
|
|
543
|
+
baerly-storage is designed for the small-to-medium operating point.
|
|
544
|
+
The cost model puts the soft ceiling at:
|
|
543
545
|
|
|
544
|
-
- **~30 writes / minute / collection**
|
|
545
|
-
-
|
|
546
|
-
- **~100 collections / tenant**
|
|
546
|
+
- **~30 writes / minute / collection** (throughput ceiling — model/estimate)
|
|
547
|
+
- **>10 GB / tenant stored** (R2 free-tier storage line — a cost signal, not a protocol ceiling)
|
|
548
|
+
- **~100 collections / tenant** (soft fan-out guideline — bench-grounded linear cost)
|
|
547
549
|
|
|
548
|
-
|
|
549
|
-
op pricing start to dominate;
|
|
550
|
+
At M-size (~30 writes/min) the projected cost is ~$18/mo on R2. Past
|
|
551
|
+
those, per-class op pricing and fan-out scan cost start to dominate;
|
|
552
|
+
you've outgrown the workload envelope — move to a database service (D1 / Postgres) suited to higher scale.
|
|
550
553
|
Pick your graduation target:
|
|
551
554
|
|
|
552
555
|
- **Cloudflare Workers + lock-in OK:** [D1](https://developers.cloudflare.com/d1/) — cheaper per-write at M-size.
|
|
@@ -554,8 +557,8 @@ Pick your graduation target:
|
|
|
554
557
|
- **Single-instance Node:** SQLite via Litestream.
|
|
555
558
|
|
|
556
559
|
Either way, the export below is mechanical because log entries are
|
|
557
|
-
Debezium-style CDC change events — graduation is a
|
|
558
|
-
not a churn event.
|
|
560
|
+
Debezium-style CDC change events — graduation is a baerly-storage
|
|
561
|
+
win, not a churn event.
|
|
559
562
|
|
|
560
563
|
**Estimate your current rate:** for Node/self-hosted buckets,
|
|
561
564
|
`baerly admin usage --target=node --bucket=<bucket-uri> --app=<app>
|
|
@@ -1,13 +1,16 @@
|
|
|
1
1
|
# minimal-cloudflare
|
|
2
2
|
|
|
3
|
-
A baerly app scaffolded with `@gusto/create-baerly-storage` for
|
|
4
|
-
Workers** target. Single-bucket R2-backed deployment
|
|
5
|
-
`@gusto/baerly-storage/cloudflare` adapter. Ships
|
|
6
|
-
day-1 happy path works with zero env vars; flip
|
|
7
|
-
Access or a shared secret before deploy — see "Going to
|
|
3
|
+
A baerly-storage app scaffolded with `@gusto/create-baerly-storage` for
|
|
4
|
+
the **Cloudflare Workers** target. Single-bucket R2-backed deployment
|
|
5
|
+
via the `@gusto/baerly-storage/cloudflare` adapter. Ships
|
|
6
|
+
`auth: "none"` so the day-1 happy path works with zero env vars; flip
|
|
7
|
+
to Cloudflare Access or a shared secret before deploy — see "Going to
|
|
8
8
|
production" below.
|
|
9
9
|
|
|
10
|
-
**The
|
|
10
|
+
**The R2 bucket is the durable state.** The Worker is trusted app code
|
|
11
|
+
with an R2 binding; it applies the baerly-storage protocol, but it is
|
|
12
|
+
not a database server. No daemon, lock table, scheduler, or idle
|
|
13
|
+
database bill; maintenance is automatic and write-triggered.
|
|
11
14
|
|
|
12
15
|
## What you got
|
|
13
16
|
|
|
@@ -86,9 +89,9 @@ needs no secrets. If you adopt a "Going to production" recipe:
|
|
|
86
89
|
`CF_ACCESS_AUDIENCE_TAG` go in `wrangler.jsonc:vars` (they're
|
|
87
90
|
public identifiers, not secrets).
|
|
88
91
|
- **Pattern B (`auth: "shared-secret"`):** `SHARED_SECRET` is a
|
|
89
|
-
secret — `.dev.vars` for `wrangler dev
|
|
90
|
-
SHARED_SECRET` for production. Each secret is
|
|
91
|
-
and exposed on `env` at runtime.
|
|
92
|
+
secret — use `.dev.vars` for `wrangler dev` and
|
|
93
|
+
`wrangler secret put SHARED_SECRET` for production. Each secret is
|
|
94
|
+
encrypted at rest and exposed on `env` at runtime.
|
|
92
95
|
|
|
93
96
|
## Next steps
|
|
94
97
|
|
|
@@ -98,9 +101,9 @@ needs no secrets. If you adopt a "Going to production" recipe:
|
|
|
98
101
|
reads `CLAUDE.md`; both files are byte-identical so either
|
|
99
102
|
surface lands you the same context.
|
|
100
103
|
2. **Declare your first collection schema** in `baerly.config.ts`
|
|
101
|
-
via `defineConfig({ collections: { ... } })
|
|
102
|
-
`Db.create({
|
|
103
|
-
bad inserts return 400.
|
|
104
|
+
via `defineConfig({ collections: { ... } })`. The Worker adapter
|
|
105
|
+
passes that config to `Db.create({ storage, app, tenant, config })`,
|
|
106
|
+
so schema validation is live and bad inserts return 400.
|
|
104
107
|
3. **Set up production auth** — follow `AGENTS.md` → "Going to
|
|
105
108
|
production". Pattern A wires CF Access via an env-aware factory
|
|
106
109
|
`verifier:` override; Pattern B flips `auth: "shared-secret"`.
|
|
@@ -118,16 +121,16 @@ needs no secrets. If you adopt a "Going to production" recipe:
|
|
|
118
121
|
|
|
119
122
|
## When to graduate
|
|
120
123
|
|
|
121
|
-
baerly is designed for the small-to-medium operating point.
|
|
122
|
-
thresholds, S3 list-prefix latency and per-class operation
|
|
123
|
-
|
|
124
|
+
baerly-storage is designed for the small-to-medium operating point.
|
|
125
|
+
Past these thresholds, S3 list-prefix latency and per-class operation
|
|
126
|
+
pricing starts to dominate, and you've outgrown the workload envelope — move to a database service:
|
|
124
127
|
|
|
125
|
-
- **~30 writes / minute / collection**
|
|
126
|
-
-
|
|
127
|
-
- **~100 collections / tenant**
|
|
128
|
+
- **~30 writes / minute / collection** — per-collection throughput estimate (CAS-livelock model)
|
|
129
|
+
- **>10 GB / tenant** — R2 free-tier storage cost line (a billing signal, not a protocol ceiling)
|
|
130
|
+
- **~100 collections / tenant** — soft fan-out guideline (linear cost, bench-grounded; nothing enforces it)
|
|
128
131
|
|
|
129
|
-
When you cross
|
|
130
|
-
`baerly export --target=postgres` walks your log entries (already Debezium-style CDC change events) into a
|
|
132
|
+
When you cross these signals, graduation is mechanical:
|
|
133
|
+
`baerly export --target=postgres` walks your log entries (already Debezium-style CDC change events) into a database service. If your
|
|
131
134
|
deploy target is Cloudflare Workers and you'll accept Cloudflare
|
|
132
135
|
lock-in, [D1](https://developers.cloudflare.com/d1/) is cheaper
|
|
133
136
|
per-write at M-size and is a natural next step. If you're on
|
|
@@ -135,7 +138,7 @@ AWS, on-prem, or want your data portable, managed Postgres is
|
|
|
135
138
|
the typical destination. Either way — graduation is a Baerly win,
|
|
136
139
|
not a churn event.
|
|
137
140
|
|
|
138
|
-
**Export to a
|
|
141
|
+
**Export to a database service** (swap `--target=` for `sqlite`,
|
|
139
142
|
`postgres`, or `d1`):
|
|
140
143
|
|
|
141
144
|
```sh
|
|
@@ -15,14 +15,14 @@
|
|
|
15
15
|
"@gusto/baerly-storage": "workspace:*"
|
|
16
16
|
},
|
|
17
17
|
"devDependencies": {
|
|
18
|
-
"@cloudflare/vite-plugin": "^1.
|
|
19
|
-
"@cloudflare/workers-types": "^4",
|
|
20
|
-
"@types/node": "^
|
|
21
|
-
"happy-dom": "^20.10.
|
|
18
|
+
"@cloudflare/vite-plugin": "^1.42.4",
|
|
19
|
+
"@cloudflare/workers-types": "^4.20260630.1",
|
|
20
|
+
"@types/node": "^26.0.1",
|
|
21
|
+
"happy-dom": "^20.10.6",
|
|
22
22
|
"typescript": "^6.0.3",
|
|
23
|
-
"vite": "^8.
|
|
24
|
-
"vitest": "^4.1.
|
|
25
|
-
"wrangler": "^4.
|
|
23
|
+
"vite": "^8.1.2",
|
|
24
|
+
"vitest": "^4.1.9",
|
|
25
|
+
"wrangler": "^4.106.0"
|
|
26
26
|
},
|
|
27
27
|
"packageManager": "pnpm@11.1.2"
|
|
28
28
|
}
|
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
{ "from": "minimal-demo", "fromKey": "tenant" }
|
|
5
5
|
],
|
|
6
6
|
"excludePaths": [".baerly/scaffold.json"],
|
|
7
|
-
"excludeNames": ["node_modules", "dist", ".DS_Store", "*.tsbuildinfo"],
|
|
7
|
+
"excludeNames": ["node_modules", "dist", ".baerly-data", ".DS_Store", "*.tsbuildinfo"],
|
|
8
8
|
"dropDevDeps": [],
|
|
9
9
|
"copies": [
|
|
10
10
|
{ "from": "AGENTS.md", "to": "CLAUDE.md" },
|
|
@@ -1,13 +1,20 @@
|
|
|
1
|
-
# Storage
|
|
2
|
-
#
|
|
3
|
-
#
|
|
1
|
+
# Storage selection. Defaults to local filesystem storage
|
|
2
|
+
# (./.baerly-data, zero credentials) for local dev. A deployment
|
|
3
|
+
# (NODE_ENV=production or a known PaaS) requires a bucket below — the
|
|
4
|
+
# server fails loud rather than running on local-fs, which is local-dev
|
|
5
|
+
# only. Self-hosting without a cloud bucket? Run MinIO on the box, or use
|
|
6
|
+
# SQLite + Litestream.
|
|
7
|
+
# MinIO is for local conformance. Other S3-compatible endpoints require
|
|
8
|
+
# `baerly doctor --bucket` plus owner validation; GCS S3-interop is not
|
|
9
|
+
# supported for database use today.
|
|
10
|
+
# AWS S3: set BUCKET + AWS creds (AWS_REGION optional).
|
|
4
11
|
AWS_ACCESS_KEY_ID=
|
|
5
12
|
AWS_SECRET_ACCESS_KEY=
|
|
6
13
|
AWS_REGION=us-east-1
|
|
7
14
|
BUCKET=
|
|
8
15
|
# Set to your Cloudflare R2 account ID (left half of the
|
|
9
|
-
# https://<account>.r2.cloudflarestorage.com endpoint) to
|
|
10
|
-
#
|
|
16
|
+
# https://<account>.r2.cloudflarestorage.com endpoint) to use R2
|
|
17
|
+
# instead of AWS S3 (still set BUCKET + AWS_* creds). Leave unset for S3.
|
|
11
18
|
# R2_ACCOUNT_ID=
|
|
12
19
|
|
|
13
20
|
# Server
|
|
@@ -1,16 +1,17 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: AGENTS.md — agent guidance for minimal-node
|
|
3
3
|
audience: agent
|
|
4
|
-
summary: How to develop and deploy minimal-node, a baerly app.
|
|
5
|
-
tags: [agent-entry, baerly]
|
|
4
|
+
summary: How to develop and deploy minimal-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,41 +38,42 @@ 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
|
-
`minimal-node` is a baerly app scaffolded with
|
|
43
|
-
Node target
|
|
44
|
-
Fly without Docker, Heroku, a VM, a
|
|
45
|
-
package: the Node-side server lives in
|
|
46
|
-
optional client lives in `src/web/`.
|
|
47
|
-
`baerly.config.ts`.
|
|
44
|
+
`minimal-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). One flat package: the Node-side server lives in
|
|
48
|
+
`src/server/index.ts`; the optional client lives in `src/web/`.
|
|
49
|
+
Configuration lives in `baerly.config.ts`.
|
|
48
50
|
|
|
49
51
|
Single package, single `vite` process: `baerlyDev()` from
|
|
50
52
|
`@gusto/baerly-storage/dev/vite` mounts the Node HTTP listener as Vite
|
|
51
53
|
middleware on `:5173` alongside the SPA dev server, so `pnpm dev`
|
|
52
54
|
brings up SPA + HMR + `/v1/*` in one command — same origin in dev,
|
|
53
|
-
same `dist/client/`-served origin in production via `pnpm start
|
|
54
|
-
|
|
55
|
-
option
|
|
55
|
+
same `dist/client/`-served origin in production via `pnpm start`. The
|
|
56
|
+
production entrypoint serves the Vite-built SPA from `dist/client/`
|
|
57
|
+
via the `baerlyNode({ webRoot: "dist/client" })` option, with `/v1/*`
|
|
58
|
+
handled by the kernel on the same origin.
|
|
56
59
|
|
|
57
60
|
If this scaffold was created with `--with=docker`, you'll also have a
|
|
58
61
|
multi-stage distroless `Dockerfile`, a `.dockerignore`, and a
|
|
59
62
|
`healthcheck.js` at the project root — wired to the same
|
|
60
63
|
`pnpm install && pnpm build && pnpm start` flow.
|
|
61
64
|
|
|
62
|
-
Public API docs:
|
|
63
|
-
|
|
64
|
-
|
|
65
|
+
Public API docs: the JSDoc on `baerly-storage`'s `Db` and `Collection`
|
|
66
|
+
is the canonical reference; read it via your editor's TS LS, the
|
|
67
|
+
published types, or `node_modules/@gusto/baerly-storage/dist/API.md`.
|
|
65
68
|
|
|
66
69
|
## Toolchain
|
|
67
70
|
|
|
68
71
|
- **Package manager:** pnpm. The emitted repo pins
|
|
69
72
|
`packageManager: pnpm@11.1.2`.
|
|
70
73
|
- **Test runner:** vitest.
|
|
71
|
-
- **Type checker:** TypeScript
|
|
72
|
-
itself uses TypeScript 7 via
|
|
73
|
-
|
|
74
|
-
apps work with the wider ecosystem.)
|
|
74
|
+
- **Type checker:** TypeScript 6.x, as pinned in `package.json`.
|
|
75
|
+
(The baerly-storage monorepo itself uses TypeScript 7 via
|
|
76
|
+
`@typescript/native-preview`.)
|
|
75
77
|
- **`erasableSyntaxOnly`** is enabled in every `tsconfig*.json` so the
|
|
76
78
|
code stays compatible with type-stripping runtimes (Node's
|
|
77
79
|
`--experimental-strip-types`, esbuild's strip path). The flag bans
|
|
@@ -90,10 +92,10 @@ read it via your editor's TS LS or via the published types).
|
|
|
90
92
|
| `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 |
|
|
91
93
|
| `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 |
|
|
92
94
|
| `pnpm typecheck` | TS typecheck across the `app` + `server` project references | seconds |
|
|
93
|
-
| `pnpm test` | `vitest run
|
|
95
|
+
| `pnpm test` | `vitest run` — standalone `vitest.config.ts` (Node env). The template ships `src/notes.test.ts` by default. | seconds |
|
|
94
96
|
| `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 |
|
|
95
97
|
| `pnpm build` | `tsc -b && vite build` — emits the SPA into `dist/client/` | seconds |
|
|
96
|
-
| `pnpm start` | `node --experimental-strip-types src/server/index.ts` — production entry; serves the SPA from `dist/client/` via `webRoot`
|
|
98
|
+
| `pnpm start` | `node --experimental-strip-types src/server/index.ts` — production entry; serves the built SPA from `dist/client/` plus `/v1/*` on the same origin via `webRoot` | seconds to start |
|
|
97
99
|
|
|
98
100
|
**`pnpm verify` exercises typecheck + tests only.** The dev-auth
|
|
99
101
|
middleware, the SPA bundle, and any custom `/api/*` route are NOT
|
|
@@ -107,7 +109,7 @@ http://localhost:5173/<path>`) before declaring the task complete.
|
|
|
107
109
|
|
|
108
110
|
| Path | What it is |
|
|
109
111
|
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
110
|
-
| `src/server/index.ts` | Server entry —
|
|
112
|
+
| `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)` |
|
|
111
113
|
| `src/web/`, `index.html` | Optional SPA shell built by Vite into `dist/client/`. `src/web/main.ts` is a ~17-line hello-world: reads `client.collection("notes").all()` to render a `${n} note(s)` count and an `[Add note]` button that inserts a timestamped row and re-fetches. Demonstrates both read and write paths on first load — extend, replace, or remove the whole tree if not needed. The `config`-bound `client.collection("notes")` is the typed surface (the generic on `.collection()` is the collection **name**, not the row type). |
|
|
112
114
|
| `vite.config.ts` | Vite client build — `outDir: dist/client`; `baerlyDev()` mounts the Node listener as middleware so SPA + `/v1/*` share `:5173` in dev |
|
|
113
115
|
| `tsconfig.{app,server}.json` | TS project references for the client and server projects |
|
|
@@ -273,7 +275,7 @@ http://localhost:5173/<path>`) before declaring the task complete.
|
|
|
273
275
|
(without the `doc` wrapper) returns
|
|
274
276
|
`400 SchemaError "Request body must be { doc: object }"` — the
|
|
275
277
|
wording is locked by `assertJsonBodyField` in the kernel. Canonical
|
|
276
|
-
reference: the
|
|
278
|
+
reference: the JSDoc on `createRouter` in
|
|
277
279
|
`baerly-storage`.
|
|
278
280
|
|
|
279
281
|
- **Auth** — your scaffold ships `auth: "none"` in `baerly.config.ts`:
|
|
@@ -350,29 +352,35 @@ Dev sees `JWKS_URL` as `undefined`, spread short-circuits, and
|
|
|
350
352
|
`config.auth: "none"` runs. Prod sets `JWKS_URL` + `JWT_ISSUER` +
|
|
351
353
|
`JWT_AUDIENCE` and `bearerJwt` engages. Use `tenantClaim` when your
|
|
352
354
|
IdP issues one tenant per token; use `tenantPrefix` for single-tenant
|
|
353
|
-
apps or tenancy enforced outside
|
|
355
|
+
apps or tenancy enforced outside baerly-storage.
|
|
354
356
|
|
|
355
357
|
<!-- pattern-c:end -->
|
|
356
358
|
|
|
357
|
-
- **Storage backend** — `src/server/index.ts`
|
|
358
|
-
`
|
|
359
|
-
`
|
|
360
|
-
|
|
361
|
-
`
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
359
|
+
- **Storage backend** — `src/server/index.ts` resolves storage by env:
|
|
360
|
+
`R2_ACCOUNT_ID` → Cloudflare R2, else `BUCKET` → AWS S3, else
|
|
361
|
+
zero-config `localFsStorage()` (persists to `./.baerly-data`, no
|
|
362
|
+
credentials, local dev only). **In a detected deployment
|
|
363
|
+
(`NODE_ENV=production` or a known PaaS) the server fails loud and
|
|
364
|
+
requires a bucket** — local-fs is single-process with no cross-process
|
|
365
|
+
CAS or crash durability, so it is never a production store (there is no
|
|
366
|
+
opt-in). AWS S3 and Cloudflare R2 are the production-supported stores;
|
|
367
|
+
self-hosting without a cloud bucket, run **MinIO** on the box (also the
|
|
368
|
+
local/dev conformance target) or graduate to SQLite + Litestream. Other S3-compatible endpoints need a
|
|
369
|
+
green `baerly doctor --bucket` plus owner validation; GCS S3-interop
|
|
370
|
+
is not supported for database use today. JSDoc `@example` blocks for
|
|
371
|
+
the factories are visible in your editor's TS hover.
|
|
372
|
+
|
|
373
|
+
- **Switching from static creds to EKS** — in
|
|
368
374
|
`src/server/index.ts`, swap `credentials: { accessKeyId,
|
|
369
|
-
secretAccessKey }` for `credentials:
|
|
370
|
-
|
|
371
|
-
`import { s3Storage,
|
|
372
|
-
|
|
373
|
-
`
|
|
374
|
-
|
|
375
|
-
`
|
|
375
|
+
secretAccessKey }` for `credentials: fromEks()` and add `fromEks`
|
|
376
|
+
to your import:
|
|
377
|
+
`import { s3Storage, fromEks } from "@gusto/baerly-storage/node"`.
|
|
378
|
+
`fromEks()` auto-detects the cluster's mechanism — EKS Pod Identity
|
|
379
|
+
(`AWS_CONTAINER_CREDENTIALS_FULL_URI` +
|
|
380
|
+
`AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE`) or IRSA (`AWS_ROLE_ARN` +
|
|
381
|
+
`AWS_WEB_IDENTITY_TOKEN_FILE`), both EKS-injected; to pin one, use
|
|
382
|
+
`fromEksPodIdentity()` or `fromWebIdentity()`. For ECS / EC2 / other
|
|
383
|
+
AWS contexts, see `packages/adapter-node/AGENTS.md` — pass any
|
|
376
384
|
`() => Promise<Credentials>` or an `@aws-sdk/credential-providers`
|
|
377
385
|
factory through the seam.
|
|
378
386
|
|
|
@@ -438,15 +446,16 @@ your own schedule. Not required for steady-state operation.
|
|
|
438
446
|
|
|
439
447
|
## When to graduate
|
|
440
448
|
|
|
441
|
-
baerly is designed for the small-to-medium operating point.
|
|
442
|
-
model puts the soft ceiling at:
|
|
449
|
+
baerly-storage is designed for the small-to-medium operating point.
|
|
450
|
+
The cost model puts the soft ceiling at:
|
|
443
451
|
|
|
444
|
-
- **~30 writes / minute / collection**
|
|
445
|
-
-
|
|
446
|
-
- **~100 collections / tenant**
|
|
452
|
+
- **~30 writes / minute / collection** (throughput ceiling — model/estimate)
|
|
453
|
+
- **>10 GB / tenant stored** (R2 free-tier storage line — a cost signal, not a protocol ceiling)
|
|
454
|
+
- **~100 collections / tenant** (soft fan-out guideline — bench-grounded linear cost)
|
|
447
455
|
|
|
448
|
-
|
|
449
|
-
op pricing start to dominate;
|
|
456
|
+
At M-size (~30 writes/min) the projected cost is ~$26/mo on S3 (~$18/mo on R2). Past
|
|
457
|
+
those, per-class op pricing and fan-out scan cost start to dominate;
|
|
458
|
+
you've outgrown the workload envelope — move to a database service (D1 / Postgres) suited to higher scale.
|
|
450
459
|
Pick your graduation target:
|
|
451
460
|
|
|
452
461
|
- **Cloudflare Workers + lock-in OK:** [D1](https://developers.cloudflare.com/d1/) — cheaper per-write at M-size.
|
|
@@ -454,8 +463,8 @@ Pick your graduation target:
|
|
|
454
463
|
- **Single-instance Node:** SQLite via Litestream.
|
|
455
464
|
|
|
456
465
|
Either way, the export below is mechanical because log entries are
|
|
457
|
-
Debezium-style CDC change events — graduation is a
|
|
458
|
-
not a churn event.
|
|
466
|
+
Debezium-style CDC change events — graduation is a baerly-storage
|
|
467
|
+
win, not a churn event.
|
|
459
468
|
|
|
460
469
|
**Estimate your current rate:** for Node/self-hosted buckets,
|
|
461
470
|
`baerly admin usage --target=node --bucket=<bucket-uri> --app=<app>
|