@clubedge/create-clubedge-app 0.11.0 → 0.13.0

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to `create-clubedge-app` are documented here.
 
+## 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.
+- Test a payments project in CI and in the release smoke test, and add the payments module in the change-modules job.
+
 ## 0.11.0
 
 - Default to Starter `v0.10.0`, which adds the deploy module (`--deploy docker|fly|railway|render|vercel|netlify`), a migrator in the production image, a manual deploy workflow, and the `/api/ready` readiness endpoint. `--deploy` 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.11.0
+create-clubedge-app v0.13.0
         |
         v
-Clubedge Starter v0.10.0
-commit 9d8fec71b3851c2d615735fb37edb6bb0e568761
+Clubedge Starter v0.12.0
+commit 445add73c3505cd8505faccb3b0b7061a29f5356
 ```
 
 The current relationship is:
 
 | CLI release | Default Starter release | Meaning |
 | --- | --- | --- |
-| `create-clubedge-app@0.11.0` | `clubedge-starter@v0.10.0` | The CLI's required, tested default |
+| `create-clubedge-app@0.13.0` | `clubedge-starter@v0.12.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.10.0` tag is expected to resolve to commit
-`9d8fec71b3851c2d615735fb37edb6bb0e568761`. The CLI verifies this before
+The `v0.12.0` tag is expected to resolve to commit
+`445add73c3505cd8505faccb3b0b7061a29f5356`. 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.10.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.12.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, 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, 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    |
 | ----------- | ------------------------------------------ | ---------- |
@@ -93,6 +93,8 @@ Authentication, file storage, caching, email, local infrastructure, and deployme
 | `--storage` | `s3`, `supabase` (needs Supabase Auth), `none` | `s3`   |
 | `--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` |
 | `--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` |
 
@@ -138,7 +140,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.10.0
+pnpm dlx @clubedge/create-clubedge-app my-app --ref v0.12.0
 pnpm dlx @clubedge/create-clubedge-app my-app --ref <commit-sha>
 
 # Test local Starter changes before releasing them
@@ -155,7 +157,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.10.0 # or a specific tag, branch, or commit
+pnpm dlx @clubedge/create-clubedge-app upgrade --ref v0.12.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.
@@ -206,7 +208,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.10.0`, and publish the Starter release.
+4. Commit `main`, create a release tag such as `v0.12.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.11.0",
+  "version": "0.13.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.10.0",
-    "starterCommit": "9d8fec71b3851c2d615735fb37edb6bb0e568761"
+    "starterRef": "v0.12.0",
+    "starterCommit": "445add73c3505cd8505faccb3b0b7061a29f5356"
   },
   "license": "Apache-2.0",
   "repository": {

package/template/.env.example

@@ -51,6 +51,23 @@ RESEND_API_KEY=
 EMAIL_FROM=App <no-reply@example.com>
 # clubedge:end
 
+# clubedge:if payments=stripe
+# Stripe (https://dashboard.stripe.com/apikeys): use test-mode keys during development. The
+# webhook secret comes from `stripe listen` locally, or from the endpoint's settings in production.
+STRIPE_SECRET_KEY=
+STRIPE_WEBHOOK_SECRET=
+# The Stripe price for each plan in src/config/plans.ts (STRIPE_PRICE_<PLAN>).
+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 storage=s3
 # S3-compatible storage (AWS S3, Cloudflare R2, MinIO)
 STORAGE_BUCKET= # clubedge:only infra!=docker

package/template/README.md

@@ -27,6 +27,8 @@ This repository contains the same application for two frameworks, Next.js (`apps
 - Fixed-window rate limiter and cache in process memory, suited to a single server instance. <!-- clubedge:only cache=memory -->
 - 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 -->
 - 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.
@@ -221,6 +223,10 @@ The TanStack Start app is `apps/start`, run with `pnpm --filter @clubedge/start
 - `packages/email/`: `EmailProvider` interface with console and in-memory providers <!-- clubedge:only email!=none -->
 - `packages/email-smtp/`: SMTP email provider <!-- clubedge:only email=smtp -->
 - `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/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

