@clubedge/create-clubedge-app 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 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.

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.13.0
         |
         v
-Clubedge Starter v0.11.0
-commit b5637afcf3748e03bb7ecb1f1941a4e6c17cfa65
+Clubedge Starter v0.12.0
+commit 445add73c3505cd8505faccb3b0b7061a29f5356
 ```
 
 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.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.11.0` tag is expected to resolve to commit
-`b5637afcf3748e03bb7ecb1f1941a4e6c17cfa65`. 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.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.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, 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, 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,7 @@ 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` |
 | `--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 +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.11.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
@@ -156,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.11.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.
@@ -207,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.11.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.12.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.11.0",
-    "starterCommit": "b5637afcf3748e03bb7ecb1f1941a4e6c17cfa65"
+    "starterRef": "v0.12.0",
+    "starterCommit": "445add73c3505cd8505faccb3b0b7061a29f5356"
   },
   "license": "Apache-2.0",
   "repository": {

package/template/.env.example

@@ -60,6 +60,14 @@ 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 storage=s3
 # S3-compatible storage (AWS S3, Cloudflare R2, MinIO)
 STORAGE_BUCKET= # clubedge:only infra!=docker

package/template/README.md

@@ -28,6 +28,7 @@ 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 -->
 - 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 +225,8 @@ 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/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,7 @@ 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 -->
 - `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 +237,33 @@ 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 storage!=none -->
 
@@ -338,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 -->
 
@@ -346,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.
@@ -371,6 +403,7 @@ 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 -->
 - 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,14 @@ 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 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.12.0",
   "private": true,
   "license": "Apache-2.0",
   "type": "module",
@@ -22,6 +22,8 @@
     "@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:*",

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/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/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/jobs-forms.ts

@@ -0,0 +1,17 @@
+import "@tanstack/react-start/server-only";
+import { sampleJob } from "@/jobs";
+import { getCurrentUser, isAuthConfigured } from "./auth";
+import { getJobs } from "./jobs";
+
+/** Who the sample job runs for: the signed-in user's email, or "anonymous". */
+export async function sampleJobRequester(): Promise<string> {
+  const user = isAuthConfigured() ? await getCurrentUser() : null;
+  return user?.email ?? "anonymous";
+}
+
+/** The jobs card's form: queues the sample job; repeated clicks within seconds are ignored. */
+export async function handleSampleJob(): Promise<Response> {
+  const requestedBy = await sampleJobRequester();
+  await getJobs().enqueue(sampleJob, { requestedBy }, { key: requestedBy, throttleSeconds: 2 });
+  return new Response(null, { status: 303, headers: { Location: "/dashboard" } });
+}

package/template/apps/start/src/server/jobs.functions.ts

@@ -0,0 +1,29 @@
+import { createServerFn } from "@tanstack/react-start";
+import { sampleJob } from "@/jobs";
+import { getJobs, isWorkerEnabled } from "./jobs";
+import { sampleJobRequester } from "./jobs-forms";
+
+/** What the dashboard's jobs card shows; serializable, so it can cross to the browser. */
+export const getJobsStatus = createServerFn({ method: "GET" }).handler(async () => {
+  const worker = isWorkerEnabled();
+  try {
+    const jobs = await getJobs().recent(sampleJob, {
+      data: { requestedBy: await sampleJobRequester() },
+      limit: 5,
+    });
+    return {
+      worker,
+      jobs: jobs.map(({ id, name, state, createdAt }) => ({
+        id,
+        name,
+        state,
+        createdAt: createdAt.toISOString(),
+      })),
+    };
+  } catch (error) {
+    console.error("Background jobs: could not list recent jobs.", error);
+    return { worker, jobs: null };
+  }
+});
+
+export type JobsStatus = Awaited<ReturnType<typeof getJobsStatus>>;

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

@@ -0,0 +1,59 @@
+import "@tanstack/react-start/server-only";
+import { z } from "zod";
+import type { JobQueue } from "@clubedge/jobs";
+import { createPgBossJobs } from "@clubedge/jobs-pg-boss";
+import { jobs } from "@/jobs";
+import { getServerEnv, optional, parseEnv } from "@/env/server";
+
+export type { JobRecord } from "@clubedge/jobs";
+
+// Jobs stored in the app's PostgreSQL through pg-boss, behind the provider-neutral JobQueue.
+const jobsEnvSchema = z.object({
+  JOBS_WORKER: optional(z.enum(["on", "off"])),
+  // Authorizes /api/jobs/run, which runs due jobs where no worker can; unset disables it.
+  CRON_SECRET: optional(z.string().min(16)),
+});
+
+const jobsEnv = () => parseEnv(jobsEnvSchema, "Jobs");
+
+/**
+ * Whether this server runs a worker. Serverless functions (Vercel, Netlify) stop between
+ * requests, so there jobs run when a scheduler calls /api/jobs/run instead.
+ */
+export function isWorkerEnabled(): boolean {
+  const { JOBS_WORKER } = jobsEnv();
+  if (JOBS_WORKER) return JOBS_WORKER === "on";
+  return !process.env.VERCEL && !process.env.AWS_LAMBDA_FUNCTION_NAME;
+}
+
+export function getCronSecret(): string | null {
+  return jobsEnv().CRON_SECRET || null;
+}
+
+const globalForJobs = globalThis as typeof globalThis & { clubedgeJobs?: JobQueue };
+
+/** One queue per process, shared with the worker and across dev reloads. */
+export function getJobs(): JobQueue {
+  if (globalForJobs.clubedgeJobs) return globalForJobs.clubedgeJobs;
+  const env = getServerEnv();
+  globalForJobs.clubedgeJobs = createPgBossJobs({
+    connectionString: env.DATABASE_URL,
+    jobs,
+    worker: isWorkerEnabled(),
+    maxConnections: env.NODE_ENV === "production" ? 4 : 2,
+  });
+  return globalForJobs.clubedgeJobs;
+}
+
+/** Starts the worker when this server should run one, retrying until the database answers. */
+export function startJobsWorker() {
+  if (!isWorkerEnabled()) return;
+  const start = () =>
+    getJobs()
+      .startWorker()
+      .catch((error: unknown) => {
+        console.error("Background jobs: the worker could not start, retrying in 5 seconds.", error);
+        setTimeout(start, 5_000).unref();
+      });
+  void start();
+}

package/template/apps/start/vite.config.ts

@@ -22,6 +22,7 @@ export default defineConfig(({ mode }) => {
     // Vite resolves externals from this app, so it is also a direct dependency here.
     environments: { ssr: { resolve: { external: ["use-sync-external-store"] } } },
     // The Start plugin must come before the React plugin.
-    plugins: [tailwindcss(), tanstackStart(), nitro(), viteReact()],
+    // Nitro runs the plugins in src/nitro/plugins once when the server starts.
+    plugins: [tailwindcss(), tanstackStart(), nitro({ serverDir: "./src/nitro" }), viteReact()],
   };
 });

package/template/apps/web/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/web",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "private": true,
   "license": "Apache-2.0",
   "scripts": {
@@ -21,6 +21,8 @@
     "@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:*",

package/template/apps/web/src/app/api/jobs/run/route.ts

@@ -0,0 +1,23 @@
+import { timingSafeEqual } from "node:crypto";
+import { getCronSecret, getJobs } from "@/server/jobs";
+
+export const dynamic = "force-dynamic";
+
+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 async function GET(request: 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/web/src/app/dashboard/_components/jobs-actions.ts

@@ -0,0 +1,14 @@
+"use server";
+
+import { revalidatePath } from "next/cache";
+import { sampleJob } from "@/jobs";
+import { getCurrentUser } from "@/server/auth";
+import { getJobs } from "@/server/jobs";
+
+/** Queues the sample job for the current user; repeated clicks within seconds are ignored. */
+export async function runSampleJob() {
+  const user = await getCurrentUser();
+  const requestedBy = user?.email ?? "anonymous";
+  await getJobs().enqueue(sampleJob, { requestedBy }, { key: requestedBy, throttleSeconds: 2 });
+  revalidatePath("/dashboard");
+}