@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.
Files changed (29) hide show
  1. package/LICENSE +202 -0
  2. package/dist/index.js +54 -28
  3. package/dist/index.js.map +1 -1
  4. package/dist/templates/addons/docker/Dockerfile +8 -2
  5. package/dist/templates/minimal-cloudflare/AGENTS.md +140 -101
  6. package/dist/templates/minimal-cloudflare/README.md +43 -33
  7. package/dist/templates/minimal-cloudflare/package.json +7 -7
  8. package/dist/templates/minimal-cloudflare/wrangler.jsonc +1 -1
  9. package/dist/templates/minimal-node/.baerly/scaffold.json +1 -1
  10. package/dist/templates/minimal-node/.env.example +12 -5
  11. package/dist/templates/minimal-node/AGENTS.md +135 -107
  12. package/dist/templates/minimal-node/README.md +77 -44
  13. package/dist/templates/minimal-node/package.json +5 -5
  14. package/dist/templates/minimal-node/src/server/index.ts +22 -30
  15. package/dist/templates/minimal-node/src/server/resolve-storage.ts +18 -0
  16. package/dist/templates/minimal-node/vite.config.ts +0 -2
  17. package/dist/templates/react-cloudflare/AGENTS.md +77 -52
  18. package/dist/templates/react-cloudflare/README.md +25 -16
  19. package/dist/templates/react-cloudflare/index.html +1 -1
  20. package/dist/templates/react-cloudflare/package.json +12 -12
  21. package/dist/templates/react-cloudflare/wrangler.jsonc +1 -1
  22. package/dist/templates/react-node/.env.example +12 -5
  23. package/dist/templates/react-node/AGENTS.md +117 -81
  24. package/dist/templates/react-node/README.md +67 -37
  25. package/dist/templates/react-node/package.json +10 -10
  26. package/dist/templates/react-node/src/server/index.ts +18 -29
  27. package/dist/templates/react-node/src/server/resolve-storage.ts +18 -0
  28. package/dist/templates/react-node/vite.config.ts +0 -2
  29. package/package.json +16 -11
@@ -1,14 +1,24 @@
1
1
  # react-node
2
2
 
3
- A baerly app scaffolded with `@gusto/create-baerly-storage` for the **Node** target —
4
- any host that runs `node server.js` (Railway, Render, Fly without
5
- Docker, Heroku, a VM, a container scheduler, your laptop). Uses
6
- `@gusto/baerly-storage/node` against an S3-compatible bucket (AWS S3, R2 via
7
- S3-compat, Minio, etc.). Ships `auth: "none"` so the day-1 happy
8
- path works with zero env vars, plus a React + Vite SPA and a
9
- one-collection `notes` schema you extend; flip to a shared secret
10
- or wire `bearerJwt` against your OIDC IdP before deploy — see
11
- "Production auth" below.
3
+ A baerly-storage app scaffolded with `@gusto/create-baerly-storage` for
4
+ the **Node** target — any host that runs `node server.js` (Railway,
5
+ Render, Fly without Docker, Heroku, a VM, a container scheduler, your
6
+ laptop). Runs zero-config on local filesystem storage out of the box;
7
+ promote to an S3-compatible bucket via `@gusto/baerly-storage/node` for
8
+ production. AWS S3 and Cloudflare R2 are the production-supported
9
+ targets; MinIO is the local conformance target, and other endpoints
10
+ require `baerly doctor --bucket` plus owner validation. Ships
11
+ `auth: "none"` so the day-1 happy path works with zero env vars, plus a
12
+ React + Vite SPA and a one-collection `notes` schema you extend; flip
13
+ to a shared secret or wire `bearerJwt` against your OIDC IdP before
14
+ deploy — see "Production auth" below.
15
+
16
+ **In production, the S3-compatible bucket is the durable state**
17
+ (locally, a `./.baerly-data` directory stands in). The Node process is
18
+ trusted app code with bucket credentials; it applies the
19
+ baerly-storage protocol, but it is not a database server. No daemon,
20
+ lock table, scheduler, or idle database bill; maintenance is automatic
21
+ and write-triggered.
12
22
 
13
23
  To ship a production Dockerfile alongside, scaffold with
14
24
  `--with=docker` — the add-on writes a multi-stage distroless Dockerfile,
@@ -24,13 +34,13 @@ react-node/
24
34
  ├── tsconfig.server.json # Node server TS project (src/server)
25
35
  ├── vite.config.ts # Vite + @vitejs/plugin-react + baerlyDev()
