@clubedge/create-clubedge-app 0.38.0 → 0.39.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 (128) hide show
  1. package/CHANGELOG.md +15 -0
  2. package/README.md +11 -10
  3. package/package.json +3 -3
  4. package/template/.github/workflows/ci.yml +35 -1
  5. package/template/README.md +19 -8
  6. package/template/SETUP.md +51 -16
  7. package/template/apps/api/.env.example +108 -0
  8. package/template/apps/api/build.mjs +3 -2
  9. package/template/apps/api/clubedge.stack.json +87 -1
  10. package/template/apps/api/package.json +20 -2
  11. package/template/apps/api/scripts/check-env.ts +35 -7
  12. package/template/apps/api/scripts/check-services.ts +204 -9
  13. package/template/apps/api/src/app.test.ts +39 -1
  14. package/template/apps/api/src/app.ts +66 -7
  15. package/template/apps/api/src/config/plans.ts +16 -0
  16. package/template/apps/api/src/env/production.test.ts +88 -0
  17. package/template/apps/api/src/env/production.ts +121 -0
  18. package/template/apps/api/src/http.test.ts +38 -0
  19. package/template/apps/api/src/http.ts +30 -0
  20. package/template/apps/api/src/index.ts +22 -1
  21. package/template/apps/api/src/jobs/index.ts +31 -0
  22. package/template/apps/api/src/jobs/sample.ts +10 -0
  23. package/template/apps/api/src/rate-limit.test.ts +43 -0
  24. package/template/apps/api/src/rate-limit.ts +51 -0
  25. package/template/apps/api/src/routes/account.test.ts +141 -0
  26. package/template/apps/api/src/routes/account.ts +135 -0
  27. package/template/apps/api/src/routes/billing.test.ts +208 -0
  28. package/template/apps/api/src/routes/billing.ts +130 -0
  29. package/template/apps/api/src/routes/client-errors.test.ts +90 -0
  30. package/template/apps/api/src/routes/client-errors.ts +43 -0
  31. package/template/apps/api/src/routes/inngest.test.ts +37 -0
  32. package/template/apps/api/src/routes/inngest.ts +14 -0
  33. package/template/apps/api/src/routes/jobs-run.test.ts +39 -0
  34. package/template/apps/api/src/routes/jobs-run.ts +25 -0
  35. package/template/apps/api/src/routes/jobs.test.ts +85 -0
  36. package/template/apps/api/src/routes/jobs.ts +68 -0
  37. package/template/apps/api/src/server/account.ts +38 -0
  38. package/template/apps/api/src/server/auth.ts +18 -0
  39. package/template/apps/api/src/server/cache.test.ts +65 -0
  40. package/template/apps/api/src/server/cache.ts +57 -0
  41. package/template/apps/api/src/server/email.ts +39 -0
  42. package/template/apps/api/src/server/index.ts +13 -0
  43. package/template/apps/api/src/server/jobs.test.ts +28 -0
  44. package/template/apps/api/src/server/jobs.ts +82 -0
  45. package/template/apps/api/src/server/observability.test.ts +23 -0
  46. package/template/apps/api/src/server/observability.ts +48 -0
  47. package/template/apps/api/src/server/payments.ts +76 -0
  48. package/template/apps/api/src/server/storage.ts +64 -0
  49. package/template/apps/api/src/server/users.ts +8 -0
  50. package/template/apps/api/src/server/variants/auth.appwrite.ts +43 -0
  51. package/template/apps/api/src/server/variants/auth.better-auth.ts +32 -0
  52. package/template/apps/api/src/server/variants/auth.firebase.ts +53 -0
  53. package/template/apps/api/src/server/variants/auth.supabase.ts +31 -1
  54. package/template/apps/api/src/server/variants/cache.memory.ts +25 -0
  55. package/template/apps/api/src/server/variants/email.resend.ts +39 -0
  56. package/template/apps/api/src/server/variants/jobs.bullmq.ts +77 -0
  57. package/template/apps/api/src/server/variants/jobs.inngest.ts +96 -0
  58. package/template/apps/api/src/server/variants/observability.sentry.ts +65 -0
  59. package/template/apps/api/src/server/variants/storage.supabase.ts +59 -0
  60. package/template/apps/api/src/tracing.ts +12 -0
  61. package/template/apps/api-fastapi/package.json +1 -1
  62. package/template/apps/api-fastapi/pyproject.toml +1 -1
  63. package/template/apps/api-fastapi/uv.lock +1 -1
  64. package/template/apps/start/package.json +1 -1
  65. package/template/apps/vite/.env.example +27 -3
  66. package/template/apps/vite/auth.server.mjs +86 -30
  67. package/template/apps/vite/clubedge.stack.json +39 -0
  68. package/template/apps/vite/package.json +7 -2
  69. package/template/apps/vite/server.mjs +22 -5
  70. package/template/apps/vite/src/components/billing/billing-card.tsx +143 -0
  71. package/template/apps/vite/src/components/dashboard/variants/account-button.supabase.tsx +32 -21
  72. package/template/apps/vite/src/components/error-reporting.tsx +52 -0
  73. package/template/apps/vite/src/components/jobs/jobs-card.tsx +95 -0
  74. package/template/apps/vite/src/components/route-error.tsx +12 -0
  75. package/template/apps/vite/src/components/variants/error-reporting.sentry.tsx +34 -0
  76. package/template/apps/vite/src/lib/auth-client.ts +18 -0
  77. package/template/apps/vite/src/main.tsx +6 -0
  78. package/template/apps/vite/src/routes/dashboard.tsx +41 -0
  79. package/template/apps/vite/src/routes/login.tsx +21 -14
  80. package/template/apps/vite/src/routes/settings.tsx +383 -0
  81. package/template/apps/vite/src/variants/auth.appwrite.ts +22 -2
  82. package/template/apps/vite/src/variants/auth.better-auth.ts +31 -2
  83. package/template/apps/vite/src/variants/auth.firebase.ts +39 -2
  84. package/template/apps/vite/src/variants/auth.supabase.ts +20 -1
  85. package/template/apps/vite/src/variants/router.supabase.tsx +8 -0
  86. package/template/apps/web/package.json +1 -1
  87. package/template/clubedge.template.json +2 -1
  88. package/template/package.json +3 -2
  89. package/template/packages/auth/package.json +1 -1
  90. package/template/packages/auth-appwrite/package.json +1 -1
  91. package/template/packages/auth-better-auth/package.json +1 -1
  92. package/template/packages/auth-firebase/package.json +1 -1
  93. package/template/packages/auth-supabase/package.json +1 -1
  94. package/template/packages/auth-supabase/src/index.test.ts +25 -3
  95. package/template/packages/auth-supabase/src/index.ts +12 -0
  96. package/template/packages/cache/package.json +1 -1
  97. package/template/packages/cache-redis/package.json +1 -1
  98. package/template/packages/contract/openapi.yaml +633 -0
  99. package/template/packages/contract/package.json +1 -1
  100. package/template/packages/contract/src/conformance.ts +268 -4
  101. package/template/packages/contract/src/index.ts +12 -0
  102. package/template/packages/contract/src/remote.test.ts +24 -0
  103. package/template/packages/contract/src/schema.test.ts +59 -2
  104. package/template/packages/contract/src/schema.ts +824 -1
  105. package/template/packages/core/package.json +1 -1
  106. package/template/packages/db/package.json +1 -1
  107. package/template/packages/email/package.json +1 -1
  108. package/template/packages/email-resend/package.json +1 -1
  109. package/template/packages/email-smtp/package.json +1 -1
  110. package/template/packages/jobs/package.json +1 -1
  111. package/template/packages/jobs-bullmq/package.json +1 -1
  112. package/template/packages/jobs-inngest/package.json +1 -1
  113. package/template/packages/jobs-inngest/src/index.test.ts +26 -0
  114. package/template/packages/jobs-inngest/src/index.ts +7 -1
  115. package/template/packages/jobs-pg-boss/package.json +1 -1
  116. package/template/packages/local-db/package.json +1 -1
  117. package/template/packages/observability/package.json +1 -1
  118. package/template/packages/observability-otel/package.json +1 -1
  119. package/template/packages/observability-sentry/package.json +1 -1
  120. package/template/packages/payments/package.json +1 -1
  121. package/template/packages/payments-stripe/package.json +1 -1
  122. package/template/packages/storage/package.json +1 -1
  123. package/template/packages/storage-s3/package.json +1 -1
  124. package/template/packages/storage-supabase/package.json +1 -1
  125. package/template/packages/ui/package.json +1 -1
  126. package/template/playwright.config.ts +2 -1
  127. package/template/pnpm-lock.yaml +75 -5
  128. package/template.lock.json +46 -2
