@gusto/create-baerly-storage 0.3.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/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,15 +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
|
-
|
|
11
|
-
|
|
12
|
-
|
|
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.
|
|
13
21
|
|
|
14
22
|
To ship a production Dockerfile alongside, scaffold with
|
|
15
23
|
`--with=docker` — the add-on writes a multi-stage distroless Dockerfile,
|
|
@@ -25,13 +33,13 @@ minimal-node/
|
|
|
25
33
|
├── tsconfig.server.json # Node server TS project (src/server)
|
|
26
34
|
├── vite.config.ts # Vite SPA build → dist/client/
|
|
27
35
|
├── index.html # SPA shell — Vite's entry point
|
|
28
|
-
├── .env.example # storage
|
|
36
|
+
├── .env.example # storage selection (local-fs default) + PORT
|
|
29
37
|
├── baerly.config.ts # app, tenant, target, domain
|
|
30
38
|
├── AGENTS.md # deeper guide: predicates, schemas,
|
|
31
39
|
│ # auth recipes, graduation
|
|
32
40
|
├── src/
|
|
33
41
|
│ ├── server/
|
|
34
|
-
│ │ └── index.ts # baerlyNode({ config, storage,
|
|
42
|
+
│ │ └── index.ts # baerlyNode({ config, storage, webRoot }).listen(PORT)
|
|
35
43
|
│ └── web/
|
|
36
44
|
│ └── main.ts # SPA client entry — bundled into dist/client/
|
|
37
45
|
└── README.md
|
|
@@ -47,27 +55,43 @@ pnpm dev
|
|
|
47
55
|
`pnpm dev` runs `vite`. `baerlyDev()` from `@gusto/baerly-storage/dev/vite`
|
|
48
56
|
mounts the Node HTTP listener as Connect middleware on the same Vite
|
|
49
57
|
process that serves the SPA, so `GET /` hits the SPA on
|
|
50
|
-
`http://localhost:5173/` and anything baerly handles (e.g.
|
|
58
|
+
`http://localhost:5173/` and anything baerly-storage handles (e.g.
|
|
51
59
|
`GET /v1/healthz`) is served on the same origin — one process, one
|
|
52
60
|
port, SPA + HMR + `/v1/*` in one command. Storage is `LocalFsStorage`
|
|
53
61
|
rooted at `.baerly-data/`, so first-touch needs no S3 creds, no JWKS,
|
|
54
62
|
and no second process.
|
|
55
63
|
|
|
56
|
-
For production-shaped local runs (
|
|
57
|
-
|
|
64
|
+
For production-shaped local runs (the built SPA served from
|
|
65
|
+
`dist/client/` alongside `/v1/*`):
|
|
58
66
|
|
|
59
67
|
```sh
|
|
60
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
|
|
61
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
|
|
62
82
|
```
|
|
63
83
|
|
|
64
84
|
The server reads `BUCKET`, `AWS_ACCESS_KEY_ID`,
|
|
65
|
-
`AWS_SECRET_ACCESS_KEY` at startup
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
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.
|
|
71
95
|
|
|
72
96
|
Maintenance (compaction + GC) is automatic and in-band: it runs
|
|
73
97
|
inline on the rare write that crosses a maintenance trigger — no env
|
|
@@ -77,9 +101,9 @@ snapshot ceiling and `BAERLY_MAINTENANCE_DISABLE=1` is a kill switch.
|
|
|
77
101
|
For an explicit out-of-band sweep, call `runScheduledMaintenance`
|
|
78
102
|
from `@gusto/baerly-storage`.
|
|
79
103
|
|
|
80
|
-
After `pnpm build`, `
|
|
81
|
-
|
|
82
|
-
|
|
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.
|
|
83
107
|
|
|
84
108
|
`pnpm typecheck` runs `tsc -b --noEmit` across both project
|
|
85
109
|
references.
|
|
@@ -89,7 +113,12 @@ references.
|
|
|
89
113
|
This scaffold runs anywhere `node server.js` runs. The `package.json`
|
|
90
114
|
exposes `build` (Vite SPA + TS check) and `start`
|
|
91
115
|
(`node --experimental-strip-types src/server/index.ts`); arrange your
|
|
92
|
-
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.
|
|
93
122
|
|
|
94
123
|
Concrete shapes:
|
|
95
124
|
|
|
@@ -98,10 +127,12 @@ Concrete shapes:
|
|
|
98
127
|
repo, set env vars from `.env.example` in the dashboard, deploy.
|
|
99
128
|
The platform's buildpack detects Node and runs the root scripts.
|
|
100
129
|
- **VM / bare-metal**: clone, install Node 24+, copy `.env.example`
|
|
101
|
-
to `.env
|
|
102
|
-
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.
|
|
103
134
|
- **Container** (Docker, k8s, ECS, Fly Machines with a Dockerfile):
|
|
104
|
-
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
|
|
105
136
|
a production Dockerfile, `.dockerignore`, and `healthcheck.js`
|
|
106
137
|
alongside this shape, then `docker build .`.
|
|
107
138
|
|
|
@@ -115,9 +146,9 @@ Verify: `curl https://<your-service>/v1/healthz`.
|
|
|
115
146
|
users: `@gusto/create-baerly-storage` mirrors `AGENTS.md` to `CLAUDE.md` at
|
|
116
147
|
scaffold time.)
|
|
117
148
|
2. **Declare your first collection schema** in `baerly.config.ts`
|
|
118
|
-
via `defineConfig({ collections: { ... } })
|
|
119
|
-
`Db.create({
|
|
120
|
-
bad inserts return 400.
|
|
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.
|
|
121
152
|
3. **Set up production auth** — follow `AGENTS.md` → "Going to
|
|
122
153
|
production". Pattern B flips `auth: "shared-secret"` and reads
|
|
123
154
|
`SHARED_SECRET` from `process.env`; Pattern C wires `bearerJwt`
|
|
@@ -128,16 +159,16 @@ Verify: `curl https://<your-service>/v1/healthz`.
|
|
|
128
159
|
|
|
129
160
|
## When to graduate
|
|
130
161
|
|
|
131
|
-
baerly is designed for the small-to-medium operating point.
|
|
132
|
-
thresholds, S3 list-prefix latency and per-class operation
|
|
133
|
-
|
|
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:
|
|
134
165
|
|
|
135
|
-
- **~30 writes / minute / collection**
|
|
136
|
-
-
|
|
137
|
-
- **~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)
|
|
138
169
|
|
|
139
|
-
When you cross
|
|
140
|
-
`baerly export --target=postgres` walks your log entries (already Debezium-style CDC change events) into a
|
|
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
|
|
141
172
|
deploy target is Cloudflare Workers and you'll accept Cloudflare
|
|
142
173
|
lock-in, [D1](https://developers.cloudflare.com/d1/) is cheaper
|
|
143
174
|
per-write at M-size and is a natural next step. If you're on
|
|
@@ -145,7 +176,7 @@ AWS, on-prem, or want your data portable, managed Postgres is
|
|
|
145
176
|
the typical destination. Either way — graduation is a Baerly win,
|
|
146
177
|
not a churn event.
|
|
147
178
|
|
|
148
|
-
**Export to a
|
|
179
|
+
**Export to a database service** (swap `--target=` for `sqlite`,
|
|
149
180
|
`postgres`, or `d1`):
|
|
150
181
|
|
|
151
182
|
```sh
|
|
@@ -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.10.
|
|
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 |
|
|
@@ -299,7 +301,7 @@ http://localhost:5173/<path>`) before declaring the task complete.
|
|
|
299
301
|
(without the `doc` wrapper) returns
|
|
300
302
|
`400 SchemaError "Request body must be { doc: object }"` — the
|
|
301
303
|
wording is locked by `assertJsonBodyField` in the kernel. Canonical
|
|
302
|
-
reference: the
|
|
304
|
+
reference: the JSDoc on `createRouter` in
|
|
303
305
|
`baerly-storage`.
|
|
304
306
|
|
|
305
307
|
- **Auth** — your scaffold ships `auth: "none"` in `baerly.config.ts`:
|
|
@@ -542,23 +544,24 @@ your own schedule. Not required for steady-state operation.
|
|
|
542
544
|
|
|
543
545
|
## When to graduate
|
|
544
546
|
|
|
545
|
-
baerly is designed for the small-to-medium operating point.
|
|
546
|
-
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:
|
|
547
549
|
|
|
548
|
-
- **~30 writes / minute / collection**
|
|
549
|
-
-
|
|
550
|
-
- **~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)
|
|
551
553
|
|
|
552
|
-
|
|
553
|
-
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.
|
|
554
557
|
Pick your graduation target:
|
|
555
558
|
- **Cloudflare Workers + lock-in OK:** [D1](https://developers.cloudflare.com/d1/) — cheaper per-write at M-size.
|
|
556
559
|
- **Off-Workers or portability matters:** managed Postgres.
|
|
557
560
|
- **Single-instance Node:** SQLite via Litestream.
|
|
558
561
|
|
|
559
562
|
Either way, the export below is mechanical because log entries are
|
|
560
|
-
Debezium-style CDC change events — graduation is a
|
|
561
|
-
not a churn event.
|
|
563
|
+
Debezium-style CDC change events — graduation is a baerly-storage
|
|
564
|
+
win, not a churn event.
|
|
562
565
|
|
|
563
566
|
**Estimate your current rate:** for Node/self-hosted buckets,
|
|
564
567
|
`baerly admin usage --target=node --bucket=<bucket-uri> --app=<app>
|
|
@@ -718,8 +721,9 @@ JSON-merge-patch (RFC 7386) semantics apply on `update()`:
|
|
|
718
721
|
omitting `tags` from an update preserves the existing value;
|
|
719
722
|
passing `tags: null` deletes the field; passing `tags: []` sets
|
|
720
723
|
it to an empty array. Note that `null` is the deletion sentinel,
|
|
721
|
-
not a storable value — `DocumentValue` doesn't include `null`,
|
|
722
|
-
|
|
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`.
|
|
723
727
|
That's why this recipe uses `.optional()` and not `.nullable()`.
|
|
724
728
|
|
|
725
729
|
## Pointers
|
|
@@ -1,13 +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
|
-
|
|
9
|
-
|
|
10
|
-
|
|
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.
|
|
11
15
|
|
|
12
16
|
## What you got
|
|
13
17
|
|
|
@@ -103,11 +107,13 @@ follow `AGENTS.md` → "Going to production":
|
|
|
103
107
|
|
|
104
108
|
## When to graduate
|
|
105
109
|
|
|
106
|
-
baerly is sized for the small-to-medium operating point. Past
|
|
107
|
-
~30 writes/min/collection
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
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.
|
|
111
117
|
|
|
112
118
|
## Pointers
|
|
113
119
|
|
|
@@ -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": "^
|
|
21
|
+
"@cloudflare/vite-plugin": "^1.42.4",
|
|
22
|
+
"@cloudflare/workers-types": "^4.20260630.1",
|
|
23
|
+
"@types/node": "^26.0.1",
|
|
24
24
|
"@types/react": "^19.2.17",
|
|
25
|
-
"@types/react-dom": "^19.
|
|
26
|
-
"@vitejs/plugin-react": "^6.0.
|
|
27
|
-
"happy-dom": "^20.10.
|
|
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,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
|