26
36
  ├── index.html # SPA shell — Vite's entry point
27
- ├── .env.example # storage creds, verifier, observability
37
+ ├── .env.example # storage selection (local-fs default) + PORT
28
38
  ├── baerly.config.ts # app, tenant, target, NoteSchema, `Note` type
29
39
  ├── AGENTS.md # deeper guide: hooks, schema, auth, deploy
30
40
  ├── CLAUDE.md # same content (Claude Code reads this)
31
41
  ├── src/
32
42
  │ ├── server/
33
- │ │ └── index.ts # baerlyNode({ app, storage, verifier, webRoot, maintenance? }).listen(PORT)
43
+ │ │ └── index.ts # baerlyNode({ config, storage, verifier, webRoot }).listen(PORT)
34
44
  │ └── web/
35
45
  │ ├── main.tsx # React entry
36
46
  │ ├── App.tsx # Provider + new-note form (useMutation)
@@ -46,35 +56,49 @@ pnpm install
46
56
  pnpm dev
47
57
  ```
48
58
 
49
-
50
59
  `pnpm dev` runs `vite`. `baerlyDev()` from `@gusto/baerly-storage/dev/vite`
51
60
  mounts the Node HTTP listener as Connect middleware on the same Vite
52
61
  process that serves the SPA, so `GET /` hits the SPA on
53
- `http://localhost:5173/` and anything baerly handles (e.g.
54
- `GET /v1/healthz`, `POST /v1/notes`) is served on the same origin —
62
+ `http://localhost:5173/` and anything baerly-storage handles (e.g.
63
+ `GET /v1/healthz`, `POST /v1/c/notes`) is served on the same origin —
55
64
  one process, one port, SPA + HMR + `/v1/*` in one command. Storage is
56
65
  `LocalFsStorage` rooted at `.baerly-data/`, so first-touch needs no
57
66
  S3 creds, no JWKS, and no second process.
58
67
 
59
68
  Open <http://localhost:5173>. Type a note, hit "Add note." Open a
60
69
  second tab — inserts, edits, and deletes in one tab appear in the
61
- other over the `/v1/since` long-poll.
70
+ other over the `/v1/since?collection=notes&cursor=...` long-poll.
62
71
 
63
- For production-shaped local runs (S3 and the bundled SPA served
64
- from `dist/client/`):
72
+ For production-shaped local runs (the bundled SPA served from
73
+ `dist/client/`):
65
74
 
66
75
  ```sh
67
76
  pnpm build
77
+ pnpm start
78
+ ```
79
+
80
+ `pnpm start` defaults to `localFsStorage()` (persists to
81
+ `./.baerly-data`, zero credentials, single-node only). To opt into
82
+ S3 or R2:
83
+
84
+ ```sh
85
+ # AWS S3
68
86
  BUCKET=... AWS_ACCESS_KEY_ID=... AWS_SECRET_ACCESS_KEY=... pnpm start
87
+
88
+ # Cloudflare R2
89
+ R2_ACCOUNT_ID=... BUCKET=... AWS_ACCESS_KEY_ID=... AWS_SECRET_ACCESS_KEY=... pnpm start
69
90
  ```
70
91
 
71
92
  The server reads `BUCKET`, `AWS_ACCESS_KEY_ID`,
72
- `AWS_SECRET_ACCESS_KEY` at startup. The default `auth: "none"`
93
+ `AWS_SECRET_ACCESS_KEY` at startup; when those are absent it falls
94
+ back to `localFsStorage()` for local runs. **In a detected deployment
95
+ (`NODE_ENV=production` or a known PaaS) it refuses to start and requires
96
+ a bucket** — local-fs is local-dev only (single-process, no
97
+ cross-process CAS or crash durability). The default `auth: "none"`
73
98
  posture needs no auth env vars; if you adopt Pattern B / C from
74
99
  "Production auth" below, also set `SHARED_SECRET` (Pattern B) or
75
100
  `JWKS_URL` + `JWT_ISSUER` + `JWT_AUDIENCE` (Pattern C). Optional:
76
- `R2_ACCOUNT_ID` (switches the storage factory from `s3Storage` to
77
- `r2Storage`), `AWS_REGION`, `PORT`, `TENANT`, `WEB_ROOT`.
101
+ `AWS_REGION`, `PORT`.
78
102
 
79
103
  Maintenance (compaction + GC) is automatic and in-band: it runs
80
104
  inline on the rare write that crosses a maintenance trigger — no env
