@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,11 +1,17 @@
|
|
|
1
1
|
# react-cloudflare
|
|
2
2
|
|
|
3
|
-
A baerly app scaffolded with `@gusto/create-baerly-storage` for
|
|
4
|
-
Workers** target, with a React + Vite SPA.
|
|
5
|
-
|
|
6
|
-
so the day-1
|
|
7
|
-
|
|
8
|
-
|
|
3
|
+
A baerly-storage app scaffolded with `@gusto/create-baerly-storage` for
|
|
4
|
+
the **Cloudflare Workers** target, with a React + Vite SPA.
|
|
5
|
+
Single-bucket R2-backed deployment via
|
|
6
|
+
`@gusto/baerly-storage/cloudflare`. Ships `auth: "none"` so the day-1
|
|
7
|
+
happy path works with zero env vars, plus a one-collection `notes`
|
|
8
|
+
schema you extend; flip to Cloudflare Access or a shared secret before
|
|
9
|
+
deploy — see "Production auth" below.
|
|
10
|
+
|
|
11
|
+
**The R2 bucket is the durable state.** The Worker is trusted app code
|
|
12
|
+
with an R2 binding; it applies the baerly-storage protocol, but it is
|
|
13
|
+
not a database server. No daemon, lock table, scheduler, or idle
|
|
14
|
+
database bill; maintenance is automatic and write-triggered.
|
|
9
15
|
|
|
10
16
|
## What you got
|
|
11
17
|
|
|
@@ -16,7 +22,7 @@ react-cloudflare/
|
|
|
16
22
|
├── tsconfig.app.json # client TS project (src/web)
|
|
17
23
|
├── tsconfig.worker.json # Worker TS project (src/server)
|
|
18
24
|
├── vite.config.ts # Vite + @vitejs/plugin-react + @cloudflare/vite-plugin
|
|
19
|
-
├── wrangler.jsonc # Worker manifest — R2 binding, assets, vars
|
|
25
|
+
├── wrangler.jsonc # Worker manifest — R2 binding, assets, vars
|
|
20
26
|
├── index.html # SPA shell — Vite's entry point
|
|
21
27
|
├── baerly.config.ts # app, tenant, target, NoteSchema, `Note` type
|
|
22
28
|
├── AGENTS.md # deeper guide: hooks, schema, auth, deploy
|
|
@@ -46,7 +52,7 @@ share an origin (`http://localhost:5173`). First run downloads the
|
|
|
46
52
|
|
|
47
53
|
Open <http://localhost:5173>. Type a note, hit "Add note." Open a
|
|
48
54
|
second tab — inserts, edits, and deletes in one tab appear in the
|
|
49
|
-
other over the `/v1/since
|
|
55
|
+
other over the `/v1/since?collection=notes&cursor=...` long-poll.
|
|
50
56
|
|
|
51
57
|
`pnpm build` runs `tsc -b && vite build`; the SPA lands in
|
|
52
58
|
`dist/client/` for the `assets:` binding in `wrangler.jsonc` to
|
|
@@ -56,7 +62,7 @@ serve on deploy.
|
|
|
56
62
|
|
|
57
63
|
```sh
|
|
58
64
|
baerly deploy # reads baerly.config.ts:target, runs wrangler deploy
|
|
59
|
-
baerly doctor --target=cloudflare # verify bindings, secrets,
|
|
65
|
+
baerly doctor --target=cloudflare # verify bindings, secrets, optional triggers
|
|
60
66
|
```
|
|
61
67
|
|
|
62
68
|
`baerly doctor --target=cloudflare` warns on `auth: "none"` for
|
|
@@ -91,7 +97,8 @@ follow `AGENTS.md` → "Going to production":
|
|
|
91
97
|
`wrangler.jsonc:vars`. The `cloudflareAccess()` preset
|
|
92
98
|
(re-exported from `@gusto/baerly-storage/auth`) reads the JWT off
|
|
93
99
|
`Cf-Access-Jwt-Assertion`, validates it against your team's JWKS,
|
|
94
|
-
and
|
|
100
|
+
and pins `tenantPrefix` to `config.tenant` unless you pass an
|
|
101
|
+
explicit tenant claim.
|
|
95
102
|
- **Pattern B — `auth: "shared-secret"`.** Single-tenant
|
|
96
103
|
server-to-server callers. Flip `auth` in `baerly.config.ts`, set
|
|
97
104
|
`SHARED_SECRET` via `wrangler secret put`, and re-enable
|
|
@@ -100,16 +107,18 @@ follow `AGENTS.md` → "Going to production":
|
|
|
100
107
|
|
|
101
108
|
## When to graduate
|
|
102
109
|
|
|
103
|
-
baerly is sized for the small-to-medium operating point. Past
|
|
104
|
-
~30 writes/min/collection
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
110
|
+
baerly-storage is sized for the small-to-medium operating point. Past
|
|
111
|
+
~30 writes/min/collection (throughput estimate), the R2 free-tier
|
|
112
|
+
storage cost line (>10 GB/tenant), or the soft fan-out guideline
|
|
113
|
+
(~100 collections/tenant — linear cost, nothing enforces it),
|
|
114
|
+
graduate to D1 or Postgres via `baerly export --target=postgres`.
|
|
115
|
+
Your data was already in your bucket; the export is a mechanical
|
|
116
|
+
translator, not a vendor migration.
|
|
108
117
|
|
|
109
118
|
## Pointers
|
|
110
119
|
|
|
111
120
|
- `baerly.config.ts` — app config + Zod schema.
|
|
112
|
-
- `src/server/index.ts` — Worker fetch
|
|
121
|
+
- `src/server/index.ts` — Worker fetch entry.
|
|
113
122
|
- `src/web/NoteList.tsx` — `useQuery` reactive read.
|
|
114
123
|
- `wrangler.jsonc` — Cloudflare Worker manifest.
|
|
115
124
|
- `AGENTS.md` / `CLAUDE.md` — agent-facing guide (byte-identical).
|
|
@@ -13,22 +13,22 @@
|
|
|
13
13
|
},
|
|
14
14
|
"dependencies": {
|
|
15
15
|
"@gusto/baerly-storage": "workspace:*",
|
|
16
|
-
"react": "^19.
|
|
17
|
-
"react-dom": "^19.
|
|
16
|
+
"react": "^19.2.7",
|
|
17
|
+
"react-dom": "^19.2.7",
|
|
18
18
|
"zod": "^4.4.3"
|
|
19
19
|
},
|
|
20
20
|
"devDependencies": {
|
|
21
|
-
"@cloudflare/vite-plugin": "^1.
|
|
22
|
-
"@cloudflare/workers-types": "^4",
|
|
23
|
-
"@types/node": "^
|
|
24
|
-
"@types/react": "^19.2.
|
|
25
|
-
"@types/react-dom": "^19.
|
|
26
|
-
"@vitejs/plugin-react": "^6.0.
|
|
27
|
-
"happy-dom": "^20.
|
|
21
|
+
"@cloudflare/vite-plugin": "^1.42.4",
|
|
22
|
+
"@cloudflare/workers-types": "^4.20260630.1",
|
|
23
|
+
"@types/node": "^26.0.1",
|
|
24
|
+
"@types/react": "^19.2.17",
|
|
25
|
+
"@types/react-dom": "^19.2.3",
|
|
26
|
+
"@vitejs/plugin-react": "^6.0.3",
|
|
27
|
+
"happy-dom": "^20.10.6",
|
|
28
28
|
"typescript": "^6.0.3",
|
|
29
|
-
"vite": "^8.
|
|
30
|
-
"vitest": "^4.1.
|
|
31
|
-
"wrangler": "^4.
|
|
29
|
+
"vite": "^8.1.2",
|
|
30
|
+
"vitest": "^4.1.9",
|
|
31
|
+
"wrangler": "^4.106.0"
|
|
32
32
|
},
|
|
33
33
|
"packageManager": "pnpm@11.1.2"
|
|
34
34
|
}
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
// Cloudflare Worker manifest. See `AGENTS.md` for what each field
|
|
3
|
-
// drives (R2 binding, assets, vars
|
|
3
|
+
// drives (R2 binding, assets, vars) and how
|
|
4
4
|
// the verifier consumes the vars.
|
|
5
5
|
"$schema": "node_modules/wrangler/config-schema.json",
|
|
6
6
|
"name": "react-cloudflare",
|
|
@@ -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 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
|
|
@@ -135,22 +137,34 @@ http://localhost:5173/<path>`) before declaring the task complete.
|
|
|
135
137
|
|
|
136
138
|
## When editing X, read Y
|
|
137
139
|
|
|
138
|
-
- **Typed collections** —
|
|
140
|
+
- **Typed collections** — two ways to get a typed row, in DX order.
|
|
141
|
+
The generic on `client.collection<N>(name)` is the collection
|
|
142
|
+
**name** (constrained to `CollectionNames<typeof config>`), not the
|
|
143
|
+
row type — so don't pass a row type to it.
|
|
139
144
|
1. **Bind the config.** This template's `src/web/client.ts`
|
|
140
145
|
already passes `config` to `createBaerlyClient({ baseUrl,
|
|
141
146
|
config })`, so `client.collection("notes")` returns
|
|
142
147
|
`ClientCollection<Row>` with `Row` derived from the
|
|
143
148
|
`NoteSchema` declared in `baerly.config.ts`. No generic
|
|
144
|
-
needed.
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
2. **
|
|
148
|
-
|
|
149
|
-
|
|
149
|
+
needed. When you need to name that row type elsewhere, use
|
|
150
|
+
`RowOf<typeof config, "notes">` (re-exported from
|
|
151
|
+
`@gusto/baerly-storage`) — not a generic on `.collection()`.
|
|
152
|
+
2. **Cast the handle (undeclared collection).** This template's
|
|
153
|
+
`client` is bound to `config`, so its names narrow to the
|
|
154
|
+
declared collections. To reach a collection that isn't in
|
|
155
|
+
`config`, build an unbound client
|
|
156
|
+
(`createBaerlyClient({ baseUrl })` with no `config`) — its names
|
|
157
|
+
widen to `string` and its row defaults to `DocumentData`. Cast at
|
|
158
|
+
the construction site for a narrower shape that still satisfies
|
|
159
|
+
the kernel's `DocumentData` constraint
|
|
160
|
+
(`{ [k: string]: DocumentValue }`):
|
|
150
161
|
```ts
|
|
162
|
+
import { createBaerlyClient, type ClientCollection } from "@gusto/baerly-storage/client";
|
|
151
163
|
import type { DocumentData } from "@gusto/baerly-storage";
|
|
152
164
|
interface Bookmark extends DocumentData { _id: string; url: string }
|
|
153
|
-
|
|
165
|
+
const raw = createBaerlyClient({ baseUrl: "" });
|
|
166
|
+
const bookmarks = raw.collection("bookmarks") as ClientCollection<Bookmark>;
|
|
167
|
+
await bookmarks.all();
|
|
154
168
|
```
|
|
155
169
|
A plain `interface Bookmark { _id: string; url: string }`
|
|
156
170
|
(no index signature) will fail with TS2344 — the constraint
|
|
@@ -246,9 +260,10 @@ http://localhost:5173/<path>`) before declaring the task complete.
|
|
|
246
260
|
});
|
|
247
261
|
```
|
|
248
262
|
|
|
249
|
-
The adapter
|
|
250
|
-
|
|
251
|
-
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.
|
|
252
267
|
|
|
253
268
|
- **Schemas (live feature)** — schemas are validated on the server
|
|
254
269
|
for every `insert` / `update` / `replace` when bound. Declare via
|
|
@@ -273,7 +288,7 @@ http://localhost:5173/<path>`) before declaring the task complete.
|
|
|
273
288
|
|
|
274
289
|
On a validation failure the server throws
|
|
275
290
|
`BaerlyError{ code: "SchemaError", issues: [{ path, message }] }`;
|
|
276
|
-
HTTP clients see a
|
|
291
|
+
HTTP clients see a 400 with the same envelope. Validation runs
|
|
277
292
|
on the post-image so `update` and `replace` see the full doc, not
|
|
278
293
|
just the patch.
|
|
279
294
|
|
|
@@ -294,7 +309,7 @@ http://localhost:5173/<path>`) before declaring the task complete.
|
|
|
294
309
|
(without the `doc` wrapper) returns
|
|
295
310
|
`400 SchemaError "Request body must be { doc: object }"` — the
|
|
296
311
|
wording is locked by `assertJsonBodyField` in the kernel. Canonical
|
|
297
|
-
reference: the
|
|
312
|
+
reference: the JSDoc on `createRouter` in
|
|
298
313
|
`baerly-storage`.
|
|
299
314
|
|
|
300
315
|
- **Auth** — your scaffold ships `auth: "none"` in `baerly.config.ts`:
|
|
@@ -302,9 +317,11 @@ http://localhost:5173/<path>`) before declaring the task complete.
|
|
|
302
317
|
is ignored. The adapter reads `config.auth` to pick its verifier;
|
|
303
318
|
a `verifier:` on `baerlyNode({ ... })` overrides it. The schema-
|
|
304
319
|
bound `notes` collection (`baerly.config.ts:NoteSchema`) runs
|
|
305
|
-
server-side regardless of the auth posture. `baerly
|
|
306
|
-
--target=node`
|
|
307
|
-
|
|
320
|
+
server-side regardless of the auth posture. There is no `baerly
|
|
321
|
+
doctor --target=node` backend today; verify bucket CAS with
|
|
322
|
+
`baerly doctor --bucket=<s3-uri>` and probe `/v1/healthz` after
|
|
323
|
+
deploy. See "Going to production" below for the two production-fit
|
|
324
|
+
recipes.
|
|
308
325
|
|
|
309
326
|
### Going to production
|
|
310
327
|
|
|
@@ -324,9 +341,9 @@ auth: "shared-secret", // ← flip from "none"
|
|
|
324
341
|
|
|
325
342
|
Dev: put `SHARED_SECRET=dev-shared-secret` in `.env`. Prod: set
|
|
326
343
|
`SHARED_SECRET` in the process environment (your PaaS / secret
|
|
327
|
-
manager).
|
|
328
|
-
|
|
329
|
-
`
|
|
344
|
+
manager). The Node process fails closed if `auth: "shared-secret"`
|
|
345
|
+
is set without `SHARED_SECRET` reachable from `process.env`; verify
|
|
346
|
+
the live bucket separately with `baerly doctor --bucket=<s3-uri>`.
|
|
330
347
|
|
|
331
348
|
<!-- pattern-b:end -->
|
|
332
349
|
<!-- pattern-c:start -->
|
|
@@ -360,6 +377,7 @@ await baerlyNode({
|
|
|
360
377
|
jwks: process.env["JWKS_URL"],
|
|
361
378
|
issuer: process.env["JWT_ISSUER"]!,
|
|
362
379
|
audience: process.env["JWT_AUDIENCE"]!,
|
|
380
|
+
tenantPrefix: config.tenant, // or tenantClaim: "tenant"
|
|
363
381
|
}),
|
|
364
382
|
}),
|
|
365
383
|
}).listen(Number(process.env["PORT"] ?? 8080));
|
|
@@ -367,31 +385,38 @@ await baerlyNode({
|
|
|
367
385
|
|
|
368
386
|
Dev sees `JWKS_URL` as `undefined`, spread short-circuits, and
|
|
369
387
|
`config.auth: "none"` runs. Prod sets `JWKS_URL` + `JWT_ISSUER` +
|
|
370
|
-
`JWT_AUDIENCE` and `bearerJwt` engages.
|
|
388
|
+
`JWT_AUDIENCE` and `bearerJwt` engages. Use `tenantClaim` when your
|
|
389
|
+
IdP issues one tenant per token; use `tenantPrefix` for single-tenant
|
|
390
|
+
apps or tenancy enforced outside baerly-storage.
|
|
371
391
|
|
|
372
392
|
<!-- pattern-c:end -->
|
|
373
|
-
- **Storage backend** — `src/server/index.ts`
|
|
374
|
-
`
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
`
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
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
|
|
383
406
|
`AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` (and optional
|
|
384
407
|
`AWS_REGION`).
|
|
385
408
|
|
|
386
|
-
- **Switching from static creds to EKS
|
|
409
|
+
- **Switching from static creds to EKS** — in
|
|
387
410
|
`src/server/index.ts`, swap `credentials: { accessKeyId,
|
|
388
|
-
secretAccessKey }` for `credentials:
|
|
389
|
-
|
|
390
|
-
`import { s3Storage,
|
|
391
|
-
|
|
392
|
-
`
|
|
393
|
-
|
|
394
|
-
`
|
|
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
|
|
395
420
|
`() => Promise<Credentials>` or an `@aws-sdk/credential-providers`
|
|
396
421
|
factory through the seam.
|
|
397
422
|
|
|
@@ -400,12 +425,16 @@ Dev sees `JWKS_URL` as `undefined`, spread short-circuits, and
|
|
|
400
425
|
`node --experimental-strip-types src/server/index.ts`. Arrange the
|
|
401
426
|
host to run `pnpm install && pnpm build` (populates
|
|
402
427
|
`dist/client/` for the `webRoot` static-serve branch) before
|
|
403
|
-
`pnpm start`.
|
|
404
|
-
|
|
405
|
-
`
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
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).
|
|
409
438
|
|
|
410
439
|
Shapes: **managed PaaS** (Railway, Render, DO App Platform, Fly
|
|
411
440
|
without Docker, Heroku) auto-detects Node and runs the root
|
|
@@ -431,7 +460,8 @@ Dev sees `JWKS_URL` as `undefined`, spread short-circuits, and
|
|
|
431
460
|
into the predicate so the index planner can prune
|
|
432
461
|
(`db.collection("notes").where({ ... }).all()`), or maintain a
|
|
433
462
|
side-projection (Postgres/SQLite/search index) populated
|
|
434
|
-
incrementally from the `/v1/since
|
|
463
|
+
incrementally from the `/v1/since?collection=<name>&cursor=<opaque>`
|
|
464
|
+
log feed or from a write hook —
|
|
435
465
|
never re-scan per request.
|
|
436
466
|
|
|
437
467
|
## Maintenance
|
|
@@ -450,7 +480,7 @@ maintenance, so the published idle-reader cost bound holds.
|
|
|
450
480
|
A bucket maintains itself as long as it takes writes. A bucket served read-only does
|
|
451
481
|
not auto-compact and pays a small, bounded replay — fine at small scale, a signal to
|
|
452
482
|
graduate once a collection is large. See docs/about/graduation.md for the per-tier
|
|
453
|
-
envelope and the BAERLY_MAINTENANCE_
|
|
483
|
+
envelope and the `BAERLY_MAINTENANCE_*` operator env vars (you almost never need them).
|
|
454
484
|
|
|
455
485
|
Operator opt-in: call runScheduledMaintenance from @gusto/baerly-storage/maintenance on
|
|
456
486
|
your own schedule. Not required for steady-state operation.
|
|
@@ -458,28 +488,32 @@ your own schedule. Not required for steady-state operation.
|
|
|
458
488
|
|
|
459
489
|
## When to graduate
|
|
460
490
|
|
|
461
|
-
baerly is designed for the small-to-medium operating point.
|
|
462
|
-
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:
|
|
463
493
|
|
|
464
|
-
- **~30 writes / minute / collection**
|
|
465
|
-
-
|
|
466
|
-
- **~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)
|
|
467
497
|
|
|
468
|
-
|
|
469
|
-
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.
|
|
470
501
|
Pick your graduation target:
|
|
471
502
|
- **Cloudflare Workers + lock-in OK:** [D1](https://developers.cloudflare.com/d1/) — cheaper per-write at M-size.
|
|
472
503
|
- **Off-Workers or portability matters:** managed Postgres.
|
|
473
504
|
- **Single-instance Node:** SQLite via Litestream.
|
|
474
505
|
|
|
475
506
|
Either way, the export below is mechanical because log entries are
|
|
476
|
-
|
|
477
|
-
not a churn event.
|
|
507
|
+
Debezium-style CDC change events — graduation is a baerly-storage
|
|
508
|
+
win, not a churn event.
|
|
478
509
|
|
|
479
|
-
**Estimate your current rate:**
|
|
480
|
-
|
|
481
|
-
|
|
482
|
-
|
|
510
|
+
**Estimate your current rate:** for Node/self-hosted buckets,
|
|
511
|
+
`baerly admin usage --target=node --bucket=<bucket-uri> --app=<app>
|
|
512
|
+
--tenant=<tenant>` lists recent log entries per collection and computes
|
|
513
|
+
writes/min. On Cloudflare, use canonical logs for trend history and
|
|
514
|
+
`baerly cost --bucket=<bucket-uri> --collection=<collection>` for the
|
|
515
|
+
current operation-cost projection until the usage scanner is wired to
|
|
516
|
+
R2 bindings.
|
|
483
517
|
|
|
484
518
|
**Export when ready:** `baerly export --target=sqlite|postgres|d1
|
|
485
519
|
--bucket=<...> --app=<...> --tenant=<...> --collection=<...>` writes a
|
|
@@ -562,7 +596,8 @@ const result = useQuery(
|
|
|
562
596
|
```
|
|
563
597
|
|
|
564
598
|
`useQuery` re-runs the callback when `deps` changes OR when the
|
|
565
|
-
`/v1/since
|
|
599
|
+
`/v1/since?collection=<name>&cursor=<opaque>` long-poll batches a
|
|
600
|
+
non-empty change for any subscribed
|
|
566
601
|
collection. Idle long-poll cycles (empty batches) drop at the
|
|
567
602
|
`subscription-pool` layer, so a steady-state collection costs zero list
|
|
568
603
|
reads. Add a `<select>` bound to `setFilter` and the list narrows live.
|
|
@@ -630,8 +665,9 @@ JSON-merge-patch (RFC 7386) semantics apply on `update()`:
|
|
|
630
665
|
omitting `tags` from an update preserves the existing value;
|
|
631
666
|
passing `tags: null` deletes the field; passing `tags: []` sets
|
|
632
667
|
it to an empty array. Note that `null` is the deletion sentinel,
|
|
633
|
-
not a storable value — `DocumentValue` doesn't include `null`,
|
|
634
|
-
|
|
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`.
|
|
635
671
|
That's why this recipe uses `.optional()` and not `.nullable()`.
|
|
636
672
|
|
|
637
673
|
## Pointers
|