@clubedge/create-clubedge-app 0.15.0 → 0.16.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to `create-clubedge-app` are documented here.
 
+## 0.16.0
+
+- Default to Starter `v0.14.0`, which adds:
+  - An account settings page at `/settings` when an auth provider is selected: display name, password change (signing out other sessions), and account deletion. Supabase projects set `SUPABASE_SECRET_KEY` to allow deletion.
+  - Browser error reporting with observability on: uncaught errors, unhandled rejections, and render errors caught by the new error pages, through `/api/client-errors` (`otel`) or Sentry's browser SDK (`sentry`). Sentry builds with `SENTRY_AUTH_TOKEN`, `SENTRY_ORG`, and `SENTRY_PROJECT` upload source maps and then delete them.
+  - Auth emails sent through the background-jobs queue, with retries, when both email and jobs are selected.
+- None of this needs CLI code: it all comes from the Starter's manifest.
+
 ## 0.15.0
 
 - Add `status`: a project's Starter release, framework, modules, and Git state, whether a newer Starter release exists (from npm, still working offline), and the command to run next.

package/README.md

@@ -127,7 +127,7 @@ pnpm dlx @clubedge/create-clubedge-app my-app --yes --no-git --framework tanstac
 pnpm dlx @clubedge/create-clubedge-app my-app --ref main
 
 # Reproduce a specific Starter release or commit
-pnpm dlx @clubedge/create-clubedge-app my-app --ref v0.13.1
+pnpm dlx @clubedge/create-clubedge-app my-app --ref v0.14.0
 pnpm dlx @clubedge/create-clubedge-app my-app --ref <commit-sha>
 
 # Test local Starter changes before releasing them
@@ -146,7 +146,7 @@ pnpm clubedge add email resend payments stripe              # several modules as
 pnpm clubedge remove storage payments
 pnpm dlx @clubedge/create-clubedge-app add infra local --dry-run
 pnpm dlx @clubedge/create-clubedge-app@latest upgrade        # to the newest CLI's Starter release
-pnpm dlx @clubedge/create-clubedge-app upgrade --ref v0.13.1 # or a specific tag, branch, or commit
+pnpm dlx @clubedge/create-clubedge-app upgrade --ref v0.14.0 # or a specific tag, branch, or commit
 ```
 
 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.
@@ -177,27 +177,27 @@ pnpm clubedge doctor    # Node.js, pnpm, dependencies, lockfile, env file, and p
 Each CLI release is tested against one specific Starter release:
 
 ```text
-create-clubedge-app v0.15.0
+create-clubedge-app v0.16.0
         |
         v
-Clubedge Starter v0.13.1
-commit 28bfbf98c85ae500ace6a062dd10d67746e1a330
+Clubedge Starter v0.14.0
+commit 2219a21c2eb237b7d8ee004ea8bbeb098b70106e
 ```
 
 The current relationship is:
 
 | CLI release | Default Starter release | Meaning |
 | --- | --- | --- |
-| `create-clubedge-app@0.15.0` | `clubedge-starter@v0.13.1` | The CLI's required, tested default |
+| `create-clubedge-app@0.16.0` | `clubedge-starter@v0.14.0` | The CLI's required, tested default |
 
 This means the same CLI version always scaffolds the same Starter revision by default. The CLI does not silently follow Starter `main`.
 
-The `v0.13.1` tag is expected to resolve to commit
-`28bfbf98c85ae500ace6a062dd10d67746e1a330`. The CLI verifies this before
+The `v0.14.0` tag is expected to resolve to commit
+`2219a21c2eb237b7d8ee004ea8bbeb098b70106e`. The CLI verifies this before
 scaffolding with the default reference and fails rather than silently using a
 moved tag.
 
-When the Starter changes, its maintainers first publish a new versioned release, such as `v0.13.1`. 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.
+When the Starter changes, its maintainers first publish a new versioned release, such as `v0.14.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.
 
 Every generated project records its CLI version, Starter repository, Starter ref, Starter commit, framework, and modules in `package.json` and `README.md`.
 