@@ -86,7 +110,7 @@ from `@gusto/baerly-storage`.
86
110
 
87
111
  After `pnpm build`, `http://localhost:8080/` serves the built SPA
88
112
  out of `dist/client/` and `http://localhost:8080/v1/*` is the
89
- baerly HTTP surface — single origin, no CORS.
113
+ baerly-storage HTTP surface — single origin, no CORS.
90
114
 
91
115
  `pnpm typecheck` runs `tsc -b --noEmit` across both project
92
116
  references.
@@ -96,7 +120,12 @@ references.
96
120
  This scaffold runs anywhere `node server.js` runs. The `package.json`
97
121
  exposes `build` (Vite SPA + TS check) and `start`
98
122
  (`node --experimental-strip-types src/server/index.ts`); arrange your
99
- host to run `pnpm install && pnpm build`, then `pnpm start`.
123
+ host to run `pnpm install && pnpm build`, then `pnpm start` with the
124
+ storage/auth env vars exported or configured in the process manager.
125
+ A deployment must set a durable bucket (`BUCKET` + `AWS_*`, or
126
+ `R2_ACCOUNT_ID` + creds); the server fails loud rather than running on
127
+ local-fs, which is local-dev only. Self-hosting without a cloud bucket,
128
+ run MinIO on the box or use SQLite + Litestream.
100
129
 
101
130
  Concrete shapes:
102
131
 
@@ -105,10 +134,12 @@ Concrete shapes:
105
134
  repo, set env vars from `.env.example` in the dashboard, deploy.
106
135
  The platform's buildpack detects Node and runs the root scripts.
107
136
  - **VM / bare-metal**: clone, install Node 24+, copy `.env.example`
108
- to `.env`, run `pnpm install && pnpm build && pnpm start` under
109
- your process manager of choice (systemd, pm2, etc.).
137
+ to `.env` as a template, then export those values or configure them
138
+ in your process manager (Node does not load `.env` automatically).
139
+ Run `pnpm install && pnpm build && pnpm start` under systemd, pm2,
140
+ or your process manager of choice.
110
141
  - **Container** (Docker, k8s, ECS, Fly Machines with a Dockerfile):
111
- scaffold with `pnpm create @gusto/baerly-storage@latest --target=node --with=docker` to add
142
+ scaffold with `pnpm create @gusto/baerly-storage@latest my-app --target=node --with=docker` to add
112
143
  a production Dockerfile, `.dockerignore`, and `healthcheck.js`
113
144
  alongside this shape, then `docker build .`.
114
145
 
@@ -137,7 +168,7 @@ the `NoteSchema` still validates writes server-side. Before deploy,
137
168
  follow `AGENTS.md` → "Going to production":
138
169
 
139
170
  - **Pattern B — `auth: "shared-secret"`.** Single-tenant
140
- server-to-server callers (CI, cron, internal services). Flip
171
+ server-to-server callers (CI and internal services). Flip
141
172
  `auth` in `baerly.config.ts` and put `SHARED_SECRET` in
142
173
  `process.env` (your PaaS / secret manager).
143
174
  - **Pattern C — JWKS-backed JWT (recommended for multi-tenant).**
@@ -149,17 +180,16 @@ follow `AGENTS.md` → "Going to production":
149
180
 
150
181
  ## When to graduate
151
182
 
152
- baerly is designed for the small-to-medium operating point. Past these
153
- thresholds, S3 list-prefix latency and per-class operation pricing
154
- start to dominate, and you're better off on a real database:
183
+ baerly-storage is designed for the small-to-medium operating point.
184
+ Past these thresholds, S3 list-prefix latency and per-class operation
185
+ pricing starts to dominate, and you've outgrown the workload envelope — move to a database service:
155
186
 
156
- - **~30 writes / minute / collection**
157
- - **~10 GB / tenant**
158
- - **~100 collections / tenant**
187
+ - **~30 writes / minute / collection** — per-collection throughput estimate (CAS-livelock model)
188
+ - **>10 GB / tenant** — R2 free-tier storage cost line (a billing signal, not a protocol ceiling)
189
+ - **~100 collections / tenant** — soft fan-out guideline (linear cost, bench-grounded; nothing enforces it)
159
190
 
160
- When you cross the soft ceiling, graduation is mechanical:
161
- `baerly export --target=postgres` walks your log entries (already
162
- Postgres-logical-replication-shaped) into a real DB. If your
191
+ When you cross these signals, graduation is mechanical:
192
+ `baerly export --target=postgres` walks your log entries (already Debezium-style CDC change events) into a database service. If your
163
193
  deploy target is Cloudflare Workers and you'll accept Cloudflare
