@clubedge/create-clubedge-app 0.12.0 → 0.14.0

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to `create-clubedge-app` are documented here.
 
+## 0.14.0
+
+- Default to Starter `v0.13.0`, which adds observability (`--observability otel|sentry`): request tracing and server error reporting through OpenTelemetry, to any OTLP collector, or Sentry, behind provider-neutral hooks in `@clubedge/core`. `--observability` needs no CLI code: it comes from the Starter's manifest.
+- Test an observability project in CI and in the release smoke test, and add the observability module in the change-modules job.
+
+## 0.13.0
+
+- Default to Starter `v0.12.0`, which adds background jobs (`--jobs pg-boss`): jobs stored in the project's PostgreSQL, run by a worker inside the app server, with retries and schedules, and `/api/jobs/run` for serverless hosts. `--jobs` needs no CLI code: it comes from the Starter's manifest.
+- Fix generated lockfiles that pnpm rejected as broken when pruning an optional peer left a package with no dependencies, such as `pg-pool` once `pg` is pruned for `--jobs none`. Such entries are now written as `{}`, the way pnpm writes them.
+- Test a jobs project in CI and in the release smoke test, and add the jobs module in the change-modules job.
+
 ## 0.12.0
 
 - Default to Starter `v0.11.0`, which adds payments (`--payments stripe`): Stripe Checkout, the customer portal, and verified webhooks behind a provider-neutral payments interface. `--payments` needs no CLI code: it comes from the Starter's manifest.

package/README.md

@@ -12,27 +12,27 @@ The CLI downloads a tested Starter release, names the generated project, creates
 Each CLI release is tested against one specific Starter release:
 
 ```text
-create-clubedge-app v0.12.0
+create-clubedge-app v0.14.0
         |
         v
-Clubedge Starter v0.11.0
-commit b5637afcf3748e03bb7ecb1f1941a4e6c17cfa65
+Clubedge Starter v0.13.0
+commit 62fb8d1b1e13ed8e8e134bd1e53f2bfdde2c6a50
 ```
 
 The current relationship is:
 
 | CLI release | Default Starter release | Meaning |
 | --- | --- | --- |
-| `create-clubedge-app@0.12.0` | `clubedge-starter@v0.11.0` | The CLI's required, tested default |
+| `create-clubedge-app@0.14.0` | `clubedge-starter@v0.13.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.11.0` tag is expected to resolve to commit
-`b5637afcf3748e03bb7ecb1f1941a4e6c17cfa65`. The CLI verifies this before
+The `v0.13.0` tag is expected to resolve to commit
+`62fb8d1b1e13ed8e8e134bd1e53f2bfdde2c6a50`. 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.11.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.
+When the Starter changes, its maintainers first publish a new versioned release, such as `v0.13.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.
 
 ## Requirements
 
@@ -85,7 +85,7 @@ Either way, the app lives in `apps/web` and uses the same shared packages, so th
 
 ### Choosing services
 
-Authentication, file storage, caching, email, payments, local infrastructure, and deployment are modules. Each has a default, and anything you leave out is removed completely: its package, its provider SDK, its environment variables, its documentation, and its lockfile entries. The Starter's `clubedge.template.json` defines the modules, so a module a newer Starter adds gets its `--<module>` flag without a CLI change; `--help` lists the modules of the Starter this CLI release creates.
+Authentication, file storage, caching, email, payments, background jobs, observability, local infrastructure, and deployment are modules. Each has a default, and anything you leave out is removed completely: its package, its provider SDK, its environment variables, its documentation, and its lockfile entries. The Starter's `clubedge.template.json` defines the modules, so a module a newer Starter adds gets its `--<module>` flag without a CLI change; `--help` lists the modules of the Starter this CLI release creates.
 
 | Flag        | Options                                    | Default    |
 | ----------- | ------------------------------------------ | ---------- |
@@ -94,6 +94,8 @@ Authentication, file storage, caching, email, payments, local infrastructure, an
 | `--cache`   | `redis` (falls back to memory without `REDIS_URL`), `memory` | `redis` |
 | `--email`   | `smtp` (any provider, or a local inbox), `resend`, `none` | `smtp` |
 | `--payments` | `stripe`, `none` (needs an auth module) | `none` |
+| `--jobs` | `pg-boss`, `none` | `none` |
+| `--observability` | `otel` (OpenTelemetry, to any OTLP collector), `sentry`, `none` | `none` |
 | `--deploy`  | `docker` (any container host), `fly`, `railway`, `render`, `vercel`, `netlify` | `docker` |
 | `--infra`   | `docker` (Docker Compose), `supabase` (Supabase CLI), `local` (no Docker: PGlite and a local folder), `none` | `docker` |
 
@@ -139,7 +141,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.11.0
+pnpm dlx @clubedge/create-clubedge-app my-app --ref v0.13.0
 pnpm dlx @clubedge/create-clubedge-app my-app --ref <commit-sha>
 
 # Test local Starter changes before releasing them
@@ -156,7 +158,7 @@ pnpm dlx @clubedge/create-clubedge-app add cache redis      # or switch: add aut
 pnpm dlx @clubedge/create-clubedge-app remove storage
 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.11.0 # or a specific tag, branch, or commit
+pnpm dlx @clubedge/create-clubedge-app upgrade --ref v0.13.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.
@@ -207,7 +209,7 @@ CI packs the CLI with `npm pack`, scaffolds a clean project from the packed tarb
 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.11.0`, and publish the Starter release.