@@ -45,6 +45,8 @@ The variables are:
 - `REDIS_URL` (optional): see [Redis](#redis). <!-- clubedge:only cache=redis -->
 - `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 -->
 - `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 -->
 
@@ -208,6 +210,60 @@ Set `RESEND_API_KEY` to a [Resend](https://resend.com) API key and `EMAIL_FROM`
 
 Without a provider configured, development prints each email to the server log, so you can open links from the terminal, and production refuses to send. `pnpm check:services` confirms that the provider accepts the settings without sending anything.
 
+<!-- clubedge:end -->
+<!-- clubedge:if payments!=none -->
+
+## Payments
+
+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:end -->
+<!-- clubedge:if payments=stripe -->
+
+[Stripe](https://stripe.com) runs checkout and billing management. In test mode:
+
+1. Copy the secret key from the dashboard's API keys into `STRIPE_SECRET_KEY`.
+2. Create a recurring price for each plan and put its id in `STRIPE_PRICE_<PLAN>`, such as `STRIPE_PRICE_PRO`.
+3. Forward webhooks to your machine with the [Stripe CLI](https://docs.stripe.com/stripe-cli), and put the signing secret it prints in `STRIPE_WEBHOOK_SECRET`:
+
+```sh
+stripe listen --forward-to localhost:3000/api/webhooks/payments
+```
+
+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.
+
+<!-- clubedge:end -->
+<!-- clubedge:if payments!=none -->
+
+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 storage!=none -->
 
@@ -310,6 +366,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 -->
 
@@ -318,6 +376,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.
@@ -341,7 +401,9 @@ Production needs these variables:
 - `BETTER_AUTH_SECRET`, at least 32 random characters, different from development. <!-- clubedge:only auth=better-auth -->
 - `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 -->
 - `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 -->
 - 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

@@ -53,6 +53,23 @@ RESEND_API_KEY=
 EMAIL_FROM=App <no-reply@example.com>
 # clubedge:end
 
+# clubedge:if payments=stripe
+# Stripe (https://dashboard.stripe.com/apikeys): use test-mode keys during development. The
+# webhook secret comes from `stripe listen` locally, or from the endpoint's settings in production.
+STRIPE_SECRET_KEY=
+STRIPE_WEBHOOK_SECRET=
+# The Stripe price for each plan in src/config/plans.ts (STRIPE_PRICE_<PLAN>).
+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 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.10.0",
+  "version": "0.12.0",
   "private": true,
   "license": "Apache-2.0",
   "type": "module",
@@ -22,6 +22,10 @@
     "@clubedge/email": "workspace:*",
     "@clubedge/email-resend": "workspace:*",
     "@clubedge/email-smtp": "workspace:*",
+    "@clubedge/jobs": "workspace:*",
+    "@clubedge/jobs-pg-boss": "workspace:*",
+    "@clubedge/payments": "workspace:*",
+    "@clubedge/payments-stripe": "workspace:*",
     "@clubedge/storage": "workspace:*",
     "@clubedge/storage-s3": "workspace:*",
     "@clubedge/storage-supabase": "workspace:*",

package/template/apps/start/scripts/check-services.ts

@@ -14,6 +14,9 @@ import { createSmtpEmail } from "@clubedge/email-smtp";
 // clubedge:if email=resend
 import { createResendEmail } from "@clubedge/email-resend";
 // clubedge:end
+// clubedge:if payments=stripe
+import { createStripePayments } from "@clubedge/payments-stripe";
+// clubedge:end
 // clubedge:if storage=s3 && infra=local
 import { createFileSystemStorage } from "@clubedge/storage/file-system";
 // clubedge:end
@@ -100,6 +103,23 @@ async function main() {
       },
     },
     // clubedge:end
+    // clubedge:if payments=stripe
+    {
+      name: "Payments (Stripe)",
+      skip: env.STRIPE_SECRET_KEY ? undefined : "STRIPE_SECRET_KEY is not set",
+      async run() {
+        // A read-only request that checks the key; nothing is charged or created.
+        const stripe = createStripePayments({
+          secretKey: env.STRIPE_SECRET_KEY!,
+          webhookSecret: env.STRIPE_WEBHOOK_SECRET || "unused",
+          prices: {},
+          apiBase: env.STRIPE_API_BASE || undefined,
+        });
+        await stripe.verify();
+        return "secret key accepted";
+      },
+    },
+    // clubedge:end
     // clubedge:if storage=s3 && infra=local
     {
       name: "Local folder storage",

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

@@ -0,0 +1,83 @@
+import { CreditCard } from "lucide-react";
+
+import { plans } from "@/config/plans";
+import type { BillingStatus } from "@/server/billing.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 dateFormat = new Intl.DateTimeFormat("en", { dateStyle: "medium", timeZone: "UTC" });
+
+/** The signed-in user's plan, with checkout or the billing portal. Forms post to /billing/*. */
+export function BillingCard({ billing }: { billing: BillingStatus }) {
+  const { subscription } = billing;
+
+  return (
+    <Card className="gap-0 py-0" id="billing">
+      <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">Billing</CardTitle>
+          <CardDescription>Your plan and payment details.</CardDescription>
+        </div>
+        <span className="grid size-9 place-items-center rounded-lg bg-primary/10 text-primary">
+          <CreditCard aria-hidden="true" className="size-4" />
+        </span>
+      </CardHeader>
+      <CardContent className="grid gap-4 px-5 py-5 sm:px-6">
+        {!billing.configured ? (
+          <p className="text-sm text-muted-foreground">
+            Payments are not configured yet. Set the Stripe variables in{" "}
+            <code className="rounded bg-muted px-1 py-0.5 font-mono text-xs">
+              apps/web/.env.local
+            </code>
+            .
+          </p>
+        ) : !billing.signedIn ? (
+          <p className="text-sm text-muted-foreground">Sign in to choose a plan.</p>
+        ) : subscription ? (
+          <>
+            <div className="flex flex-wrap items-center gap-2">
+              <span className="font-medium">{subscription.planName}</span>
+              <Badge variant={subscription.entitled ? "default" : "secondary"}>
+                {subscription.status.replace(/_/g, " ")}
+              </Badge>
+            </div>
+            {subscription.currentPeriodEnd && (
+              <p className="text-sm text-muted-foreground">
+                {subscription.cancelAtPeriodEnd ? "Ends" : "Renews"} on{" "}
+                {dateFormat.format(new Date(subscription.currentPeriodEnd))}.
+              </p>
+            )}
+            <form action="/billing/portal" method="post">
+              <Button type="submit" variant="outline">
+                Manage billing
+              </Button>
+            </form>
+          </>
+        ) : (
+          plans.map((plan) => (
+            <form
+              action="/billing/checkout"
+              className="flex flex-wrap items-center justify-between gap-3"
+              key={plan.id}
+              method="post"
+            >
+              <input name="planId" type="hidden" value={plan.id} />
+              <div className="grid gap-0.5">
+                <span className="font-medium">{plan.name}</span>
+                <span className="text-sm text-muted-foreground">{plan.description}</span>
+              </div>
+              <Button type="submit">Upgrade to {plan.name}</Button>
+            </form>
+          ))
+        )}
+      </CardContent>
+    </Card>
+  );
+}

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/config/plans.ts

@@ -0,0 +1,16 @@
+/**
+ * The plans users can subscribe to. Ids are the app's own: each payment provider maps them to
+ * its prices through environment variables, such as STRIPE_PRICE_PRO for the "pro" plan.
+ */
+export const plans = [
+  {
+    id: "pro",
+    name: "Pro",
+    description: "Everything in the free plan, plus the paid features you build.",
+  },
+] as const;
+
+export type PlanId = (typeof plans)[number]["id"];
+
+export const planName = (id: string | null) =>
+  plans.find((plan) => plan.id === id)?.name ?? "Unknown plan";

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/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

@@ -0,0 +1,31 @@
+import { createFileRoute } from "@tanstack/react-router";
+import { getBilling, isPaymentsConfigured, WebhookVerificationError } from "@/server/payments";
+
+/**
+ * The payment provider's webhook. The body is read as raw text, because the signature covers
+ * the exact bytes. Each event is applied once; failures answer 500 so the provider retries.
+ */
+export const Route = createFileRoute("/api/webhooks/payments")({
+  server: {
+    handlers: {
+      POST: async ({ request }) => {
+        if (!isPaymentsConfigured()) {
+          return Response.json({ error: "Payments are not configured." }, { status: 503 });
+        }
+        try {
+          const result = await getBilling().handleWebhook({
+            body: await request.text(),
+            headers: request.headers,
+          });
+          return Response.json({ received: true, result });
+        } catch (error) {
+          if (error instanceof WebhookVerificationError) {
+            return Response.json({ error: "Invalid signature." }, { status: 400 });
+          }
+          console.error("Payment webhook failed", error);
+          return Response.json({ error: "Webhook failed." }, { status: 500 });
+        }
+      },
+    },
+  },
+});

package/template/apps/start/src/routes/billing/checkout.ts

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