164
194
  lock-in, [D1](https://developers.cloudflare.com/d1/) is cheaper
165
195
  per-write at M-size and is a natural next step. If you're on
@@ -167,12 +197,12 @@ AWS, on-prem, or want your data portable, managed Postgres is
167
197
  the typical destination. Either way — graduation is a Baerly win,
168
198
  not a churn event.
169
199
 
170
- **Export to a real database** (swap `--target=` for `sqlite`,
200
+ **Export to a database service** (swap `--target=` for `sqlite`,
171
201
  `postgres`, or `d1`):
172
202
 
173
203
  ```sh
174
204
  baerly export --target=postgres \
175
- --bucket=react-node --app=react-node --tenant=<your-tenant> \
205
+ --bucket=s3://react-node --app=react-node --tenant=<your-tenant> \
176
206
  --collection=<collection-name> --output=./out.sql
177
207
  ```
178
208
 
@@ -13,20 +13,20 @@
13
13
  },
14
14
  "dependencies": {
15
15
  "@gusto/baerly-storage": "workspace:*",
16
- "aws4fetch": "^1.0.20",
17
- "react": "^19.0.0",
18
- "react-dom": "^19.0.0",
16
+ "aws4fetch": "1.0.20",
17
+ "react": "^19.2.7",
18
+ "react-dom": "^19.2.7",
19
19
  "zod": "^4.4.3"
20
20
  },
21
21
  "devDependencies": {
22
- "@types/node": "^24.0.0",
23
- "@types/react": "^19.2.15",
24
- "@types/react-dom": "^19.0.0",
25
- "@vitejs/plugin-react": "^6.0.2",
26
- "happy-dom": "^20.9.0",
22
+ "@types/node": "^26.0.1",
23
+ "@types/react": "^19.2.17",
24
+ "@types/react-dom": "^19.2.3",
25
+ "@vitejs/plugin-react": "^6.0.3",
26
+ "happy-dom": "^20.10.6",
27
27
  "typescript": "^6.0.3",
28
- "vite": "^8.0.14",
29
- "vitest": "^4.1.7"
28
+ "vite": "^8.1.2",
29
+ "vitest": "^4.1.9"
30
30
  },
31
31
  "packageManager": "pnpm@11.1.2"
32
32
  }
@@ -7,39 +7,28 @@
7
7
  * every write. See AGENTS.md "Going to production" for the recipe
8
8
  * to flip `auth` or wire a custom verifier.
9
9
  *
10
- * Storage: AWS S3 by default; set `R2_ACCOUNT_ID` to switch to
11
- * Cloudflare R2 via the S3-compat endpoint.
10
+ * Storage: zero-config `LocalFsStorage` rooted at ./.baerly-data for
11
+ * local development — no credentials. Set `BUCKET` (+ AWS creds) for AWS
12
+ * S3, or `R2_ACCOUNT_ID` (+ creds) for Cloudflare R2. In a detected
13
+ * deployment (NODE_ENV=production or a known PaaS) the server REFUSES to
14
+ * start without a bucket — local-fs is a local-dev convenience only
15
+ * (single-process, no cross-process CAS, no crash durability), never a
16
+ * production store — so a missing/typo'd bucket fails loud instead of
17
+ * silently losing data.
12
18
  */
13
- import { baerlyNode, r2Storage, s3Storage } from "@gusto/baerly-storage/node";
14
- import type { Storage } from "@gusto/baerly-storage";
19
+ import { baerlyNode } from "@gusto/baerly-storage/node";
15
20
  import config from "../../baerly.config.ts";
21
+ import { resolveStorage } from "./resolve-storage.ts";
16
22
 
17
- const reqEnv = (name: string): string => {
18
- const v = process.env[name];
19
- if (v === undefined || v === "") {
20
- throw new Error(`Missing required env var: ${name}`);
21
- }
22
- return v;
23
- };
23
+ // Pick the storage backend from the environment (R2 / S3 / local-fs),
24
+ // failing loud if a deployment has no bucket. The policy lives in
25
+ // `./resolve-storage.ts` — edit it there to change how your app maps
26
+ // env vars to storage.
27
+ const { storage, label: storageLabel } = resolveStorage();
24
28
 