package/CHANGELOG.md CHANGED
@@ -2,6 +2,21 @@
2
2
 
3
3
  All notable changes to `create-clubedge-app` are documented here.
4
4
 
5
+ ## 0.39.0
6
+
7
+ - **Every module on React + Vite with Hono**: default to Starter `v0.25.0` (#118). `--framework vite --api hono` now offers every module option the full-stack apps have, each running in the API with the matching UI in the frontend:
8
+ - `--storage s3` (or a local folder with `--infra local`) and `--storage supabase`.
9
+ - `--cache redis`, for the rate limits and cache.
10
+ - `--email smtp` and `--email resend`; Better Auth's emails in the frontend's server use them too.
11
+ - `--observability otel` and `--observability sentry`, with browser error reporting.
12
+ - `--payments stripe`: the billing card, Checkout, the customer portal, and webhooks through the frontend.
13
+ - `--jobs pg-boss`, `--jobs bullmq`, and `--jobs inngest`, with the worker inside the API and a jobs card on the dashboard.
14
+ - New Vite + Hono projects get the same defaults as the full-stack apps: S3 storage, Redis cache, and SMTP email.
15
+ - `deploy` needs no change: Railway and Docker Compose already send each variable to the service that reads it.
16
+ - **Account settings on React + Vite**: projects with authentication get the settings page (display name, password change, account deletion). With FastAPI it offers the password change.
17
+ - FastAPI is unchanged: the CLI still refuses the module options it doesn't implement, with the message that names them.
18
+ - Generated React + Vite projects' own CI builds and checks the API's image too.
19
+
5
20
  ## 0.38.0
6
21
 
7
22
  - **Security: default to Starter `v0.24.2`** (#116). It updates Next.js to 16.4.3: 16.0.0 to 16.4.0 have two critical unauthenticated remote code execution advisories and a high denial of service ([GHSA-p3m5-59mp-jv5r](https://github.com/advisories/GHSA-p3m5-59mp-jv5r) and related). It also updates Zod to 4.6.7 ([GHSA-mrhx-c7xc-m3w5](https://github.com/advisories/GHSA-mrhx-c7xc-m3w5)). **Every Next.js project from an earlier Starter should run `pnpm clubedge upgrade`**, or raise `next` to `^16.4.3` in `apps/web/package.json` and run `pnpm install`. The Starter release also:
package/README.md CHANGED
@@ -207,7 +207,7 @@ pnpm dlx @clubedge/create-clubedge-app my-app --yes --no-git --framework tanstac
207
207
  pnpm dlx @clubedge/create-clubedge-app my-app --ref main
208
208
 
209
209
  # Reproduce a specific Starter release or commit
210
- pnpm dlx @clubedge/create-clubedge-app my-app --ref v0.24.2
210
+ pnpm dlx @clubedge/create-clubedge-app my-app --ref v0.25.0
211
211
  pnpm dlx @clubedge/create-clubedge-app my-app --ref <commit-sha>
212
212
 
213
213
  # Test local Starter changes before releasing them
@@ -226,7 +226,7 @@ pnpm clubedge add email resend payments stripe # several modules as
226
226
  pnpm clubedge remove storage payments
227
227
  pnpm dlx @clubedge/create-clubedge-app add infra local --dry-run
228
228
  pnpm dlx @clubedge/create-clubedge-app@latest upgrade # to the newest CLI's Starter release
229
- pnpm dlx @clubedge/create-clubedge-app upgrade --ref v0.24.2 # or a specific tag, branch, or commit
229
+ pnpm dlx @clubedge/create-clubedge-app upgrade --ref v0.25.0 # or a specific tag, branch, or commit
230
230
  ```
231
231
 
232
232
  The CLI renders the project twice, from the Starter commit and modules recorded in your `package.json` and from the new state, and merges the difference into your project. The new state has other modules for `add` and `remove`, and the newer Starter with the same modules for `upgrade`. Modules a newer Starter introduces start as `none` where possible, so an upgrade never adds a service on its own.
@@ -337,27 +337,27 @@ Projects created with `--infra neon` also have `.github/workflows/preview.yml`,
337
337
  Each CLI release is tested against one specific Starter release:
338
338
 
339
339
  ```text
340
- create-clubedge-app v0.38.0
340
+ create-clubedge-app v0.39.0
341
341
  |
342
342
  v
343
- Clubedge Starter v0.24.2
344
- commit 4450d2f00a89f1a3929a5c9d2c1541e0d65df891
343
+ Clubedge Starter v0.25.0
344
+ commit 17f4e82dca42884e7bfc3c66991110d00c7428a8
345
345
  ```
346
346
 
347
347
  The current relationship is:
348
348
 
349
349
  | CLI release | Default Starter release | Meaning |
350
350
  | --- | --- | --- |
351
- | `create-clubedge-app@0.38.0` | `clubedge-starter@v0.24.2` | The CLI's required, tested default |
351
+ | `create-clubedge-app@0.39.0` | `clubedge-starter@v0.25.0` | The CLI's required, tested default |
352
352
 
353
353
  This means the same CLI version always scaffolds the same Starter revision by default. The CLI does not silently follow Starter `main`.
354
354
 
355
- The `v0.24.2` tag is expected to resolve to commit
356
- `4450d2f00a89f1a3929a5c9d2c1541e0d65df891`. The CLI verifies this before
355
+ The `v0.25.0` tag is expected to resolve to commit
356
+ `17f4e82dca42884e7bfc3c66991110d00c7428a8`. The CLI verifies this before
357
357
  scaffolding with the default reference and fails rather than silently using a
358
358
  moved tag.
359
359
 
360
- When the Starter changes, its maintainers first publish a new versioned release, such as `v0.24.2`. The CLI is then updated to use that release, all generated-project checks must pass, and a new CLI version is published. This keeps Starter and CLI releases independently versioned while preserving a tested compatibility relationship.
360
+ When the Starter changes, its maintainers first publish a new versioned release, such as `v0.25.0`. The CLI is then updated to use that release, all generated-project checks must pass, and a new CLI version is published. This keeps Starter and CLI releases independently versioned while preserving a tested compatibility relationship.
361
361
 
362
362
  Every generated project records its CLI version, Starter repository, Starter ref, Starter commit, framework, and modules in `package.json` and `README.md`.
363
363
 
@@ -412,7 +412,7 @@ CI packs the CLI with `npm pack`, scaffolds clean projects from the packed tarba
412
412
  1. Make and validate changes in `clubedge-starter`.
413
413
  2. Run lint, typecheck, unit tests, browser tests, and production build.
414
414
  3. Update the Starter package versions.
415
- 4. Commit `main`, create a release tag such as `v0.24.2`, and publish the Starter release.
415
+ 4. Commit `main`, create a release tag such as `v0.25.0`, and publish the Starter release.
416
416
 
417
417
  ### CLI maintainers
418
418
 
@@ -461,6 +461,7 @@ Each phase ends with a Starter release and a CLI release pinned to it. The full
461
461
  | 0.36.0 | v0.24.1 | Starter v0.24.1: security update of FastAPI's `certifi`; dependency updates |
462
462
  | 0.37.0 | v0.24.1 | An MCP server (capabilities, validate, plan, create) and an agent skill for coding agents |
463
463
  | 0.38.0 | v0.24.2 | Starter v0.24.2: Next.js security update (critical RCE advisories); database URLs, Neon, and deploy variables for a frontend and its API |
464
+ | 0.39.0 | v0.25.0 | Starter v0.25.0: every module on React + Vite with Hono, and account settings on React + Vite |
464
465
 
465
466
  ## Community
466
467
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@clubedge/create-clubedge-app",
3
- "version": "0.38.0",
3
+ "version": "0.39.0",
4
4
  "description": "Create React apps from Clubedge Starter with a CLI or local MCP server.",
5
5
  "type": "module",
6
6
  "packageManager": "pnpm@10.9.0",
@@ -24,8 +24,8 @@
24
24
  },
25
25
  "clubedge": {
26
26
  "starterRepository": "Clubedge/clubedge-starter",
27
- "starterRef": "v0.24.2",
28
- "starterCommit": "4450d2f00a89f1a3929a5c9d2c1541e0d65df891"
27
+ "starterRef": "v0.25.0",
28
+ "starterCommit": "17f4e82dca42884e7bfc3c66991110d00c7428a8"
29
29
  },
30
30
  "license": "Apache-2.0",
31
31
  "repository": {
@@ -97,9 +97,20 @@ jobs:
97
97
  --health-cmd pg_isready --health-interval 5s --health-timeout 5s --health-retries 10
98
98
  steps:
99
99
  - uses: actions/checkout@v7
100
+ # clubedge:if api=none
100
101
  - name: Build the production image
101
102
  # A public URL of its own, to check that it reaches the build.
102
103
  run: docker build --build-arg NEXT_PUBLIC_APP_URL=https://app.ci.invalid --tag app:ci .
104
+ # clubedge:end
105
+ # clubedge:if api!=none
106
+ # The frontend's image, and the API's, which owns the database and carries the migrator.
107
+ # Their own tags: the Starter repository runs every block of this file.
108
+ - name: Build the production images
109
+ run: |
110
+ set -euo pipefail
111
+ docker build --tag web:ci .
112
+ docker build --file apps/api/Dockerfile --tag api:ci .
113
+ # clubedge:end
103
114
  # clubedge:if framework=next
104
115
  - name: Check that the public URL is compiled into the build
105
116
  # Next.js inlines NEXT_PUBLIC_* at build time, server code included; without the build
@@ -110,9 +121,11 @@ jobs:
110
121
  run: |
111
122
  set -euo pipefail
112
123
  for run in 1 2; do
113
- docker run --rm --network host --env DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:5432/app app:ci node /app/migrate.mjs
124
+ docker run --rm --network host --env DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:5432/app app:ci node /app/migrate.mjs # clubedge:only api=none
125
+ docker run --rm --network host --env DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:5432/app api:ci node /app/migrate.mjs # clubedge:only api!=none
114
126
  done
115
127
  PGPASSWORD=postgres psql --host 127.0.0.1 --username postgres --dbname app --command "select count(*) from public.users"
128
+ # clubedge:if api=none
116
129
  - name: Start the image and check health
117
130
  run: |
118
131
  set -euo pipefail
@@ -128,3 +141,24 @@ jobs:
128
141
  done
129
142
  echo "The container did not become healthy."
130
143
  exit 1
144
+ # clubedge:end
145
+ # clubedge:if api!=none
146
+ # On the host's network, like the migrations: the API on port 3001, and the frontend on
147
+ # 3000, which forwards /api to it. Both must answer: the API itself, and through the frontend.
148
+ - name: Start the images and check health through the frontend
149
+ run: |
150
+ set -euo pipefail
151
+ docker run --detach --name api --network host \
152
+ --env DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:5432/app api:ci
153
+ docker run --detach --name web --network host --env API_URL=http://127.0.0.1:3001 web:ci
154
+ trap 'docker logs api; docker logs web; docker rm --force api web' EXIT
155
+ for attempt in $(seq 1 30); do
156
+ if curl --fail --silent http://127.0.0.1:3001/api/health &&
157
+ curl --fail --silent http://127.0.0.1:3000/api/health; then
158
+ exit 0
159
+ fi
160
+ sleep 2
161
+ done
162
+ echo "The containers did not become healthy."
163
+ exit 1
164
+ # clubedge:end
@@ -48,6 +48,8 @@ Every combination in the CI matrix is generated as a real project and runs its f
48
48
 
49
49
  - Next.js App Router with React, TypeScript, Tailwind CSS 4, and shadcn/ui using Base UI primitives. <!-- clubedge:only framework=next -->
50
50
  - TanStack Start with React, TypeScript, Vite, Tailwind CSS 4, and shadcn/ui using Base UI primitives. <!-- clubedge:only framework=tanstack-start -->
51
+ - A React + Vite single-page app with TypeScript, TanStack Router, Tailwind CSS 4, and shadcn/ui using Base UI primitives, and a Hono API in TypeScript in `apps/api`, joined by one OpenAPI contract. <!-- clubedge:only framework=vite && api=hono -->
52
+ - A React + Vite single-page app with TypeScript, TanStack Router, Tailwind CSS 4, and shadcn/ui using Base UI primitives, and a FastAPI API in Python in `apps/api`, joined by one OpenAPI contract. <!-- clubedge:only framework=vite && api=fastapi -->
51
53
  - pnpm workspaces and Turborepo, with the web app in `apps/web` and framework-agnostic packages under `packages/`.
52
54
  - Drizzle ORM and PostgreSQL schema, migrations, and seed commands.
53
55
  - Zod environment validation, security headers, structured errors, and `/api/health`.
@@ -55,13 +57,19 @@ Every combination in the CI matrix is generated as a real project and runs its f
55
57
 
56
58
  **Modules**
57
59
 
58
- - Supabase Auth with server-verified sessions in secure cookies, a protected dashboard, and rate-limited sign-in. <!-- clubedge:only auth=supabase -->
59
- - Better Auth with users and sessions in your own PostgreSQL, secure session cookies, a protected dashboard, and rate-limited sign-in. <!-- clubedge:only auth=better-auth -->
60
- - Firebase Authentication through the app's own pages, with server-side session cookies, a protected dashboard, and rate-limited sign-in; the Auth Emulator in development. <!-- clubedge:only auth=firebase -->
61
- - Appwrite accounts through the app's own pages, on Appwrite Cloud or your own server, with server-side session cookies, a protected dashboard, and rate-limited sign-in. <!-- clubedge:only auth=appwrite -->
60
+ - Supabase Auth with server-verified sessions in secure cookies, a protected dashboard, and rate-limited sign-in. <!-- clubedge:only auth=supabase && framework!=vite -->
61
+ - Better Auth with users and sessions in your own PostgreSQL, secure session cookies, a protected dashboard, and rate-limited sign-in. <!-- clubedge:only auth=better-auth && framework!=vite -->
62
+ - Firebase Authentication through the app's own pages, with server-side session cookies, a protected dashboard, and rate-limited sign-in; the Auth Emulator in development. <!-- clubedge:only auth=firebase && framework!=vite -->
63
+ - Appwrite accounts through the app's own pages, on Appwrite Cloud or your own server, with server-side session cookies, a protected dashboard, and rate-limited sign-in. <!-- clubedge:only auth=appwrite && framework!=vite -->
64
+ - Supabase Auth in the browser, with access tokens that the API verifies on each request, and a protected dashboard. <!-- clubedge:only auth=supabase && framework=vite -->
65
+ - Better Auth in the frontend's server, with users and sessions in your own PostgreSQL, a secure session cookie that the API checks, a protected dashboard, and rate-limited sign-in. <!-- clubedge:only auth=better-auth && framework=vite -->
66
+ - Firebase Authentication in the browser, with ID tokens that the API verifies on each request, and a protected dashboard; the Auth Emulator in development. <!-- clubedge:only auth=firebase && framework=vite -->
67
+ - Appwrite accounts in the browser, on Appwrite Cloud or your own server, with JWTs that the API verifies on each request, and a protected dashboard. <!-- clubedge:only auth=appwrite && framework=vite -->
62
68
  - Password reset by email, and email verification that can be required before sign-in. <!-- clubedge:only auth=better-auth && email!=none -->
63
69
  - Password reset by email, sent by Supabase. <!-- clubedge:only auth=supabase -->
64
- - An account settings page: display name, password change, and account deletion. <!-- clubedge:only auth!=none -->
70
+ - An account settings page: display name, password change, and account deletion. <!-- clubedge:only auth!=none && framework!=vite -->
71
+ - An account settings page: display name, password change, and account deletion. <!-- clubedge:only auth!=none && framework=vite && api=hono -->
72
+ - An account settings page with password change; the FastAPI API does not keep display names or delete accounts yet. <!-- clubedge:only auth!=none && framework=vite && api=fastapi -->
65
73
  - Email over SMTP, for any provider or a local inbox; development prints emails to the server log until SMTP is configured. <!-- clubedge:only email=smtp -->
66
74
  - Email through Resend; development prints emails to the server log until the API key is set. <!-- clubedge:only email=resend -->
67
75
  - S3-compatible storage adapter for AWS S3, Cloudflare R2, and MinIO. <!-- clubedge:only storage=s3 -->
@@ -69,15 +77,18 @@ Every combination in the CI matrix is generated as a real project and runs its f
69
77
  - Fixed-window rate limiter and cache on Redis, falling back to process memory without `REDIS_URL`. <!-- clubedge:only cache=redis -->
70
78
  - Fixed-window rate limiter and cache in process memory, suited to a single server instance. <!-- clubedge:only cache=memory -->
71
79
  - Subscriptions with Stripe Checkout and the customer portal, kept in sync by verified webhooks, behind a provider-neutral payments interface. <!-- clubedge:only payments=stripe -->
72
- - Background jobs with retries and schedules, stored in PostgreSQL by pg-boss and run by a worker inside the app server, behind a provider-neutral jobs interface. <!-- clubedge:only jobs=pg-boss -->
73
- - Background jobs with retries and schedules, stored in Redis by BullMQ and run by a worker inside the app server, behind a provider-neutral jobs interface. <!-- clubedge:only jobs=bullmq -->
80
+ - Background jobs with retries and schedules, stored in PostgreSQL by pg-boss and run by a worker inside the app server, behind a provider-neutral jobs interface. <!-- clubedge:only jobs=pg-boss && api=none -->
81
+ - Background jobs with retries and schedules, stored in PostgreSQL by pg-boss and run by a worker inside the API, behind a provider-neutral jobs interface. <!-- clubedge:only jobs=pg-boss && api!=none -->
82
+ - Background jobs with retries and schedules, stored in Redis by BullMQ and run by a worker inside the app server, behind a provider-neutral jobs interface. <!-- clubedge:only jobs=bullmq && api=none -->
83
+ - Background jobs with retries and schedules, stored in Redis by BullMQ and run by a worker inside the API, behind a provider-neutral jobs interface. <!-- clubedge:only jobs=bullmq && api!=none -->
74
84
  - Background jobs with retries and schedules, run by Inngest, which calls the app for each one, behind a provider-neutral jobs interface. <!-- clubedge:only jobs=inngest -->
75
85
  - Server error reporting and request tracing with OpenTelemetry, to any OTLP collector, behind a provider-neutral observability interface. <!-- clubedge:only observability=otel -->
76
86
  - Server error reporting and request tracing with Sentry, behind a provider-neutral observability interface. <!-- clubedge:only observability=sentry -->
77
87
 
78
88
  **Production**
79
89
 
80
- - A production image that includes its own migrator (`node /app/migrate.mjs`), for running migrations before each release.
90
+ - A production image that includes its own migrator (`node /app/migrate.mjs`), for running migrations before each release. <!-- clubedge:only api=none -->
91
+ - Production images for the frontend, served by Node, and for the API, which includes the migrator (`node /app/migrate.mjs`) for running migrations before each release. <!-- clubedge:only api!=none -->
81
92
  - A manual deploy workflow for the chosen platform, and a readiness endpoint (`/api/ready`) that checks the database.
82
93
  - Deployment to Fly.io with `fly.toml`: migrations run as the release command. <!-- clubedge:only deploy=fly -->
83
94
  - Deployment to Railway with `.railway/railway.ts`: migrations run before each release, and `pnpm clubedge deploy` sets up the project. <!-- clubedge:only deploy=railway -->
package/template/SETUP.md CHANGED
@@ -72,6 +72,7 @@ The app is available at <http://localhost:3000>, the liveness endpoint at <http:
72
72
 
73
73
  Create or select a Supabase project and copy its URL and publishable key from the project's API settings into the Supabase variables above. Authentication runs on the server, which validates every user with Supabase, and the publishable key is all sign-in needs. To let users delete their account from the settings page, also set `SUPABASE_SECRET_KEY` to a secret key from the same settings; it stays on the server, so never give it a `NEXT_PUBLIC_` prefix. <!-- clubedge:only framework=next -->
74
74
  Create or select a Supabase project and copy its URL and publishable key from the project's API settings into the Supabase variables above. Authentication runs on the server, which validates every user with Supabase, and the publishable key is all sign-in needs. To let users delete their account from the settings page, also set `SUPABASE_SECRET_KEY` to a secret key from the same settings; it stays on the server. <!-- clubedge:only framework=tanstack-start -->
75
+ To let users delete their account from the settings page, set `SUPABASE_SECRET_KEY` in `apps/api/.env.local` to a secret key from the project's API settings; only the API uses it. <!-- clubedge:only framework=vite && api=hono -->
75
76
 
76
77
  In Supabase Auth URL configuration, add this redirect URL for local email confirmation and password reset links:
77
78
 
@@ -96,6 +97,7 @@ openssl rand -base64 32
96
97
  Put the result in `BETTER_AUTH_SECRET`. Until it is set, the dashboard stays viewable as a demo and the login page explains what is missing; once it is set, the dashboard redirects signed-out visitors to the login page. Signing in again on another device creates another session row, and signing out deletes it.
97
98
 
98
99
  Sign-up signs the user in immediately; add email verification in `packages/auth-better-auth` if your application needs it. <!-- clubedge:only email=none -->
100
+ The frontend's server still sends password reset and verification emails through Resend when `RESEND_API_KEY` and `EMAIL_FROM` are both set in `apps/web/.env.local`. <!-- clubedge:only email=none && api!=none -->
99
101
  Better Auth sends its emails through the [email module](#email): <!-- clubedge:only email!=none -->
100
102
 
101
103
  - **Password reset:** "Forgot password?" on the login page emails a link to `/reset-password`, valid for one hour and usable once. <!-- clubedge:only email!=none -->
@@ -245,6 +247,8 @@ Use `rediss://` for TLS connections such as Upstash and `redis://` for an unencr
245
247
 
246
248
  Without `REDIS_URL`, the rate limiter and cache use process memory. Memory limits apply per server process, so configure Redis when you run several instances or serverless functions. Never commit a real Redis URL or password.
247
249
 
250
+ The API's rate limits use Redis, so `REDIS_URL` belongs in `apps/api/.env.local` and on the API's service. A limit answers `429` with `Retry-After`; when Redis is unreachable, requests go through and the failure is reported. <!-- clubedge:only api=hono -->
251
+
248
252
  <!-- clubedge:end -->
249
253
  <!-- clubedge:if cache=memory -->
250
254
 
@@ -257,7 +261,9 @@ The rate limiter and cache keep their state in process memory, which suits a sin
257
261
 
258
262
  ## Email
259
263
 
260
- The app sends email through the `EmailProvider` in `apps/web/src/server/email.ts`. Server code imports `email` from `@/server/email` and calls `email.send({ to, subject, text, html })`.
264
+ The app sends email through the `EmailProvider` in `apps/web/src/server/email.ts`. Server code imports `email` from `@/server/email` and calls `email.send({ to, subject, text, html })`. <!-- clubedge:only api=none -->
265
+ The API sends email through the `EmailProvider` in `apps/api/src/server/email.ts`: its code imports `email` from `@/server/email` and calls `email.send({ to, subject, text, html })`. <!-- clubedge:only api!=none -->
266
+ Better Auth runs in the frontend's server (`apps/web/auth.server.mjs`), which sends its emails with the same provider, so set the email variables in both `apps/web/.env.local` and `apps/api/.env.local`. <!-- clubedge:only api!=none && auth=better-auth -->
261
267
 
262
268
  <!-- clubedge:end -->
263
269
  <!-- clubedge:if email=smtp -->
@@ -279,12 +285,14 @@ Without a provider configured, development prints each email to the server log,
279
285
 
280
286
  ## Payments
281
287
 
282
- The plans users can buy are in `apps/web/src/config/plans.ts`, with the app's own ids. The dashboard's billing card offers checkout for each plan, then shows the subscription and opens billing management. Server code reads a user's plan with `getBilling().subscriptionFor(userId)` and `isEntitled` from `@/server/payments`, and the `subscriptions` table keeps it in sync through the provider's webhook at `/api/webhooks/payments`.
288
+ The plans users can buy are in `apps/web/src/config/plans.ts`, with the app's own ids. The dashboard's billing card offers checkout for each plan, then shows the subscription and opens billing management. Server code reads a user's plan with `getBilling().subscriptionFor(userId)` and `isEntitled` from `@/server/payments`, and the `subscriptions` table keeps it in sync through the provider's webhook at `/api/webhooks/payments`. <!-- clubedge:only api=none -->
289
+ The plans users can buy are in `apps/api/src/config/plans.ts`, with the app's own ids, and the API serves them at `/api/billing`. The dashboard's billing card offers checkout for each plan, then shows the subscription and opens billing management; checkout and the portal send the user back to `FRONTEND_URL`. API code reads a user's plan with `getBilling().subscriptionFor(await getUserProfileId(user))` and `isEntitled` from `@/server/payments` and `@/server/users`, and the `subscriptions` table keeps it in sync through the provider's webhook at `/api/webhooks/payments`, which the frontend forwards to the API. <!-- clubedge:only api=hono -->
283
290
 
284
291
  <!-- clubedge:end -->
285
292
  <!-- clubedge:if payments=stripe -->
286
293
 
287
- [Stripe](https://stripe.com) runs checkout and billing management. In test mode:
294
+ [Stripe](https://stripe.com) runs checkout and billing management. In test mode: <!-- clubedge:only api=none -->
295
+ [Stripe](https://stripe.com) runs checkout and billing management. The Stripe variables go in `apps/api/.env.local`. In test mode: <!-- clubedge:only api=hono -->
288
296
 
289
297
  1. Copy the secret key from the dashboard's API keys into `STRIPE_SECRET_KEY`.
290
298
  2. Create a recurring price for each plan and put its id in `STRIPE_PRICE_<PLAN>`, such as `STRIPE_PRICE_PRO`.
@@ -294,23 +302,30 @@ The plans users can buy are in `apps/web/src/config/plans.ts`, with the app's ow
294
302
  stripe listen --forward-to localhost:3000/api/webhooks/payments
295
303
  ```
296
304
 
305
+ The Stripe CLI posts to the frontend on port 3000, which forwards the webhook, body untouched, to the API; the API itself stays private. <!-- clubedge:only api=hono -->
306
+
297
307
  Turn on the customer portal in the dashboard's billing settings, so "Manage billing" works. In production, add a webhook endpoint for `https://<your-domain>/api/webhooks/payments` with the events `checkout.session.completed` and `customer.subscription.created`, `.updated`, `.deleted`, `.paused`, and `.resumed`, and use its signing secret. Every webhook's signature is verified, each event is applied once, and subscription events read the subscription's current state from Stripe, so retried or out-of-order deliveries are safe.
298
308
 
299
309
  <!-- clubedge:end -->
300
310
  <!-- clubedge:if payments!=none -->
301
311
 
302
- Payments go through the provider-neutral `PaymentProvider` interface in `packages/payments`. To use another provider, implement that interface in a new package and return it from `apps/web/src/server/payments.ts`; billing logic, the tables, the routes, and the billing card stay the same.
312
+ Payments go through the provider-neutral `PaymentProvider` interface in `packages/payments`. To use another provider, implement that interface in a new package and return it from `apps/web/src/server/payments.ts`; billing logic, the tables, the routes, and the billing card stay the same. <!-- clubedge:only api=none -->
313
+ Payments go through the provider-neutral `PaymentProvider` interface in `packages/payments`. To use another provider, implement that interface in a new package and return it from `apps/api/src/server/payments.ts`; billing logic, the tables, the routes, and the billing card stay the same. <!-- clubedge:only api=hono -->
303
314
 
304
315
  <!-- clubedge:end -->
305
316
  <!-- clubedge:if jobs!=none -->
306
317
 
307
318
  ## Background jobs
308
319
 
309
- Jobs run outside requests, with retries, in a worker that starts inside the app server: `pnpm dev` and the production server both run it, so there is no separate process to deploy. [pg-boss](https://github.com/timgit/pg-boss) stores them in your PostgreSQL, and creates and upgrades its own tables in the `pgboss` schema when the app starts. <!-- clubedge:only jobs=pg-boss -->
310
- Jobs run outside requests, with retries, in a worker that starts inside the app server: `pnpm dev` and the production server both run it, so there is no separate process to deploy. [BullMQ](https://docs.bullmq.io) stores them in Redis (`REDIS_URL`, Redis 6.2 or newer), which the cache also uses; keep it on a Redis that doesn't evict keys, since jobs are data. <!-- clubedge:only jobs=bullmq -->
311
- [Inngest](https://www.inngest.com) runs the jobs: the app sends an event for each one, and Inngest calls the app's `/api/inngest` to run it, with retries and schedules, so nothing runs between requests and serverless hosts need no cron. In development, start Inngest's Dev Server next to `pnpm dev` with `pnpm jobs:dev`, and open its dashboard at <http://localhost:8288> to see every run; `INNGEST_DEV=1` points the app at it. In production, create an app in Inngest, set `INNGEST_EVENT_KEY` and `INNGEST_SIGNING_KEY`, remove `INNGEST_DEV`, and sync the deployed `/api/inngest` URL in Inngest's dashboard (Inngest's Vercel and Netlify integrations do it on each deploy). <!-- clubedge:only jobs=inngest -->
320
+ Jobs run outside requests, with retries, in a worker that starts inside the app server: `pnpm dev` and the production server both run it, so there is no separate process to deploy. [pg-boss](https://github.com/timgit/pg-boss) stores them in your PostgreSQL, and creates and upgrades its own tables in the `pgboss` schema when the app starts. <!-- clubedge:only jobs=pg-boss && api=none -->
321
+ Jobs run outside requests, with retries, in a worker that starts inside the API: `pnpm dev` and the API's production server both run it, so there is no separate process to deploy. [pg-boss](https://github.com/timgit/pg-boss) stores them in your PostgreSQL, and creates and upgrades its own tables in the `pgboss` schema when the API starts. <!-- clubedge:only jobs=pg-boss && api=hono -->
322
+ Jobs run outside requests, with retries, in a worker that starts inside the app server: `pnpm dev` and the production server both run it, so there is no separate process to deploy. [BullMQ](https://docs.bullmq.io) stores them in Redis (`REDIS_URL`, Redis 6.2 or newer), which the cache also uses; keep it on a Redis that doesn't evict keys, since jobs are data. <!-- clubedge:only jobs=bullmq && api=none -->
323
+ Jobs run outside requests, with retries, in a worker that starts inside the API: `pnpm dev` and the API's production server both run it, so there is no separate process to deploy. [BullMQ](https://docs.bullmq.io) stores them in Redis (`REDIS_URL` in `apps/api/.env.local`, Redis 6.2 or newer), which the cache also uses; keep it on a Redis that doesn't evict keys, since jobs are data. <!-- clubedge:only jobs=bullmq && api=hono -->
324
+ [Inngest](https://www.inngest.com) runs the jobs: the app sends an event for each one, and Inngest calls the app's `/api/inngest` to run it, with retries and schedules, so nothing runs between requests and serverless hosts need no cron. In development, start Inngest's Dev Server next to `pnpm dev` with `pnpm jobs:dev`, and open its dashboard at <http://localhost:8288> to see every run; `INNGEST_DEV=1` points the app at it. In production, create an app in Inngest, set `INNGEST_EVENT_KEY` and `INNGEST_SIGNING_KEY`, remove `INNGEST_DEV`, and sync the deployed `/api/inngest` URL in Inngest's dashboard (Inngest's Vercel and Netlify integrations do it on each deploy). <!-- clubedge:only jobs=inngest && api=none -->
325
+ [Inngest](https://www.inngest.com) runs the jobs: the API sends an event for each one, and Inngest calls `/api/inngest` to run it, with retries and schedules. Inngest reaches the API through the frontend, which forwards `/api/inngest` to it, so the API stays private; the API tells Inngest its address from `FRONTEND_URL`. In development, start Inngest's Dev Server next to `pnpm dev` with `pnpm jobs:dev`, and open its dashboard at <http://localhost:8288> to see every run; `INNGEST_DEV=1` in `apps/api/.env.local` points the API at it, and the API syncs its jobs once the frontend answers. In production, create an app in Inngest, set `INNGEST_EVENT_KEY` and `INNGEST_SIGNING_KEY` on the API, remove `INNGEST_DEV`, and sync `https://<your-frontend>/api/inngest` in Inngest's dashboard. <!-- clubedge:only jobs=inngest && api=hono -->
312
326
 
313
- Define a job in `apps/web/src/jobs` and add it to the list in `apps/web/src/jobs/index.ts`:
327
+ Define a job in `apps/web/src/jobs` and add it to the list in `apps/web/src/jobs/index.ts`: <!-- clubedge:only api=none -->
328
+ Define a job in `apps/api/src/jobs` and add it to the list in `apps/api/src/jobs/index.ts`: <!-- clubedge:only api=hono -->
314
329
 
315
330
  ```ts
316
331
  import { defineJob } from "@clubedge/jobs";
@@ -324,15 +339,20 @@ export const welcomeEmail = defineJob<{ userId: string }>({
324
339
  });
325
340
  ```
326
341
 
327
- Queue it from server code with `getJobs().enqueue(welcomeEmail, { userId })`, from `@/server/jobs`. To send any email in the background, enqueue `sendEmailJob` from `@/jobs` with the message, as the auth emails do. <!-- clubedge:only email!=none -->
328
- Queue it from server code with `getJobs().enqueue(welcomeEmail, { userId })`, from `@/server/jobs`. <!-- clubedge:only email=none -->
342
+ Queue it from server code with `getJobs().enqueue(welcomeEmail, { userId })`, from `@/server/jobs`. To send any email in the background, enqueue `sendEmailJob` from `@/jobs` with the message, as the auth emails do. <!-- clubedge:only email!=none && api=none -->
343
+ Queue it from the API's code with `getJobs().enqueue(welcomeEmail, { userId })`, from `@/server/jobs`. To send any email in the background, enqueue `sendEmailJob` from `@/jobs` with the message. <!-- clubedge:only email!=none && api=hono -->
344
+ Queue it from server code with `getJobs().enqueue(welcomeEmail, { userId })`, from `@/server/jobs`. <!-- clubedge:only email=none && api=none -->
345
+ Queue it from the API's code with `getJobs().enqueue(welcomeEmail, { userId })`, from `@/server/jobs`. <!-- clubedge:only email=none && api=hono -->
329
346
 
330
- A thrown error fails the attempt and the job is retried (`retryLimit`, `retryDelaySeconds`, `retryBackoff`). An attempt that runs past `timeoutSeconds`, or whose server stops, is retried too, so make jobs safe to run twice. Add `schedule: "0 3 * * *"` (cron syntax, UTC) to run a job on a schedule. Restart `pnpm dev` after adding or changing a job. The dashboard's jobs card queues the sample job from `apps/web/src/jobs/sample.ts` and lists its recent runs; remove both when you add your own.
347
+ A thrown error fails the attempt and the job is retried (`retryLimit`, `retryDelaySeconds`, `retryBackoff`). An attempt that runs past `timeoutSeconds`, or whose server stops, is retried too, so make jobs safe to run twice. Add `schedule: "0 3 * * *"` (cron syntax, UTC) to run a job on a schedule. Restart `pnpm dev` after adding or changing a job. The dashboard's jobs card queues the sample job from `apps/web/src/jobs/sample.ts` and lists its recent runs; remove both when you add your own. <!-- clubedge:only api=none -->
348
+ A thrown error fails the attempt and the job is retried (`retryLimit`, `retryDelaySeconds`, `retryBackoff`). An attempt that runs past `timeoutSeconds`, or whose server stops, is retried too, so make jobs safe to run twice. Add `schedule: "0 3 * * *"` (cron syntax, UTC) to run a job on a schedule. Restart the API after adding or changing a job. The dashboard's jobs card queues the sample job from `apps/api/src/jobs/sample.ts` through `/api/jobs` and lists its recent runs; remove both when you add your own. <!-- clubedge:only api=hono -->
331
349
 
332
- Where no server keeps running, as on Vercel and Netlify, there is no worker: `JOBS_WORKER` defaults to `off` there, and you can set it yourself anywhere. Set `CRON_SECRET` to 16 or more random characters and call `GET /api/jobs/run` every minute or so with the header `Authorization: Bearer <CRON_SECRET>`, from Vercel Cron, a Netlify scheduled function, or any scheduler. Each call runs the jobs that are due. <!-- clubedge:only jobs=pg-boss|bullmq -->
350
+ Where no server keeps running, as on Vercel and Netlify, there is no worker: `JOBS_WORKER` defaults to `off` there, and you can set it yourself anywhere. Set `CRON_SECRET` to 16 or more random characters and call `GET /api/jobs/run` every minute or so with the header `Authorization: Bearer <CRON_SECRET>`, from Vercel Cron, a Netlify scheduled function, or any scheduler. Each call runs the jobs that are due. <!-- clubedge:only jobs=pg-boss|bullmq && api=none -->
351
+ To run the jobs elsewhere, set `JOBS_WORKER=off` on the API: it then runs no worker. Set `CRON_SECRET` to 16 or more random characters and call `GET /api/jobs/run` on the frontend, which forwards it to the API, every minute or so with the header `Authorization: Bearer <CRON_SECRET>`. Each call runs the jobs that are due. The API stops its worker on `SIGTERM`, letting running jobs finish. <!-- clubedge:only jobs=pg-boss|bullmq && api=hono -->
333
352
  Inngest keeps the job history: the jobs card reads it from Inngest's API (the Dev Server's locally), and Inngest's dashboard shows each run's attempts, output, and errors. <!-- clubedge:only jobs=inngest -->
334
353
 
335
- Jobs go through the provider-neutral `JobQueue` interface in `packages/jobs`, so job definitions, the routes, and the jobs card stay the same whichever provider runs them. Switch providers with `pnpm clubedge add jobs pg-boss`, `bullmq`, or `inngest`. To add another, implement `JobQueue` in a new package, return it from `apps/web/src/server/jobs.ts`, and prove it with the shared conformance suite, as each provider's tests do:
354
+ Jobs go through the provider-neutral `JobQueue` interface in `packages/jobs`, so job definitions, the routes, and the jobs card stay the same whichever provider runs them. Switch providers with `pnpm clubedge add jobs pg-boss`, `bullmq`, or `inngest`. To add another, implement `JobQueue` in a new package, return it from `apps/web/src/server/jobs.ts`, and prove it with the shared conformance suite, as each provider's tests do: <!-- clubedge:only api=none -->
355
+ Jobs go through the provider-neutral `JobQueue` interface in `packages/jobs`, so job definitions, the routes, and the jobs card stay the same whichever provider runs them. Switch providers with `pnpm clubedge add jobs pg-boss`, `bullmq`, or `inngest`. To add another, implement `JobQueue` in a new package, return it from `apps/api/src/server/jobs.ts`, and prove it with the shared conformance suite, as each provider's tests do: <!-- clubedge:only api=hono -->
336
356
 
337
357
  ```ts
338
358
  import { describeJobQueue } from "@clubedge/jobs/conformance";
@@ -352,6 +372,7 @@ Server errors and traces go to the tool you chose. Errors that escape a page, ro
352
372
 
353
373
  Set `OTEL_EXPORTER_OTLP_ENDPOINT` to an OpenTelemetry collector or to a vendor's OTLP/HTTP endpoint (Grafana Cloud, Honeycomb, Datadog, and others accept it), with any API key in `OTEL_EXPORTER_OTLP_HEADERS` as `key=value` pairs. Traces go to `/v1/traces` and errors to `/v1/logs` as error log records, and each error is also recorded on the span it happened in. `OTEL_SERVICE_NAME` defaults to the project's service id. The spans Next.js and pg-boss create join the same traces. <!-- clubedge:only framework=next -->
354
374
  Set `OTEL_EXPORTER_OTLP_ENDPOINT` to an OpenTelemetry collector or to a vendor's OTLP/HTTP endpoint (Grafana Cloud, Honeycomb, Datadog, and others accept it), with any API key in `OTEL_EXPORTER_OTLP_HEADERS` as `key=value` pairs. Traces go to `/v1/traces` and errors to `/v1/logs` as error log records, and each error is also recorded on the span it happened in. `OTEL_SERVICE_NAME` defaults to the project's service id. <!-- clubedge:only framework=tanstack-start -->
375
+ Set `OTEL_EXPORTER_OTLP_ENDPOINT` in `apps/api/.env.local` to an OpenTelemetry collector or to a vendor's OTLP/HTTP endpoint (Grafana Cloud, Honeycomb, Datadog, and others accept it), with any API key in `OTEL_EXPORTER_OTLP_HEADERS` as `key=value` pairs. The API sends traces to `/v1/traces` and errors to `/v1/logs` as error log records, and each error is also recorded on the span it happened in. `OTEL_SERVICE_NAME` defaults to the API's service id. <!-- clubedge:only framework=vite -->
355
376
 
356
377
  To see traces during development, run [Jaeger](https://www.jaegertracing.io), set `OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318`, and open http://localhost:16686:
357
378
 
@@ -364,17 +385,20 @@ docker run --rm -p 16686:16686 -p 4318:4318 jaegertracing/jaeger:latest
364
385
 
365
386
  Create a Node.js project in [Sentry](https://sentry.io) and set `SENTRY_DSN` to its DSN. `SENTRY_TRACES_SAMPLE_RATE` is the share of requests traced, from 0 to 1 (default 0.1; use 1 while trying it out), and `SENTRY_ENVIRONMENT` labels events (default `NODE_ENV`). The SDK sends no user details, cookies, query strings, or request bodies. The spans Next.js and pg-boss create join the same traces. <!-- clubedge:only framework=next -->
366
387
  Create a Node.js project in [Sentry](https://sentry.io) and set `SENTRY_DSN` to its DSN. `SENTRY_TRACES_SAMPLE_RATE` is the share of requests traced, from 0 to 1 (default 0.1; use 1 while trying it out), and `SENTRY_ENVIRONMENT` labels events (default `NODE_ENV`). The SDK sends no user details, cookies, query strings, or request bodies. <!-- clubedge:only framework=tanstack-start -->
388
+ Create a Node.js project in [Sentry](https://sentry.io) and set `SENTRY_DSN` in `apps/api/.env.local` to its DSN; the frontend reads it from the API at runtime. `SENTRY_TRACES_SAMPLE_RATE` is the share of API requests traced, from 0 to 1 (default 0.1; use 1 while trying it out), and `SENTRY_ENVIRONMENT` labels events (default `NODE_ENV`). The SDK sends no user details, cookies, query strings, or request bodies. <!-- clubedge:only framework=vite -->
367
389
 
368
- To see your own code in browser stack traces, give the build `SENTRY_AUTH_TOKEN` (an auth token with the `project:releases` scope), `SENTRY_ORG`, and `SENTRY_PROJECT`. The build then makes source maps for the browser bundle, uploads them to Sentry, and deletes them, so they are never served. Without the token the build makes no source maps. Set the three variables where the build runs: in CI, or as build-time variables on your platform.
390
+ To see your own code in browser stack traces, give the build `SENTRY_AUTH_TOKEN` (an auth token with the `project:releases` scope), `SENTRY_ORG`, and `SENTRY_PROJECT`. The build then makes source maps for the browser bundle, uploads them to Sentry, and deletes them, so they are never served. Without the token the build makes no source maps. Set the three variables where the build runs: in CI, or as build-time variables on your platform. <!-- clubedge:only framework!=vite -->
391
+ The React + Vite build does not upload source maps to Sentry yet, so browser stack traces point into the minified bundle. <!-- clubedge:only framework=vite -->
369
392
 
370
393
  <!-- clubedge:end -->
371
394
  <!-- clubedge:if observability!=none -->
372
395
 
373
396
  Uncaught errors in the browser are reported too, with the page's path and no query string. With OpenTelemetry, the browser sends them to `/api/client-errors`, which reports them like server errors and accepts 30 reports a minute per address. With Sentry, Sentry's browser SDK sends them directly; it is downloaded only when `SENTRY_DSN` is set. In both cases the browser reads its settings from `/api/client-errors` at runtime, so builds never bake them in.
374
397
 
375
- On Vercel and Netlify, a function can stop right after it responds, so spans still waiting in a batch at that moment can be lost.
398
+ On Vercel and Netlify, a function can stop right after it responds, so spans still waiting in a batch at that moment can be lost. <!-- clubedge:only framework!=vite -->
376
399
 
377
- Observability goes through the provider-neutral `ObservabilityProvider` interface in `packages/observability` and the telemetry hooks in `@clubedge/core`. To use another tool, implement that interface in a new package and install it from `apps/web/src/server/observability.ts`; error reports and spans across the app stay the same.
400
+ Observability goes through the provider-neutral `ObservabilityProvider` interface in `packages/observability` and the telemetry hooks in `@clubedge/core`. To use another tool, implement that interface in a new package and install it from `apps/web/src/server/observability.ts`; error reports and spans across the app stay the same. <!-- clubedge:only api=none -->
401
+ Observability goes through the provider-neutral `ObservabilityProvider` interface in `packages/observability` and the telemetry hooks in `@clubedge/core`. To use another tool, implement that interface in a new package and install it from `apps/api/src/server/observability.ts`; error reports and spans across the API stay the same. The API stops taking requests on `SIGTERM` and sends what is still buffered before it exits. <!-- clubedge:only api=hono -->
378
402
 
379
403
  <!-- clubedge:end -->
380
404
  <!-- clubedge:if storage!=none -->
@@ -391,6 +415,12 @@ The storage adapter works with AWS S3 and S3-compatible providers such as Cloudf
391
415
 
392
416
  The storage adapter uses Supabase Storage through the signed-in user's Supabase session, so bucket policies can rely on that user. Set `SUPABASE_STORAGE_BUCKET` and choose a bucket policy that matches your application's access model.
393
417
 
418
+ <!-- clubedge:end -->
419
+ <!-- clubedge:if storage!=none && api=hono -->
420
+
421
+ The API holds the storage adapter: set its variables in `apps/api/.env.local`, and in a route call `getStorage(c.req.raw)` from `apps/api/src/server/storage.ts`. `pnpm check:services` uploads, reads back, and deletes a test file. <!-- clubedge:only storage=s3 -->
422
+ The API holds the storage adapter: set `SUPABASE_STORAGE_BUCKET` in `apps/api/.env.local`, and in a route call `getStorage(c.req.raw)` from `apps/api/src/server/storage.ts`. It acts as the user whose Supabase access token the request carries (the `Authorization: Bearer` header the frontend sends), and as anonymous without one. <!-- clubedge:only storage=supabase -->
423
+
394
424
  <!-- clubedge:end -->
395
425
  <!-- clubedge:if storage!=none -->
396
426
 
@@ -614,6 +644,11 @@ To change the API, edit `openapi.yaml` first, run `pnpm --filter @clubedge/contr
614
644
  API_URL=http://127.0.0.1:3001 pnpm exec vitest run packages/contract/src/remote.test.ts
615
645
  ```
616
646
 
647
+ Some endpoints are an optional part of a module, a capability (`x-clubedge-capability` in `openapi.yaml`): the account settings page's display name and account deletion are the `account` capability of the auth module. An API without a capability answers its endpoints with 404, and the suite checks that unless `API_CAPABILITIES` lists it (such as `API_CAPABILITIES=account`).
648
+
649
+ The settings page changes passwords with the auth provider, in the browser or in Better Auth's server, which signs out the user's other sessions and applies the provider's rate limits. The display name and account deletion go through the API, which keeps the app's data: deletion checks the password (10 tries a minute per user, refused while the limit cannot be checked), removes the user's app data, then deletes the user from the provider. <!-- clubedge:only auth!=none && api=hono -->
650
+ The FastAPI API does not implement the `account` capability yet, so the settings page offers only the password change. <!-- clubedge:only auth!=none && api=fastapi -->
651
+
617
652
  In production, run each app's image: `apps/vite/Dockerfile` (the frontend, served by Node with `API_URL` set to the API's address) and the selected API image (`apps/api/Dockerfile` or `apps/api-fastapi/Dockerfile`). `docker compose up --build` runs both.
618
653
 
619
654
  Run `node migrate.mjs` in the API's image before a new version starts. <!-- clubedge:only api=hono -->
@@ -21,6 +21,8 @@ DATABASE_URL_DIRECT=
21
21
  # clubedge:if auth=supabase
22
22
  SUPABASE_URL=
23
23
  SUPABASE_PUBLISHABLE_KEY=
24
+ # Optional: the project's secret key (server-side only), which deleting accounts needs.
25
+ SUPABASE_SECRET_KEY=
24
26
  # clubedge:end
25
27
 
26
28
  # Firebase Authentication. Private key is a server secret; escape newlines as \\n.
@@ -36,9 +38,115 @@ FIREBASE_PRIVATE_KEY=
36
38
  # clubedge:if auth=appwrite
37
39
  APPWRITE_ENDPOINT=https://cloud.appwrite.io/v1
38
40
  APPWRITE_PROJECT_ID=
41
+ # Optional: an API key with the sessions.write and users.write scopes, to delete accounts.
42
+ APPWRITE_API_KEY=
39
43
  # clubedge:end
40
44
 
41
45
  # Better Auth is hosted at this public origin and uses a database-backed session cookie.
42
46
  # clubedge:if auth=better-auth
43
47
  BETTER_AUTH_URL=http://localhost:3000
44
48
  # clubedge:end
49
+
50
+ # clubedge:if cache=redis
51
+ # Optional rate limits and cache (Redis protocol; rediss:// enables TLS). Without it, both use
52
+ # process memory. Upstash example: rediss://default:YOUR_PASSWORD@your-database.upstash.io:6379
53
+ REDIS_URL= # clubedge:only infra!=docker
54
+ REDIS_URL=redis://localhost:6379 # clubedge:only infra=docker
55
+ # clubedge:end
56
+
57
+ # clubedge:if storage=s3
58
+ # S3-compatible storage (AWS S3, Cloudflare R2, MinIO)
59
+ STORAGE_BUCKET= # clubedge:only infra!=docker
60
+ STORAGE_REGION=auto # clubedge:only infra!=docker
61
+ STORAGE_ENDPOINT= # clubedge:only infra!=docker
62
+ STORAGE_ACCESS_KEY_ID= # clubedge:only infra!=docker
63
+ STORAGE_SECRET_ACCESS_KEY= # clubedge:only infra!=docker
64
+ # Local S3-compatible storage from docker-compose.dev.yml; it accepts any credentials. # clubedge:only infra=docker
65
+ STORAGE_BUCKET=app # clubedge:only infra=docker
66
+ STORAGE_REGION=us-east-1 # clubedge:only infra=docker
67
+ STORAGE_ENDPOINT=http://localhost:9090 # clubedge:only infra=docker
68
+ STORAGE_ACCESS_KEY_ID=local # clubedge:only infra=docker
69
+ STORAGE_SECRET_ACCESS_KEY=local-secret # clubedge:only infra=docker
70
+ STORAGE_PUBLIC_URL=
71
+ # Without an S3 service, files are stored in this folder (relative to the API). # clubedge:only infra=local
72
+ STORAGE_DIRECTORY=../../.data/storage # clubedge:only infra=local
73
+ # clubedge:end
74
+
75
+ # clubedge:if storage=supabase
76
+ # Supabase Storage bucket, accessed as the user whose access token the request carries
77
+ SUPABASE_STORAGE_BUCKET= # clubedge:only infra!=supabase
78
+ SUPABASE_STORAGE_BUCKET=app # clubedge:only infra=supabase
79
+ # clubedge:end
80
+
81
+ # clubedge:if email=smtp
82
+ # Email over SMTP: any provider's SMTP endpoint (smtps:// for TLS). Without it, development
83
+ # prints emails to the server log and production refuses to send.
84
+ SMTP_URL= # clubedge:only infra!=docker|supabase
85
+ # Mailpit from docker-compose.dev.yml; read the emails at http://localhost:8025. # clubedge:only infra=docker
86
+ SMTP_URL=smtp://localhost:1025 # clubedge:only infra=docker
87
+ # The local Supabase inbox; read the emails at http://127.0.0.1:54324. # clubedge:only infra=supabase
88
+ SMTP_URL=smtp://127.0.0.1:54325 # clubedge:only infra=supabase
89
+ EMAIL_FROM=App <no-reply@example.com>
90
+ # clubedge:end
91
+
92
+ # clubedge:if email=resend
93
+ # Resend (https://resend.com). EMAIL_FROM must use a domain verified in Resend. Without the
94
+ # key, development prints emails to the server log and production refuses to send.
95
+ RESEND_API_KEY=
96
+ EMAIL_FROM=App <no-reply@example.com>
97
+ # clubedge:end
98
+
99
+ # clubedge:if jobs=pg-boss
100
+ # Background jobs are stored in DATABASE_URL and run by a worker inside the API. JOBS_WORKER=off
101
+ # turns the worker off; a scheduler then calls /api/jobs/run with CRON_SECRET (16 or more
102
+ # characters) instead.
103
+ JOBS_WORKER=
104
+ CRON_SECRET=
105
+ # clubedge:end
106
+
107
+ # clubedge:if jobs=bullmq
108
+ # Background jobs are stored in Redis (REDIS_URL above) through BullMQ and run by a worker inside
109
+ # the API. JOBS_WORKER=off turns the worker off; a scheduler then calls /api/jobs/run with
110
+ # CRON_SECRET (16 or more characters) instead.
111
+ JOBS_WORKER=
112
+ CRON_SECRET=
113
+ # clubedge:end
114
+
115
+ # clubedge:if jobs=inngest
116
+ # Background jobs run by Inngest (https://www.inngest.com), which calls /api/inngest through the
117
+ # frontend (FRONTEND_URL above), so the API stays private. In development, start its Dev Server
118
+ # with pnpm jobs:dev (http://localhost:8288); INNGEST_DEV=1 points the API at it. In production,
119
+ # remove INNGEST_DEV and set the keys of your Inngest app.
120
+ INNGEST_DEV=1
121
+ INNGEST_EVENT_KEY=
122
+ INNGEST_SIGNING_KEY=
123
+ # clubedge:end
124
+
125
+ # clubedge:if payments=stripe
126
+ # Stripe (https://dashboard.stripe.com/apikeys): use test-mode keys during development. The
127
+ # webhook secret comes from `stripe listen` locally, or from the endpoint's settings in production;
128
+ # Stripe calls the webhook through the frontend, at FRONTEND_URL/api/webhooks/payments.
129
+ STRIPE_SECRET_KEY=
130
+ STRIPE_WEBHOOK_SECRET=
131
+ # The Stripe price for each plan in src/config/plans.ts (STRIPE_PRICE_<PLAN>).
132
+ STRIPE_PRICE_PRO=
133
+ # Tests can send Stripe API requests to a stand-in, such as stripe-mock or the fake in
134
+ # e2e/stripe-fake.ts: STRIPE_API_BASE=http://127.0.0.1:12111. Leave it unset otherwise.
135
+ # clubedge:end
136
+
137
+ # clubedge:if observability=otel
138
+ # OpenTelemetry: where traces and error logs go over OTLP/HTTP, such as a collector, Grafana
139
+ # Cloud, or Honeycomb. Empty sends nothing. Headers are key=value pairs separated by commas.
140
+ OTEL_EXPORTER_OTLP_ENDPOINT=
141
+ OTEL_EXPORTER_OTLP_HEADERS=
142
+ OTEL_SERVICE_NAME=
143
+ # clubedge:end
144
+
145
+ # clubedge:if observability=sentry
146
+ # Sentry (https://sentry.io): the DSN from the project's Client Keys settings. Empty sends nothing.
147
+ # The browser reads it from the API at runtime. The traces sample rate is the share of requests
148
+ # traced, from 0 to 1 (default 0.1).
149
+ SENTRY_DSN=
150
+ SENTRY_ENVIRONMENT=
151
+ SENTRY_TRACES_SAMPLE_RATE=
152
+ # clubedge:end
@@ -10,9 +10,10 @@ await build({
10
10
  target: "node22",
11
11
  format: "esm",
12
12
  sourcemap: true,
13
- // Some dependencies still call require(); give the ESM bundle one.
13
+ // Some dependencies still call require(); give the ESM bundle one. The import is renamed
14
+ // because bundled modules (Sentry's) import createRequire themselves, at the same top level.
14
15
  banner: {
15
- js: 'import { createRequire } from "node:module"; const require = createRequire(import.meta.url);',
16
+ js: 'import { createRequire as createBannerRequire } from "node:module"; const require = createBannerRequire(import.meta.url);',
16
17
  },
17
18
  logLevel: "info",
18
19
  });