@@ -252,7 +252,7 @@ CI packs the CLI with `npm pack`, scaffolds clean projects from the packed tarba
 1. Make and validate changes in `clubedge-starter`.
 2. Run lint, typecheck, unit tests, browser tests, and production build.
 3. Update the Starter package versions.
-4. Commit `main`, create a release tag such as `v0.13.1`, and publish the Starter release.
+4. Commit `main`, create a release tag such as `v0.14.0`, and publish the Starter release.
 
 ### CLI maintainers
 
@@ -277,6 +277,7 @@ Each phase ends with a Starter release and a CLI release pinned to it. The full
 | 0.13.0 | v0.12.0 | Background jobs |
 | 0.14.0 | v0.13.0 | Observability |
 | 0.15.0 | v0.13.1 | `status` and `doctor`, several modules in one change, conflict and upgrade summaries, macOS CI |
+| 0.16.0 | v0.14.0 | Account settings page, browser error reporting and Sentry source maps, auth emails through the jobs queue |
 | next | | Show the Starter's version of a conflicted file next to yours |
 
 ## Community

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/create-clubedge-app",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Create a Next.js or TanStack Start application from the Clubedge Starter reference implementation.",
   "type": "module",
   "packageManager": "pnpm@10.9.0",
@@ -22,8 +22,8 @@
   },
   "clubedge": {
     "starterRepository": "Clubedge/clubedge-starter",
-    "starterRef": "v0.13.1",
-    "starterCommit": "28bfbf98c85ae500ace6a062dd10d67746e1a330"
+    "starterRef": "v0.14.0",
+    "starterCommit": "2219a21c2eb237b7d8ee004ea8bbeb098b70106e"
   },
   "license": "Apache-2.0",
   "repository": {

package/template/.env.example

@@ -16,6 +16,8 @@ NEXT_PUBLIC_SUPABASE_URL= # clubedge:only infra!=supabase
 # Local Supabase Auth. pnpm infra:status prints the publishable key to copy below. # clubedge:only infra=supabase
 NEXT_PUBLIC_SUPABASE_URL=http://127.0.0.1:54321 # clubedge:only infra=supabase
 NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=
+# Optional, server-side only: lets users delete their account from the settings page.
+SUPABASE_SECRET_KEY=
 # clubedge:end
 
 # clubedge:if auth=better-auth
@@ -82,6 +84,10 @@ OTEL_SERVICE_NAME=
 SENTRY_DSN=
 SENTRY_ENVIRONMENT=
 SENTRY_TRACES_SAMPLE_RATE=
+# Build time only: with an auth token, the build uploads browser source maps to this project.
+# SENTRY_AUTH_TOKEN=
+# SENTRY_ORG=
+# SENTRY_PROJECT=
 # clubedge:end
 
 # clubedge:if storage=s3

package/template/README.md

@@ -57,6 +57,7 @@ Every combination in the CI matrix is generated as a real project and runs its f
 - 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 -->
 - Password reset by email, and email verification that can be required before sign-in. <!-- clubedge:only auth=better-auth && email!=none -->
 - Password reset by email, sent by Supabase. <!-- clubedge:only auth=supabase -->
+- An account settings page: display name, password change, and account deletion. <!-- clubedge:only auth!=none -->
 - 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 -->
 - Email through Resend; development prints emails to the server log until the API key is set. <!-- clubedge:only email=resend -->
 - S3-compatible storage adapter for AWS S3, Cloudflare R2, and MinIO. <!-- clubedge:only storage=s3 -->
@@ -276,13 +277,18 @@ Local services:
 - `pnpm infra:up`: run only the local database, for example for `pnpm check:services` or browser tests. <!-- clubedge:only infra=local -->
 - `pnpm infra:reset`: delete the local database and files in `.data/` (stop `pnpm dev` first). <!-- clubedge:only infra=local -->
 
+Check the project:
+
+- `pnpm clubedge status`: the project's Starter release, modules, and Git state, whether a newer Starter release exists, and the command to run next.
+- `pnpm clubedge doctor`: check Node.js, pnpm, the dependencies, the lockfile, and `apps/web/.env.local` against the example, then run `pnpm check:services`. It changes nothing and exits with an error when a check fails.
+
 Change the project later:
 
-- `pnpm clubedge add <module> <option>`: add a module or switch its option, for example `pnpm clubedge add auth better-auth` or `pnpm clubedge add infra local`. Run `pnpm clubedge add` without arguments to choose from a list.
-- `pnpm clubedge remove <module>`: remove a module, for example `pnpm clubedge remove storage`.
-- `pnpm clubedge upgrade`: move the project to the newest Starter release.
+- `pnpm clubedge add <module> <option>`: add a module or switch its option, for example `pnpm clubedge add auth better-auth` or `pnpm clubedge add infra local`. Name several to change them together, as in `pnpm clubedge add email resend payments stripe`. Run `pnpm clubedge add` without arguments to choose from a list.
+- `pnpm clubedge remove <module>`: remove one or more modules, for example `pnpm clubedge remove storage`.
+- `pnpm clubedge upgrade`: move the project to the newest Starter release. It first lists the releases in between.
 
-These commands merge the change into your code instead of overwriting it: files you never touched are updated, your edits are kept, and lines you both changed get conflict markers. Commit first, because they need a clean Git tree so that `git diff` shows the result. Add `--dry-run` to preview a change.
+These commands merge the change into your code instead of overwriting it: files you never touched are updated, your edits are kept, and lines you both changed get conflict markers, listed per file afterward. Commit first, because they need a clean Git tree so that `git diff` shows the result. Add `--dry-run` to preview a change.
 
 ## Documentation
 

package/template/SETUP.md

@@ -66,7 +66,8 @@ The app is available at <http://localhost:3000>, the liveness endpoint at <http:
 
 ## Supabase Auth
 
-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; never use a service role key.
+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 -->
+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 -->
 
 In Supabase Auth URL configuration, add this redirect URL for local email confirmation and password reset links:
 
@@ -96,6 +97,8 @@ Better Auth sends its emails through the [email module](#email): <!-- clubedge:o
 - **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 -->
 - **Email verification:** every new account gets a confirmation link. Sign-up signs the user in right away unless `BETTER_AUTH_REQUIRE_EMAIL_VERIFICATION=true`, which refuses sign-in until the link is opened. <!-- clubedge:only email!=none -->
 
+These emails are sent by the `send-email` [background job](#background-jobs), so sign-up never waits for the email provider, and a failed send is retried with backoff. <!-- clubedge:only email!=none && jobs!=none -->
+
 <!-- clubedge:end -->
 
 ## Local services
@@ -260,7 +263,8 @@ export const welcomeEmail = defineJob<{ userId: string }>({
 });
 ```
 
-Queue it from server code with `getJobs().enqueue(welcomeEmail, { userId })`, from `@/server/jobs`. 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) 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.
+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. 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) 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 email!=none -->
+Queue it from server code with `getJobs().enqueue(welcomeEmail, { userId })`, from `@/server/jobs`. 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) 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 email=none -->
 
 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. Scheduled jobs need a worker.
 
@@ -291,10 +295,14 @@ docker run --rm -p 16686:16686 -p 4318:4318 jaegertracing/jaeger:latest
 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 -->
 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 -->
 
+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:end -->
 <!-- clubedge:if observability!=none -->
 
-Only server-side errors are reported; errors in the browser are not. 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.
+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.
+
+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.
 
 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.
 
@@ -433,6 +441,7 @@ Production needs these variables:
 - `NEXT_PUBLIC_SUPABASE_URL` and `NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY`, from the Supabase project. <!-- clubedge:only framework=next && auth=supabase -->
 - `SUPABASE_URL` and `SUPABASE_PUBLISHABLE_KEY`, from the Supabase project. <!-- clubedge:only framework=tanstack-start && auth=supabase -->
 - `BETTER_AUTH_SECRET`, at least 32 random characters, different from development. <!-- clubedge:only auth=better-auth -->
+- `SUPABASE_SECRET_KEY`, if users should be able to delete their account. <!-- clubedge:only auth=supabase -->
 - `SMTP_URL` and `EMAIL_FROM`; without them, production refuses to send email. <!-- clubedge:only email=smtp -->
 - `RESEND_API_KEY` and `EMAIL_FROM`; without them, production refuses to send email. <!-- clubedge:only email=resend -->
 - `STRIPE_SECRET_KEY` (live mode), `STRIPE_WEBHOOK_SECRET` from the production webhook endpoint, and `STRIPE_PRICE_<PLAN>` for each plan. <!-- clubedge:only payments=stripe -->
@@ -445,6 +454,8 @@ Production needs these variables:
 
 ## Checks
 
+`pnpm clubedge doctor` checks that the project can run: Node.js and pnpm versions, installed dependencies, the lockfile, and `apps/web/.env.local` against the example, followed by `pnpm check:services`. Start there when something does not work.
+
 Run the checks relevant to your change before opening a pull request:
 
 ```sh

package/template/apps/start/.env.example

@@ -18,6 +18,8 @@ SUPABASE_URL= # clubedge:only infra!=supabase
 # Local Supabase Auth. pnpm infra:status prints the publishable key to copy below. # clubedge:only infra=supabase
 SUPABASE_URL=http://127.0.0.1:54321 # clubedge:only infra=supabase
 SUPABASE_PUBLISHABLE_KEY=
+# Optional: lets users delete their account from the settings page.
+SUPABASE_SECRET_KEY=
 # clubedge:end
 
 # clubedge:if auth=better-auth
@@ -84,6 +86,10 @@ OTEL_SERVICE_NAME=
 SENTRY_DSN=
 SENTRY_ENVIRONMENT=
 SENTRY_TRACES_SAMPLE_RATE=
+# Build time only: with an auth token, the build uploads browser source maps to this project.
+# SENTRY_AUTH_TOKEN=
+# SENTRY_ORG=
+# SENTRY_PROJECT=
 # clubedge:end
 
 # clubedge:if storage=s3

package/template/apps/start/AGENTS.md

@@ -5,7 +5,7 @@ This app mirrors `apps/web` with TanStack Start. Follow the root `AGENTS.md`, pl
 - Read the skills bundled with the installed packages before changing framework code: `node_modules/@tanstack/react-start/skills/` and `node_modules/@tanstack/start-client-core/skills/`. They match the installed version; APIs change often.
 - Route loaders run on the server and in the browser. Keep database, provider, and secret access in `src/server/`, reached from loaders through `createServerFn` (see `src/server/auth.functions.ts`).
 - Every server function and server route that touches private data must check the user itself. A route guard only protects the page, not the endpoint.
-- Modules in `src/server/` start with `import "@tanstack/react-start/server-only";` so they can never reach the browser bundle.
+- Modules in `src/server/` start with `import "@tanstack/react-start/server-only";` so they can never reach the browser bundle. The exception is `*.functions.ts`: routes import their `createServerFn` functions, and the Start compiler replaces each handler with a call to the server in the browser build. Keep them thin, importing the server-only modules they call.
 - Forms post to server routes that answer with 303 redirects (`src/server/auth-forms.ts`), so they work before hydration. Do not throw a router `redirect` from a POST handler; it uses 307 and repeats the POST.
 - Search params are plain strings (`src/router.tsx`). Build login links with `loginUrl()` so they match the Next.js app.
 - `src/routeTree.gen.ts` is generated by `vite dev` and `vite build`. Commit it, but do not edit it by hand.

package/template/apps/start/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/start",
-  "version": "0.13.1",
+  "version": "0.14.0",
   "private": true,
   "license": "Apache-2.0",
   "type": "module",

package/template/apps/start/src/components/auth/auth-form-controls.tsx

@@ -30,25 +30,31 @@ export function AuthForm({ action, children }: { action: string; children: React
 export function PasswordField({
   isSignUp,
   label = "Password",
+  name = "password",
+  minLength = 8,
 }: {
   isSignUp: boolean;
   label?: string;
+  /** The field's name and id; settings forms have more than one password field. */
+  name?: string;
+  /** 1 for fields that confirm an existing password, which may predate the current rules. */
+  minLength?: number;
 }) {
   const [visible, setVisible] = useState(false);
   const pending = useContext(PendingContext);
 
   return (
     <div className="grid gap-2">
-      <Label htmlFor="password">{label}</Label>
+      <Label htmlFor={name}>{label}</Label>
       <div className="relative">
         <Input
-          aria-describedby={isSignUp ? "password-hint" : undefined}
+          aria-describedby={isSignUp ? `${name}-hint` : undefined}
           autoComplete={isSignUp ? "new-password" : "current-password"}
           className="h-11 pr-11"
-          id="password"
+          id={name}
           maxLength={128}
-          minLength={8}
-          name="password"
+          minLength={minLength}
+          name={name}
           placeholder={isSignUp ? "Create a password" : "Enter your password"}
           // readOnly rather than disabled: disabled fields are left out of the submitted form.
           readOnly={pending}
@@ -70,7 +76,7 @@ export function PasswordField({
         </button>
       </div>
       {isSignUp && (
-        <p className="text-xs text-muted-foreground" id="password-hint">
+        <p className="text-xs text-muted-foreground" id={`${name}-hint`}>
           Use at least 8 characters.
         </p>
       )}
@@ -99,11 +105,24 @@ export function EmailField() {
   );
 }
 
-export function SubmitButton({ children, disabled }: { children: ReactNode; disabled?: boolean }) {
+export function SubmitButton({
+  children,
+  disabled,
+  variant,
+}: {
+  children: ReactNode;
+  disabled?: boolean;
+  variant?: "default" | "destructive";
+}) {
   const pending = useContext(PendingContext);
 
   return (
-    <Button className="h-11 w-full justify-center" disabled={disabled || pending} type="submit">
+    <Button
+      className="h-11 w-full justify-center"
+      disabled={disabled || pending}
+      type="submit"
+      variant={variant}
+    >
       {pending ? (
         <Loader2 aria-hidden="true" className="animate-spin motion-reduce:animate-none" />
       ) : null}

package/template/apps/start/src/components/dashboard/account-button.tsx

@@ -1,7 +1,8 @@
 import { Link } from "@tanstack/react-router";
 
 import type { AuthUser } from "@/server/auth";
-import { Button } from "@clubedge/ui/components/button";
+import { Button, buttonVariants } from "@clubedge/ui/components/button";
+import { cn } from "@clubedge/ui/lib/utils";
 
 type AccountButtonProps = {
   user: AuthUser | null;
@@ -11,23 +12,28 @@ type AccountButtonProps = {
 export function AccountButton({ user, className }: AccountButtonProps) {
   if (!user) {
     return (
-      <Button className={className} render={<Link to="/login" />} size="sm" variant="outline">
+      <Link to="/login" className={buttonVariants({ className, size: "sm", variant: "outline" })}>
         Sign in
-      </Button>
+      </Link>
     );
   }
 
   return (
-    <form action="/auth/sign-out" className={className} method="post">
-      <Button
-        className="w-full"
-        size="sm"
-        title={user.email ?? undefined}
-        type="submit"
-        variant="outline"
-      >
-        Sign out
-      </Button>
-    </form>
+    <div className={cn("flex items-center gap-2", className)}>
+      <Link to="/settings" className={buttonVariants({ size: "sm", variant: "ghost" })}>
+        Settings
+      </Link>
+      <form action="/auth/sign-out" className="flex-1" method="post">
+        <Button
+          className="w-full"
+          size="sm"
+          title={user.email ?? undefined}
+          type="submit"
+          variant="outline"
+        >
+          Sign out
+        </Button>
+      </form>
+    </div>
   );
 }

package/template/apps/start/src/components/error-reporting.tsx

@@ -0,0 +1,49 @@
+import { useEffect } from "react";
+
+const MAX_REPORTS = 10;
+let sent = 0;
+
+type Kind = "error" | "unhandledrejection" | "render";
+
+function describe(reason: unknown) {
+  if (reason instanceof Error)
+    return { name: reason.name, message: reason.message, stack: reason.stack };
+  return { name: "Error", message: String(reason) };
+}
+
+function send(kind: Kind, reason: unknown) {
+  if (sent >= MAX_REPORTS) return;
+  sent++;
+  const body = JSON.stringify({ kind, ...describe(reason), path: window.location.pathname });
+  // keepalive lets the report finish even if the page is being closed.
+  fetch("/api/client-errors", {
+    method: "POST",
+    body,
+    headers: { "content-type": "application/json" },
+    keepalive: true,
+  }).catch(() => {});
+}
+
+/** Reports a render error that an error boundary caught, so it never reaches the window. */
+export function reportBrowserError(error: unknown) {
+  send("render", error);
+}
+
+/**
+ * Sends uncaught errors and unhandled promise rejections from the browser to /api/client-errors,
+ * which reports them like server errors. At most a few per page load.
+ */
+export function ErrorReporting() {
+  useEffect(() => {
+    const onError = (event: ErrorEvent) => send("error", event.error ?? event.message);
+    const onRejection = (event: PromiseRejectionEvent) => send("unhandledrejection", event.reason);
+    // Capture phase: runs before handlers that might stop the event, such as a dev overlay.
+    window.addEventListener("error", onError, true);
+    window.addEventListener("unhandledrejection", onRejection, true);
+    return () => {
+      window.removeEventListener("error", onError, true);
+      window.removeEventListener("unhandledrejection", onRejection, true);
+    };
+  }, []);
+  return null;
+}

package/template/apps/start/src/components/route-error.tsx

@@ -0,0 +1,35 @@
+// clubedge:if observability!=none
+import { useEffect } from "react";
+// clubedge:end
+import { useRouter, type ErrorComponentProps } from "@tanstack/react-router";
+import { Button } from "@clubedge/ui/components/button";
+// clubedge:if observability!=none
+import { reportBrowserError } from "@/components/error-reporting";
+// clubedge:end
+
+/** Shown in place of a page that failed to render. */
+export function RouteError(props: ErrorComponentProps) {
+  const router = useRouter();
+  // clubedge:if observability!=none
+  // Error boundaries stop render errors before they reach the window, so report them here.
+  useEffect(() => {
+    reportBrowserError(props.error);
+  }, [props.error]);
+  // clubedge:end
+  return (
+    <main className="flex min-h-svh flex-col items-center justify-center gap-4 bg-background px-4 text-center">
+      <h1 className="text-xl font-semibold">Something went wrong</h1>
+      <p className="max-w-sm text-sm text-muted-foreground">
+        This page could not be shown. Try again, or come back in a moment.
+      </p>
+      <Button
+        onClick={() => {
+          props.reset();
+          void router.invalidate();
+        }}
+      >
+        Try again
+      </Button>
+    </main>
+  );
+}

package/template/apps/start/src/components/variants/error-reporting.sentry.tsx

@@ -0,0 +1,34 @@
+import { useEffect } from "react";
+import type { BrowserErrorReporting } from "@clubedge/observability";
+
+type Capture = (error: unknown) => void;
+let reporting: Promise<Capture | null> | undefined;
+
+// The settings come from /api/client-errors at runtime, and Sentry's browser SDK is only
+// downloaded when a DSN is configured.
+function startReporting() {
+  reporting ??= fetch("/api/client-errors")
+    .then((response) => (response.ok ? (response.json() as Promise<BrowserErrorReporting>) : null))
+    .then(async (config) => {
+      if (config?.provider !== "sentry") return null;
+      const { captureBrowserError, startBrowserErrorReporting } =
+        await import("@clubedge/observability-sentry/browser");
+      startBrowserErrorReporting(config);
+      return captureBrowserError;
+    })
+    .catch(() => null);
+  return reporting;
+}
+
+/** Reports a render error that an error boundary caught, so it never reaches the window. */
+export function reportBrowserError(error: unknown) {
+  void startReporting().then((capture) => capture?.(error));
+}
+
+/** Reports uncaught browser errors to Sentry. */
+export function ErrorReporting() {
+  useEffect(() => {
+    void startReporting();
+  }, []);
+  return null;
+}

package/template/apps/start/src/env/auth.ts

@@ -10,11 +10,14 @@ import { getAppUrl } from "./server";
 const supabaseAuthSchema = z.object({
   SUPABASE_URL: optional(z.url()),
   SUPABASE_PUBLISHABLE_KEY: optional(z.string()),
+  // Lets users delete their account from the settings page.
+  SUPABASE_SECRET_KEY: optional(z.string()),
 });
 
 export interface SupabaseAuthEnv {
   url: string;
   publishableKey: string;
+  secretKey?: string;
 }
 
 /** Supabase Auth settings, or null while they are not configured. */
@@ -22,7 +25,12 @@ export function getSupabaseAuthEnv(): SupabaseAuthEnv | null {
   const env = parseEnv(supabaseAuthSchema, "Supabase Auth");
   const url = env.SUPABASE_URL;
   const publishableKey = env.SUPABASE_PUBLISHABLE_KEY;
-  return url && publishableKey ? { url, publishableKey } : null;
+  if (!url || !publishableKey) return null;
+  return {
+    url,
+    publishableKey,
+    ...(env.SUPABASE_SECRET_KEY ? { secretKey: env.SUPABASE_SECRET_KEY } : {}),
+  };
 }
 // clubedge:end
 

package/template/apps/start/src/jobs/index.ts

@@ -1,7 +1,31 @@
 import type { JobDefinition } from "@clubedge/jobs";
+// clubedge:if email!=none
+import type { EmailMessage } from "@clubedge/email";
+import { defineJob } from "@clubedge/jobs";
+import { email } from "@/server/email";
+// clubedge:end
 import { sampleJob } from "./sample";
 
 export { sampleJob };
 
+// clubedge:if email!=none
+/**
+ * Sends an email in the background. Auth emails go through it, so a slow or failing email
+ * provider never delays sign-up, and failed sends are retried with backoff.
+ */
+export const sendEmailJob = defineJob<EmailMessage>({
+  name: "send-email",
+  retryLimit: 5,
+  retryDelaySeconds: 30,
+  retryBackoff: true,
+  async run(message) {
+    await email.send(message);
+  },
+});
+
+// clubedge:end
 /** Every job the worker runs. Define a job in this folder, then add it here. */
 export const jobs: JobDefinition[] = [sampleJob];
+// clubedge:if email!=none
+jobs.push(sendEmailJob);
+// clubedge:end

package/template/apps/start/src/routes/__root.tsx

@@ -1,6 +1,10 @@
 import type { ReactNode } from "react";
 import { HeadContent, Outlet, Scripts, createRootRoute } from "@tanstack/react-router";
 import { TooltipProvider } from "@clubedge/ui/components/tooltip";
+// clubedge:if observability!=none
+import { ErrorReporting } from "@/components/error-reporting";
+// clubedge:end
+import { RouteError } from "@/components/route-error";
 import { ThemeProvider } from "@/components/theme/theme-provider";
 import { siteConfig } from "@/config/site";
 import appCss from "../styles.css?url";
@@ -32,6 +36,7 @@ export const Route = createRootRoute({
   }),
   shellComponent: RootDocument,
   component: RootComponent,
+  errorComponent: RouteError,
 });
 
 function RootComponent() {
@@ -39,6 +44,9 @@ function RootComponent() {
     <ThemeProvider>
       <TooltipProvider>
         <Outlet />
+        {/* clubedge:if observability!=none */}
+        <ErrorReporting />
+        {/* clubedge:end */}
       </TooltipProvider>
     </ThemeProvider>
   );