25
- const storage: Storage =
26
- process.env["R2_ACCOUNT_ID"] !== undefined
27
- ? r2Storage({
28
- accountId: reqEnv("R2_ACCOUNT_ID"),
29
- bucket: reqEnv("BUCKET"),
30
- credentials: {
31
- accessKeyId: reqEnv("AWS_ACCESS_KEY_ID"),
32
- secretAccessKey: reqEnv("AWS_SECRET_ACCESS_KEY"),
33
- },
34
- })
35
- : s3Storage({
36
- region: process.env["AWS_REGION"] ?? "us-east-1",
37
- bucket: reqEnv("BUCKET"),
38
- credentials: {
39
- accessKeyId: reqEnv("AWS_ACCESS_KEY_ID"),
40
- secretAccessKey: reqEnv("AWS_SECRET_ACCESS_KEY"),
41
- },
42
- });
29
+ // Announce the effective backend so the chosen store (and any surprise
30
+ // local-fs fallback) is visible in the deploy logs, not a surprise.
31
+ console.log(`[baerly] storage=${storageLabel}`);
43
32
 
44
33
  const PORT = Number(process.env["PORT"] ?? 8080);
45
34
 
@@ -0,0 +1,18 @@
1
+ /**
2
+ * Storage selection is your app's policy, surfaced here as an editable
3
+ * seam. The default is the library's `resolveStorageFromEnv`, in priority
4
+ * order:
5
+ * 1. R2_ACCOUNT_ID set → Cloudflare R2 (S3-compat endpoint)
6
+ * 2. BUCKET set → AWS S3
7
+ * 3. neither, local dev → LocalFsStorage (zero credentials)
8
+ * 4. neither, deployed → throw. It never silently falls back to a
9
+ * non-durable store (local-fs or in-memory) in a deployment — that
10
+ * is the failure mode that loses data in production.
11
+ *
12
+ * Replace this re-export with your own `(env) => ResolvedStorage` if your
13
+ * policy differs (a custom endpoint, MinIO, GCS, …). The resolver is
14
+ * exported and tested in `@gusto/baerly-storage/node` so every app shares
15
+ * one safe default instead of hand-rolling one.
16
+ */
17
+ export { resolveStorageFromEnv as resolveStorage } from "@gusto/baerly-storage/node";
18
+ export type { ResolvedStorage } from "@gusto/baerly-storage/node";
@@ -1,4 +1,3 @@
1
- import { resolve } from "node:path";
2
1
  import { defineConfig } from "vite";
3
2
  import react from "@vitejs/plugin-react";
4
3
  import { baerlyDev } from "@gusto/baerly-storage/dev/vite";
@@ -11,7 +10,6 @@ export default defineConfig({
11
10
  react(),
12
11
  baerlyDev({
13
12
  config,
14
- dataDir: resolve(import.meta.dirname, ".baerly-data"),
15
13
  }),
16
14
  ],
17
15
  });
package/package.json CHANGED
@@ -1,12 +1,23 @@
1
1
  {
2
2
  "name": "@gusto/create-baerly-storage",
3
- "version": "0.2.0",
4
- "description": "Scaffold a new baerly-storage app. Run via `pnpm create @gusto/baerly-storage@latest -- my-app --target=cloudflare`.",
3
+ "version": "0.4.0",
4
+ "description": "Create an app with a document database on S3 or Cloudflare R2 — TypeScript scaffold for Workers and Node",
5
+ "keywords": [
6
+ "boilerplate",
7
+ "cloudflare-workers",
8
+ "document-database",
9
+ "r2",
10
+ "s3",
11
+ "scaffold",
12
+ "serverless",
13
+ "starter",
14
+ "typescript"
15
+ ],
5
16
  "homepage": "https://github.com/Gusto/baerly-storage#readme",
6
17
  "bugs": {
7
18
  "url": "https://github.com/Gusto/baerly-storage/issues"
8
19
  },
9
- "license": "MIT",
20
+ "license": "Apache-2.0",
10
21
  "author": "Eric Baer",
11
22
  "repository": {
12
23
  "type": "git",
@@ -20,17 +31,11 @@
20
31
  "dist"
21
32
  ],
22
33
  "type": "module",
23
- "exports": {
24
- ".": {
25
- "types": "./src/index.ts",
26
- "import": "./src/index.ts"
27
- }
28
- },
29
34
  "publishConfig": {
30
- "access": "restricted"
35
+ "access": "public"
31
36
  },
32
37
  "dependencies": {
33
- "@clack/prompts": "^1.4.0",
38
+ "@clack/prompts": "^1.6.0",
34
39
  "citty": "^0.2.2",
35
40
  "picocolors": "^1.1.1"
36
41
  },