+4. Commit `main`, create a release tag such as `v0.13.0`, and publish the Starter release.
 
 ### CLI maintainers
 

package/dist/core/lockfile-peers.js

@@ -170,5 +170,20 @@ export function pruneOptionalPeers(source) {
         }
         output.push(line);
     }
-    return output.join("\n");
+    return closeEmptySnapshots(output).join("\n");
+}
+/**
+ * A snapshot whose only dependencies were removed links is left without a body, which pnpm reads
+ * as null and rejects as a broken lockfile; pnpm itself writes such entries as "key: {}".
+ */
+function closeEmptySnapshots(lines) {
+    let section = "";
+    return lines.map((line, index) => {
+        if (/^\S/.test(line))
+            section = line.replace(/:.*$/, "");
+        if (section !== "snapshots" || !/^ {2}\S.*:$/.test(line))
+            return line;
+        const next = lines.slice(index + 1).find((candidate) => candidate.trim() !== "");
+        return next === undefined || !/^ {4}/.test(next) ? `${line} {}` : line;
+    });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/create-clubedge-app",
-  "version": "0.12.0",
+  "version": "0.14.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.11.0",
-    "starterCommit": "b5637afcf3748e03bb7ecb1f1941a4e6c17cfa65"
+    "starterRef": "v0.13.0",
+    "starterCommit": "62fb8d1b1e13ed8e8e134bd1e53f2bfdde2c6a50"
   },
   "license": "Apache-2.0",
   "repository": {

package/template/.env.example

@@ -60,6 +60,30 @@ STRIPE_WEBHOOK_SECRET=
 STRIPE_PRICE_PRO=
 # clubedge:end
 
+# clubedge:if jobs=pg-boss
+# Background jobs are stored in DATABASE_URL and run by a worker inside the app server. Set
+# JOBS_WORKER=off where no server keeps running (it is off by default on Vercel and Netlify);
+# a scheduler then calls /api/jobs/run with CRON_SECRET (16 or more characters) instead.
+JOBS_WORKER=
+CRON_SECRET=
+# clubedge:end
+
+# clubedge:if observability=otel
+# OpenTelemetry: where traces and error logs go over OTLP/HTTP, such as a collector, Grafana
+# Cloud, or Honeycomb. Empty sends nothing. Headers are key=value pairs separated by commas.
+OTEL_EXPORTER_OTLP_ENDPOINT=
+OTEL_EXPORTER_OTLP_HEADERS=
+OTEL_SERVICE_NAME=
+# clubedge:end
+
+# clubedge:if observability=sentry
+# Sentry (https://sentry.io): the DSN from the project's Client Keys settings. Empty sends nothing.
+# The traces sample rate is the share of requests traced, from 0 to 1 (default 0.1).
+SENTRY_DSN=
+SENTRY_ENVIRONMENT=
+SENTRY_TRACES_SAMPLE_RATE=
+# clubedge:end
+
 # clubedge:if storage=s3
 # S3-compatible storage (AWS S3, Cloudflare R2, MinIO)
 STORAGE_BUCKET= # clubedge:only infra!=docker

package/template/README.md

@@ -28,6 +28,9 @@ This repository contains the same application for two frameworks, Next.js (`apps
 - 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 -->
 - Subscriptions with Stripe Checkout and the customer portal, kept in sync by verified webhooks, behind a provider-neutral payments interface. <!-- clubedge:only payments=stripe -->
+- 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 -->
+- Server error reporting and request tracing with OpenTelemetry, to any OTLP collector, behind a provider-neutral observability interface. <!-- clubedge:only observability=otel -->
+- Server error reporting and request tracing with Sentry, behind a provider-neutral observability interface. <!-- clubedge:only observability=sentry -->
 - Zod environment validation, security headers, structured errors, and `/api/health`.
 - Docker support, GitHub Actions CI, Vitest, Playwright, ESLint, and Prettier.
 - A production image that includes its own migrator (`node /app/migrate.mjs`), for running migrations before each release.
@@ -224,6 +227,11 @@ The TanStack Start app is `apps/start`, run with `pnpm --filter @clubedge/start
 - `packages/email-resend/`: Resend email provider <!-- clubedge:only email=resend -->
 - `packages/payments/`: `PaymentProvider` interface, billing logic, and the subscription tables <!-- clubedge:only payments!=none -->
 - `packages/payments-stripe/`: Stripe payment provider <!-- clubedge:only payments=stripe -->
+- `packages/jobs/`: `JobQueue` interface, job definitions, and an in-memory queue for tests <!-- clubedge:only jobs!=none -->
+- `packages/jobs-pg-boss/`: pg-boss job queue <!-- clubedge:only jobs=pg-boss -->
+- `packages/observability/`: `ObservabilityProvider` interface and an in-memory provider for tests <!-- clubedge:only observability!=none -->
+- `packages/observability-otel/`: OpenTelemetry provider (OTLP/HTTP traces and error logs) <!-- clubedge:only observability=otel -->
+- `packages/observability-sentry/`: Sentry provider <!-- clubedge:only observability=sentry -->
 - `packages/ui/`: shared shadcn/ui components, utilities, and global theme styles
 - `.github/`: CI workflow, issue forms, and pull request template
 - `SETUP.md`, `CONTRIBUTING.md`, `SECURITY.md`: setup, contribution, and security guides

package/template/SETUP.md

@@ -46,6 +46,9 @@ The variables are:
 - `SMTP_URL` and `EMAIL_FROM` (for sending email): see [Email](#email). <!-- clubedge:only email=smtp -->
 - `RESEND_API_KEY` and `EMAIL_FROM` (for sending email): see [Email](#email). <!-- clubedge:only email=resend -->
 - `STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET`, and `STRIPE_PRICE_<PLAN>` (for payments): see [Payments](#payments). <!-- clubedge:only payments=stripe -->
+- `JOBS_WORKER` and `CRON_SECRET` (optional): see [Background jobs](#background-jobs). <!-- clubedge:only jobs=pg-boss -->
+- `OTEL_EXPORTER_OTLP_ENDPOINT` (to send traces and errors): see [Observability](#observability). <!-- clubedge:only observability=otel -->
+- `SENTRY_DSN` (to send errors and traces): see [Observability](#observability). <!-- clubedge:only observability=sentry -->
 - `STORAGE_*` (for file storage): see [File storage](#file-storage). <!-- clubedge:only storage=s3 -->
 - `SUPABASE_STORAGE_BUCKET` (for file storage): see [File storage](#file-storage). <!-- clubedge:only storage=supabase -->
 
@@ -236,6 +239,65 @@ Turn on the customer portal in the dashboard's billing settings, so "Manage bill
 
 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:end -->
+<!-- clubedge:if jobs=pg-boss -->
+
+## Background jobs
+
+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.
+
+Define a job in `apps/web/src/jobs` and add it to the list in `apps/web/src/jobs/index.ts`:
+
+```ts
+import { defineJob } from "@clubedge/jobs";
+
+export const welcomeEmail = defineJob<{ userId: string }>({
+  name: "welcome-email",
+  retryLimit: 3,
+  async run({ userId }) {
+    // Look the user up and send the email.
+  },
+});
+```
+
+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.
+
+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.
+
+Jobs go through the provider-neutral `JobQueue` interface in `packages/jobs`. To use another queue, implement that interface in a new package and return it from `apps/web/src/server/jobs.ts`; job definitions, the routes, and the jobs card stay the same.
+
+<!-- clubedge:end -->
+<!-- clubedge:if observability!=none -->
+
+## Observability
+
+Server errors and traces go to the tool you chose. Errors that escape a page, route, server action, or server function are sent with the request's method and path, and so are errors the app handles and reports with `reportError` from `@clubedge/core`, such as a failed webhook, email, or background job. Every request is traced, and so are calls through the email, storage, and payments composition roots, as spans such as `email.send` and `storage.upload`. Wrap your own work with `traced("name", () => work())` from `@clubedge/core`. Until the tool is configured nothing is sent, and errors keep going to the server log.
+
+<!-- clubedge:end -->
+<!-- clubedge:if observability=otel -->
+
+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 -->
+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 -->
+
+To see traces during development, run [Jaeger](https://www.jaegertracing.io), set `OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318`, and open http://localhost:16686:
+
+```sh
+docker run --rm -p 16686:16686 -p 4318:4318 jaegertracing/jaeger:latest
+```
+
+<!-- clubedge:end -->
+<!-- clubedge:if observability=sentry -->
+
+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 -->
+
+<!-- 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.
+
+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:end -->
 <!-- clubedge:if storage!=none -->
 
@@ -338,6 +400,8 @@ Render runs `node /app/migrate.mjs` as the pre-deploy command before each deploy
 
 Vercel has no step that runs before a release, so the build command applies migrations (`pnpm db:migrate`) against the `DATABASE_URL` of the deployment's environment. Give Preview deployments their own database, or remove the migration step from `buildCommand` and run migrations yourself. Serverless functions open a connection per instance: use your provider's pooled connection URL (for example Supabase's transaction pooler or Neon's pooled endpoint).
 
+Vercel runs no worker for [background jobs](#background-jobs). Set `CRON_SECRET` and add `"crons": [{ "path": "/api/jobs/run", "schedule": "* * * * *" }]` to `vercel.json`; Vercel Cron sends the secret itself. Cron jobs more frequent than daily need a paid Vercel plan; otherwise call the endpoint from another scheduler. <!-- clubedge:only jobs=pg-boss -->
+
 <!-- clubedge:end -->
 <!-- clubedge:if deploy=netlify -->
 
@@ -346,6 +410,8 @@ Vercel has no step that runs before a release, so the build command applies migr
 
 Netlify has no step that runs before a release, so the build command applies migrations (`pnpm db:migrate`) against the `DATABASE_URL` of the deploy context. Give deploy previews their own database, or remove the migration step from the build command and run migrations yourself. Serverless functions open a connection per instance: use your provider's pooled connection URL (for example Supabase's transaction pooler or Neon's pooled endpoint).
 
+Netlify runs no worker for [background jobs](#background-jobs). Set `JOBS_WORKER=off` and `CRON_SECRET`, then call `/api/jobs/run` every minute from a [scheduled function](https://docs.netlify.com/build/functions/scheduled-functions/) or another scheduler, with the header `Authorization: Bearer <CRON_SECRET>`. <!-- clubedge:only jobs=pg-boss -->
+
 <!-- clubedge:end -->
 
 `.github/workflows/deploy.yml` deploys on demand: in GitHub, open Actions, then Deploy, then Run workflow.
@@ -371,6 +437,9 @@ Production needs these variables:
 - `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 -->
 - `REDIS_URL`, when you run more than one instance. <!-- clubedge:only cache=redis -->
+- `CRON_SECRET`, where no worker runs and a scheduler calls `/api/jobs/run`. <!-- clubedge:only jobs=pg-boss -->
+- `OTEL_EXPORTER_OTLP_ENDPOINT`, and `OTEL_EXPORTER_OTLP_HEADERS` if your collector needs a key. <!-- clubedge:only observability=otel -->
+- `SENTRY_DSN`, and `SENTRY_ENVIRONMENT` to tell environments apart. <!-- clubedge:only observability=sentry -->
 - The `STORAGE_*` variables for your S3-compatible bucket. <!-- clubedge:only storage=s3 -->
 - `SUPABASE_STORAGE_BUCKET`. <!-- clubedge:only storage=supabase -->
 

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

@@ -62,6 +62,30 @@ STRIPE_WEBHOOK_SECRET=
 STRIPE_PRICE_PRO=
 # clubedge:end
 
+# clubedge:if jobs=pg-boss
+# Background jobs are stored in DATABASE_URL and run by a worker inside the app server. Set
+# JOBS_WORKER=off where no server keeps running (it is off by default on Vercel and Netlify);
+# a scheduler then calls /api/jobs/run with CRON_SECRET (16 or more characters) instead.
+JOBS_WORKER=
+CRON_SECRET=
+# clubedge:end
+
+# clubedge:if observability=otel
+# OpenTelemetry: where traces and error logs go over OTLP/HTTP, such as a collector, Grafana
+# Cloud, or Honeycomb. Empty sends nothing. Headers are key=value pairs separated by commas.
+OTEL_EXPORTER_OTLP_ENDPOINT=
+OTEL_EXPORTER_OTLP_HEADERS=
+OTEL_SERVICE_NAME=
+# clubedge:end
+
+# clubedge:if observability=sentry
+# Sentry (https://sentry.io): the DSN from the project's Client Keys settings. Empty sends nothing.
+# The traces sample rate is the share of requests traced, from 0 to 1 (default 0.1).
+SENTRY_DSN=
+SENTRY_ENVIRONMENT=
+SENTRY_TRACES_SAMPLE_RATE=
+# clubedge:end
+
 # clubedge:if storage=s3
 # S3-compatible storage (AWS S3, Cloudflare R2, MinIO)
 STORAGE_BUCKET= # clubedge:only infra!=docker

package/template/apps/start/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/start",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "private": true,
   "license": "Apache-2.0",
   "type": "module",
@@ -22,6 +22,11 @@
     "@clubedge/email": "workspace:*",
     "@clubedge/email-resend": "workspace:*",
     "@clubedge/email-smtp": "workspace:*",
+    "@clubedge/jobs": "workspace:*",
+    "@clubedge/jobs-pg-boss": "workspace:*",
+    "@clubedge/observability": "workspace:*",
+    "@clubedge/observability-otel": "workspace:*",
+    "@clubedge/observability-sentry": "workspace:*",
     "@clubedge/payments": "workspace:*",
     "@clubedge/payments-stripe": "workspace:*",
     "@clubedge/storage": "workspace:*",

package/template/apps/start/src/components/jobs/jobs-card.tsx

@@ -0,0 +1,71 @@
+import { ListChecks } from "lucide-react";
+
+import type { JobsStatus } from "@/server/jobs.functions";
+import { Badge } from "@clubedge/ui/components/badge";
+import { Button } from "@clubedge/ui/components/button";
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from "@clubedge/ui/components/card";
+
+const timeFormat = new Intl.DateTimeFormat("en", { timeStyle: "medium", timeZone: "UTC" });
+
+/** Starts the sample job and lists the current user's recent runs. The form posts to /jobs/sample. */
+export function JobsCard({ status }: { status: JobsStatus }) {
+  const { jobs } = status;
+
+  return (
+    <Card className="gap-0 py-0" id="jobs">
+      <CardHeader className="flex-row items-start justify-between gap-3 border-b px-5 py-5 sm:px-6">
+        <div className="grid gap-1">
+          <CardTitle className="text-base">Background jobs</CardTitle>
+          <CardDescription>
+            {status.worker
+              ? "Work runs outside requests in this server's worker, with retries."
+              : "This server runs no worker: jobs run when /api/jobs/run is called."}
+          </CardDescription>
+        </div>
+        <span className="grid size-9 place-items-center rounded-lg bg-primary/10 text-primary">
+          <ListChecks aria-hidden="true" className="size-4" />
+        </span>
+      </CardHeader>
+      <CardContent className="grid gap-4 px-5 py-5 sm:px-6">
+        {jobs === null ? (
+          <p className="text-sm text-muted-foreground">
+            Jobs are unavailable: the database could not be reached.
+          </p>
+        ) : (
+          <>
+            <form action="/jobs/sample" method="post">
+              <Button type="submit" variant="outline">
+                Run a sample job
+              </Button>
+            </form>
+            {jobs.length === 0 ? (
+              <p className="text-sm text-muted-foreground">No jobs yet.</p>
+            ) : (
+              <ul aria-label="Recent jobs" className="grid gap-2">
+                {jobs.map((job) => (
+                  <li className="flex items-center justify-between gap-3 text-sm" key={job.id}>
+                    <span>
+                      {job.name}{" "}
+                      <span className="text-muted-foreground">
+                        {timeFormat.format(new Date(job.createdAt))} UTC
+                      </span>
+                    </span>
+                    <Badge variant={job.state === "completed" ? "default" : "secondary"}>
+                      {job.state}
+                    </Badge>
+                  </li>
+                ))}
+              </ul>
+            )}
+          </>
+        )}
+      </CardContent>
+    </Card>
+  );
+}

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

@@ -0,0 +1,7 @@
+import type { JobDefinition } from "@clubedge/jobs";
+import { sampleJob } from "./sample";
+
+export { sampleJob };
+
+/** Every job the worker runs. Define a job in this folder, then add it here. */
+export const jobs: JobDefinition[] = [sampleJob];

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

@@ -0,0 +1,10 @@
+import { defineJob } from "@clubedge/jobs";
+
+/** An example job that the dashboard can start; replace it with your own. */
+export const sampleJob = defineJob<{ requestedBy: string }>({
+  name: "sample",
+  async run({ requestedBy }, { attempt }) {
+    await new Promise((resolve) => setTimeout(resolve, 500));
+    return { message: `Hello, ${requestedBy}, from the jobs worker.`, attempt };
+  },
+});

package/template/apps/start/src/nitro/plugins/jobs.ts

@@ -0,0 +1,8 @@
+import { definePlugin } from "nitro";
+import { getJobs, startJobsWorker } from "@/server/jobs";
+
+/** Starts the background jobs worker with the server, and stops it with the server. */
+export default definePlugin((nitroApp) => {
+  startJobsWorker();
+  nitroApp.hooks.hook("close", () => getJobs().stop());
+});

package/template/apps/start/src/nitro/plugins/observability.ts

@@ -0,0 +1,10 @@
+import { definePlugin } from "nitro";
+import { startObservability } from "@/server/observability";
+
+/** Starts error reporting and tracing with the server, and sends what is buffered when it stops. */
+export default definePlugin((nitroApp) => {
+  const provider = startObservability();
+  nitroApp.hooks.hook("close", async () => {
+    await provider?.flush();
+  });
+});

package/template/apps/start/src/routes/api/jobs/run.ts

@@ -0,0 +1,28 @@
+import { timingSafeEqual } from "node:crypto";
+import { createFileRoute } from "@tanstack/react-router";
+import { getCronSecret, getJobs } from "@/server/jobs";
+
+function isAuthorized(request: Request, secret: string): boolean {
+  const given = Buffer.from(request.headers.get("authorization") ?? "");
+  const expected = Buffer.from(`Bearer ${secret}`);
+  return given.length === expected.length && timingSafeEqual(given, expected);
+}
+
+/**
+ * Runs the jobs that are due, for hosts without a long-running worker: call it on a schedule
+ * with `Authorization: Bearer $CRON_SECRET` (Vercel Cron sends that header itself).
+ */
+export const Route = createFileRoute("/api/jobs/run")({
+  server: {
+    handlers: {
+      GET: async ({ request }) => {
+        const secret = getCronSecret();
+        if (!secret) return Response.json({ error: "Not found" }, { status: 404 });
+        if (!isAuthorized(request, secret))
+          return Response.json({ error: "Unauthorized" }, { status: 401 });
+        const result = await getJobs().runDue();
+        return Response.json(result, { headers: { "Cache-Control": "no-store" } });
+      },
+    },
+  },
+});

package/template/apps/start/src/routes/api/webhooks/payments.ts

@@ -1,5 +1,6 @@
 import { createFileRoute } from "@tanstack/react-router";
 import { getBilling, isPaymentsConfigured, WebhookVerificationError } from "@/server/payments";
+import { reportError } from "@clubedge/core";
 
 /**
  * The payment provider's webhook. The body is read as raw text, because the signature covers
@@ -22,7 +23,7 @@ export const Route = createFileRoute("/api/webhooks/payments")({
           if (error instanceof WebhookVerificationError) {
             return Response.json({ error: "Invalid signature." }, { status: 400 });
           }
-          console.error("Payment webhook failed", error);
+          reportError(error, { message: "Payment webhook failed" });
           return Response.json({ error: "Webhook failed." }, { status: 500 });
         }
       },

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

@@ -51,6 +51,10 @@ import { getPageUser } from "@/server/auth.functions";
 import { BillingCard } from "@/components/billing/billing-card";
 import { getBillingStatus } from "@/server/billing.functions";
 // clubedge:end
+// clubedge:if jobs!=none
+import { JobsCard } from "@/components/jobs/jobs-card";
+import { getJobsStatus } from "@/server/jobs.functions";
+// clubedge:end
 import { AccountButton } from "@/components/dashboard/account-button";
 import { AppSidebar } from "@/components/dashboard/app-sidebar";
 import { ThemeToggle } from "@/components/theme/theme-toggle";
@@ -116,6 +120,9 @@ export const Route = createFileRoute("/dashboard")({
     // clubedge:if payments!=none
     billing: await getBillingStatus(),
     // clubedge:end
+    // clubedge:if jobs!=none
+    jobs: await getJobsStatus(),
+    // clubedge:end
   }),
   component: DashboardPage,
 });
@@ -257,6 +264,10 @@ function DashboardPage() {
           <BillingCard billing={data.billing} />
           {/* clubedge:end */}
 
+          {/* clubedge:if jobs!=none */}
+          <JobsCard status={data.jobs} />
+          {/* clubedge:end */}
+
           <section className="grid gap-6 xl:grid-cols-[1.1fr_0.9fr]" id="modules">
             <Card className="gap-0 py-0">
               <CardHeader className="flex-row items-start justify-between gap-3 border-b px-5 py-5 sm:px-6">

package/template/apps/start/src/routes/jobs/sample.ts

@@ -0,0 +1,11 @@
+import { createFileRoute } from "@tanstack/react-router";
+import { handleSampleJob } from "@/server/jobs-forms";
+
+export const Route = createFileRoute("/jobs/sample")({
+  server: {
+    handlers: {
+      GET: () => new Response(null, { status: 303, headers: { Location: "/dashboard" } }),
+      POST: () => handleSampleJob(),
+    },
+  },
+});

package/template/apps/start/src/server/auth-forms.ts

@@ -1,6 +1,6 @@
 import "@tanstack/react-start/server-only";
 import { z } from "zod";
-import { getClientIp, safeRedirectPath } from "@clubedge/core";
+import { getClientIp, safeRedirectPath, reportError } from "@clubedge/core";
 import { getAppUrl } from "@/env/server";
 import { loginUrl } from "@/lib/login-url";
 import { getAuth, isAuthConfigured } from "./auth";
@@ -49,7 +49,7 @@ async function isRateLimited(request: Request, action: "sign-in" | "sign-up" | "
     return !result.success;
   } catch (error) {
     // Fail open: an unavailable limiter backend should not lock every user out.
-    console.error("Rate limiter unavailable", error);
+    reportError(error, { message: "Rate limiter unavailable" });
     return false;
   }
 }
@@ -142,7 +142,7 @@ export async function handleResetPassword(request: Request): Promise<Response> {
     // A Supabase reset link signed the user in; sign out so the new password is used next.
     await auth.signOut();
   } catch (error) {
-    console.error("Sign-out after password reset failed", error);
+    reportError(error, { message: "Sign-out after password reset failed" });
   }
   return seeOther(loginUrl({ notice: "password-updated" }));
 }
@@ -152,7 +152,7 @@ export async function handleSignOut(): Promise<Response> {
   try {
     await getAuth().signOut();
   } catch (error) {
-    console.error("Sign-out failed", error);
+    reportError(error, { message: "Sign-out failed" });
   }
   return seeOther("/login");
 }

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

@@ -1,7 +1,7 @@
 import "@tanstack/react-start/server-only";
 import type { AuthProvider, AuthUser } from "@clubedge/auth";
 import { createSupabaseAuth, createSupabaseServerClient } from "@clubedge/auth-supabase";
-import { AppError } from "@clubedge/core";
+import { AppError, reportError } from "@clubedge/core";
 import { getSupabaseAuthEnv } from "@/env/auth";
 import { requestCookieStore } from "./cookies";
 
@@ -34,7 +34,7 @@ export async function refreshAuthSession(): Promise<void> {
     await getAuth().refreshSession();
   } catch (error) {
     // Pages still render; protected handlers re-check the user and reject when needed.
-    console.error("Session refresh failed", error);
+    reportError(error, { message: "Session refresh failed" });
   }
 }
 

package/template/apps/start/src/server/email.ts

@@ -3,6 +3,7 @@ import { z } from "zod";
 import { createConsoleEmail, type EmailProvider } from "@clubedge/email";
 import { createSmtpEmail } from "@clubedge/email-smtp";
 import { optional, parseEnv } from "@/env/server";
+import { withSpans } from "@clubedge/core";
 
 export type { EmailMessage, EmailProvider } from "@clubedge/email";
 
@@ -34,6 +35,6 @@ function resolveProvider(): EmailProvider {
 }
 
 /** The configured email provider, resolved on first use so imports stay side-effect free. */
-export const email: EmailProvider = {
+export const email: EmailProvider = withSpans("email", {
   send: (message) => resolveProvider().send(message),
-};
+});