@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.
- package/CHANGELOG.md +15 -0
- package/README.md +11 -10
- package/package.json +3 -3
- package/template/.github/workflows/ci.yml +35 -1
- package/template/README.md +19 -8
- package/template/SETUP.md +51 -16
- package/template/apps/api/.env.example +108 -0
- package/template/apps/api/build.mjs +3 -2
- package/template/apps/api/clubedge.stack.json +87 -1
- package/template/apps/api/package.json +20 -2
- package/template/apps/api/scripts/check-env.ts +35 -7
- package/template/apps/api/scripts/check-services.ts +204 -9
- package/template/apps/api/src/app.test.ts +39 -1
- package/template/apps/api/src/app.ts +66 -7
- package/template/apps/api/src/config/plans.ts +16 -0
- package/template/apps/api/src/env/production.test.ts +88 -0
- package/template/apps/api/src/env/production.ts +121 -0
- package/template/apps/api/src/http.test.ts +38 -0
- package/template/apps/api/src/http.ts +30 -0
- package/template/apps/api/src/index.ts +22 -1
- package/template/apps/api/src/jobs/index.ts +31 -0
- package/template/apps/api/src/jobs/sample.ts +10 -0
- package/template/apps/api/src/rate-limit.test.ts +43 -0
- package/template/apps/api/src/rate-limit.ts +51 -0
- package/template/apps/api/src/routes/account.test.ts +141 -0
- package/template/apps/api/src/routes/account.ts +135 -0
- package/template/apps/api/src/routes/billing.test.ts +208 -0
- package/template/apps/api/src/routes/billing.ts +130 -0
- package/template/apps/api/src/routes/client-errors.test.ts +90 -0
- package/template/apps/api/src/routes/client-errors.ts +43 -0
- package/template/apps/api/src/routes/inngest.test.ts +37 -0
- package/template/apps/api/src/routes/inngest.ts +14 -0
- package/template/apps/api/src/routes/jobs-run.test.ts +39 -0
- package/template/apps/api/src/routes/jobs-run.ts +25 -0
- package/template/apps/api/src/routes/jobs.test.ts +85 -0
- package/template/apps/api/src/routes/jobs.ts +68 -0
- package/template/apps/api/src/server/account.ts +38 -0
- package/template/apps/api/src/server/auth.ts +18 -0
- package/template/apps/api/src/server/cache.test.ts +65 -0
- package/template/apps/api/src/server/cache.ts +57 -0
- package/template/apps/api/src/server/email.ts +39 -0
- package/template/apps/api/src/server/index.ts +13 -0
- package/template/apps/api/src/server/jobs.test.ts +28 -0
- package/template/apps/api/src/server/jobs.ts +82 -0
- package/template/apps/api/src/server/observability.test.ts +23 -0
- package/template/apps/api/src/server/observability.ts +48 -0
- package/template/apps/api/src/server/payments.ts +76 -0
- package/template/apps/api/src/server/storage.ts +64 -0
- package/template/apps/api/src/server/users.ts +8 -0
- package/template/apps/api/src/server/variants/auth.appwrite.ts +43 -0
- package/template/apps/api/src/server/variants/auth.better-auth.ts +32 -0
- package/template/apps/api/src/server/variants/auth.firebase.ts +53 -0
- package/template/apps/api/src/server/variants/auth.supabase.ts +31 -1
- package/template/apps/api/src/server/variants/cache.memory.ts +25 -0
- package/template/apps/api/src/server/variants/email.resend.ts +39 -0
- package/template/apps/api/src/server/variants/jobs.bullmq.ts +77 -0
- package/template/apps/api/src/server/variants/jobs.inngest.ts +96 -0
- package/template/apps/api/src/server/variants/observability.sentry.ts +65 -0
- package/template/apps/api/src/server/variants/storage.supabase.ts +59 -0
- package/template/apps/api/src/tracing.ts +12 -0
- package/template/apps/api-fastapi/package.json +1 -1
- package/template/apps/api-fastapi/pyproject.toml +1 -1
- package/template/apps/api-fastapi/uv.lock +1 -1
- package/template/apps/start/package.json +1 -1
- package/template/apps/vite/.env.example +27 -3
- package/template/apps/vite/auth.server.mjs +86 -30
- package/template/apps/vite/clubedge.stack.json +39 -0
- package/template/apps/vite/package.json +7 -2
- package/template/apps/vite/server.mjs +22 -5
- package/template/apps/vite/src/components/billing/billing-card.tsx +143 -0
- package/template/apps/vite/src/components/dashboard/variants/account-button.supabase.tsx +32 -21
- package/template/apps/vite/src/components/error-reporting.tsx +52 -0
- package/template/apps/vite/src/components/jobs/jobs-card.tsx +95 -0
- package/template/apps/vite/src/components/route-error.tsx +12 -0
- package/template/apps/vite/src/components/variants/error-reporting.sentry.tsx +34 -0
- package/template/apps/vite/src/lib/auth-client.ts +18 -0
- package/template/apps/vite/src/main.tsx +6 -0
- package/template/apps/vite/src/routes/dashboard.tsx +41 -0
- package/template/apps/vite/src/routes/login.tsx +21 -14
- package/template/apps/vite/src/routes/settings.tsx +383 -0
- package/template/apps/vite/src/variants/auth.appwrite.ts +22 -2
- package/template/apps/vite/src/variants/auth.better-auth.ts +31 -2
- package/template/apps/vite/src/variants/auth.firebase.ts +39 -2
- package/template/apps/vite/src/variants/auth.supabase.ts +20 -1
- package/template/apps/vite/src/variants/router.supabase.tsx +8 -0
- package/template/apps/web/package.json +1 -1
- package/template/clubedge.template.json +2 -1
- package/template/package.json +3 -2
- package/template/packages/auth/package.json +1 -1
- package/template/packages/auth-appwrite/package.json +1 -1
- package/template/packages/auth-better-auth/package.json +1 -1
- package/template/packages/auth-firebase/package.json +1 -1
- package/template/packages/auth-supabase/package.json +1 -1
- package/template/packages/auth-supabase/src/index.test.ts +25 -3
- package/template/packages/auth-supabase/src/index.ts +12 -0
- package/template/packages/cache/package.json +1 -1
- package/template/packages/cache-redis/package.json +1 -1
- package/template/packages/contract/openapi.yaml +633 -0
- package/template/packages/contract/package.json +1 -1
- package/template/packages/contract/src/conformance.ts +268 -4
- package/template/packages/contract/src/index.ts +12 -0
- package/template/packages/contract/src/remote.test.ts +24 -0
- package/template/packages/contract/src/schema.test.ts +59 -2
- package/template/packages/contract/src/schema.ts +824 -1
- package/template/packages/core/package.json +1 -1
- package/template/packages/db/package.json +1 -1
- package/template/packages/email/package.json +1 -1
- package/template/packages/email-resend/package.json +1 -1
- package/template/packages/email-smtp/package.json +1 -1
- package/template/packages/jobs/package.json +1 -1
- package/template/packages/jobs-bullmq/package.json +1 -1
- package/template/packages/jobs-inngest/package.json +1 -1
- package/template/packages/jobs-inngest/src/index.test.ts +26 -0
- package/template/packages/jobs-inngest/src/index.ts +7 -1
- package/template/packages/jobs-pg-boss/package.json +1 -1
- package/template/packages/local-db/package.json +1 -1
- package/template/packages/observability/package.json +1 -1
- package/template/packages/observability-otel/package.json +1 -1
- package/template/packages/observability-sentry/package.json +1 -1
- package/template/packages/payments/package.json +1 -1
- package/template/packages/payments-stripe/package.json +1 -1
- package/template/packages/storage/package.json +1 -1
- package/template/packages/storage-s3/package.json +1 -1
- package/template/packages/storage-supabase/package.json +1 -1
- package/template/packages/ui/package.json +1 -1
- package/template/playwright.config.ts +2 -1
- package/template/pnpm-lock.yaml +75 -5
- 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.
|
|
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.
|
|
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.
|
|
340
|
+
create-clubedge-app v0.39.0
|
|
341
341
|
|
|
|
342
342
|
v
|
|
343
|
-
Clubedge Starter v0.
|
|
344
|
-
commit
|
|
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.
|
|
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.
|
|
356
|
-
`
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
28
|
-
"starterCommit": "
|
|
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
|
package/template/README.md
CHANGED
|
@@ -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
|
|
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
|
|
311
|
-
|
|
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
|
|
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 =
|
|
16
|
+
js: 'import { createRequire as createBannerRequire } from "node:module"; const require = createBannerRequire(import.meta.url);',
|
|
16
17
|
},
|
|
17
18
|
logLevel: "info",
|
|
18
19
|
});
|