@clubedge/create-clubedge-app 0.30.1 → 0.31.0

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to `create-clubedge-app` are documented here.
 
+## 0.31.0
+
+- **Pluggable background jobs**: default to Starter `v0.20.0` (#91). The jobs module now has three providers behind one interface, so job definitions, routes, and the dashboard's jobs card stay the same whichever runs them:
+  - `--jobs pg-boss`: jobs in your PostgreSQL, run by a worker in the app server.
+  - **`--jobs bullmq`** (new): jobs in Redis through BullMQ 6, run by a worker in the app server. It needs `--cache redis`, so `deploy` creates Railway's Redis with it.
+  - **`--jobs inngest`** (new): Inngest calls the app's `/api/inngest` to run each job, so serverless hosts need no cron. `pnpm jobs:dev` starts its Dev Server, and `check:env` requires `INNGEST_EVENT_KEY` and `INNGEST_SIGNING_KEY` in production.
+  - `@clubedge/jobs/conformance` is one test suite every provider passes: retries, delays, throttling, timeouts, history, and the worker. SETUP.md shows how to add your own provider with it.
+  - `runDue`'s `failed` now counts every failed attempt, retries included, for every provider.
+  - Switch an existing project with `pnpm clubedge add jobs bullmq` or `pnpm clubedge add jobs inngest`.
+- The showcase's SaaS walkthrough waits for Stripe's billing portal to be on screen before moving on (#90). Stripe renders the portal's text under a spinner and fades it in, which Playwright counted as visible.
+
 ## 0.30.1
 
 Railway previews, fixed after running them for real on the Starter's own pull requests.

package/README.md

@@ -129,7 +129,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.19.1
+pnpm dlx @clubedge/create-clubedge-app my-app --ref v0.20.0
 pnpm dlx @clubedge/create-clubedge-app my-app --ref <commit-sha>
 
 # Test local Starter changes before releasing them
@@ -148,7 +148,7 @@ pnpm clubedge add email resend payments stripe              # several modules as
 pnpm clubedge remove storage payments
 pnpm dlx @clubedge/create-clubedge-app add infra local --dry-run
 pnpm dlx @clubedge/create-clubedge-app@latest upgrade        # to the newest CLI's Starter release
-pnpm dlx @clubedge/create-clubedge-app upgrade --ref v0.19.1 # or a specific tag, branch, or commit
+pnpm dlx @clubedge/create-clubedge-app upgrade --ref v0.20.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.
@@ -259,27 +259,27 @@ Projects created with `--infra neon` also have `.github/workflows/preview.yml`,
 Each CLI release is tested against one specific Starter release:
 
 ```text
-create-clubedge-app v0.30.1
+create-clubedge-app v0.31.0
         |
         v
-Clubedge Starter v0.19.1
-commit b113170a55a6d9990ca418f4968a7f50ebac1bca
+Clubedge Starter v0.20.0
+commit 166fd38a1b4e8e94e6c411ff26f978ed52ce1249
 ```
 
 The current relationship is:
 
 | CLI release | Default Starter release | Meaning |
 | --- | --- | --- |
-| `create-clubedge-app@0.30.1` | `clubedge-starter@v0.19.1` | The CLI's required, tested default |
+| `create-clubedge-app@0.31.0` | `clubedge-starter@v0.20.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.19.1` tag is expected to resolve to commit
-`b113170a55a6d9990ca418f4968a7f50ebac1bca`. The CLI verifies this before
+The `v0.20.0` tag is expected to resolve to commit
+`166fd38a1b4e8e94e6c411ff26f978ed52ce1249`. 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.19.1`. The CLI is then updated to use that release, all generated-project checks must pass, and a new CLI version is published. This keeps Starter and CLI releases independently versioned while preserving a tested compatibility relationship.
+When the Starter changes, its maintainers first publish a new versioned release, such as `v0.20.0`. The CLI is then updated to use that release, all generated-project checks must pass, and a new CLI version is published. This keeps Starter and CLI releases independently versioned while preserving a tested compatibility relationship.
 
 Every generated project records its CLI version, Starter repository, Starter ref, Starter commit, framework, and modules in `package.json` and `README.md`.
 
@@ -334,7 +334,7 @@ CI packs the CLI with `npm pack`, scaffolds clean projects from the packed tarba
 1. Make and validate changes in `clubedge-starter`.
 2. Run lint, typecheck, unit tests, browser tests, and production build.
 3. Update the Starter package versions.
-4. Commit `main`, create a release tag such as `v0.19.1`, and publish the Starter release.
+4. Commit `main`, create a release tag such as `v0.20.0`, and publish the Starter release.
 
 ### CLI maintainers
 
@@ -375,6 +375,7 @@ Each phase ends with a Starter release and a CLI release pinned to it. The full
 | 0.29.0 | v0.18.0 | `deploy` to Netlify and Render (experimental) |
 | 0.30.0 | v0.19.0 | `--infra neon` with a free Neon database, the `neon` command, `deploy --preview` with a Neon branch per preview |
 | 0.30.1 | v0.19.1 | Railway previews work with a workspace token and answer on the port their domain targets |
+| 0.31.0 | v0.20.0 | Pluggable background jobs: `--jobs bullmq` and `--jobs inngest` next to pg-boss, and a conformance suite every provider passes |
 | next | | Show the Starter's version of a conflicted file next to yours |
 
 ## Community

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/create-clubedge-app",
-  "version": "0.30.1",
+  "version": "0.31.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.19.1",
-    "starterCommit": "b113170a55a6d9990ca418f4968a7f50ebac1bca"
+    "starterRef": "v0.20.0",
+    "starterCommit": "166fd38a1b4e8e94e6c411ff26f978ed52ce1249"
   },
   "license": "Apache-2.0",
   "repository": {

package/template/.env.example

@@ -77,6 +77,24 @@ JOBS_WORKER=
 CRON_SECRET=
 # clubedge:end
 
+# clubedge:if jobs=bullmq
+# Background jobs are stored in Redis (REDIS_URL above) through BullMQ 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 jobs=inngest
+# Background jobs run by Inngest (https://www.inngest.com), which calls this app's /api/inngest.
+# In development, start its Dev Server with pnpm jobs:dev (http://localhost:8288); INNGEST_DEV=1
+# points the app at it. In production, remove INNGEST_DEV and set the keys of your Inngest app.
+INNGEST_DEV=1
+INNGEST_EVENT_KEY=
+INNGEST_SIGNING_KEY=
+# 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.

package/template/.github/workflows/ci.yml

@@ -9,8 +9,19 @@ permissions:
 jobs:
   verify:
     runs-on: ubuntu-24.04
+    # clubedge:if jobs=bullmq
+    # Redis for the BullMQ provider's tests, which run the jobs conformance suite against it.
+    services:
+      redis:
+        image: redis:7
+        ports:
+          - 6379:6379
+        options: >-
+          --health-cmd "redis-cli ping" --health-interval 5s --health-timeout 5s --health-retries 10
+    # clubedge:end
     env:
       DATABASE_URL: postgresql://postgres:postgres@127.0.0.1:5432/postgres
+      REDIS_URL: redis://127.0.0.1:6379 # clubedge:only jobs=bullmq
     steps:
       - uses: actions/checkout@v7
       - uses: pnpm/action-setup@v6

package/template/README.md

@@ -68,6 +68,8 @@ Every combination in the CI matrix is generated as a real project and runs its f
 - Fixed-window rate limiter and cache in process memory, suited to a single server instance. <!-- clubedge:only cache=memory -->
 - 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 -->
+- Background jobs with retries and schedules, stored in Redis by BullMQ and run by a worker inside the app server, behind a provider-neutral jobs interface. <!-- clubedge:only jobs=bullmq -->
+- Background jobs with retries and schedules, run by Inngest, which calls the app for each one, behind a provider-neutral jobs interface. <!-- clubedge:only jobs=inngest -->
 - 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 -->
 
@@ -100,7 +102,7 @@ Pick modules when you create a project, and change them later with `pnpm clubedg
 | Cache         | `redis`, `memory`                                         | `redis`    |
 | Email         | `smtp`, `resend`, `none`                                  | `smtp`     |
 | Payments      | `stripe`, `none`                                          | `none`     |
-| Jobs          | `pg-boss`, `none`                                         | `none`     |
+| Jobs          | `pg-boss`, `bullmq`, `inngest`, `none`                    | `none`     |
 | Observability | `otel`, `sentry`, `none`                                  | `none`     |
 | Local infra   | `docker`, `supabase`, `local` (no Docker), `neon`, `none` | `docker`   |
 | Deploy        | `docker`, `fly`, `railway`, `render`, `vercel`, `netlify` | `docker`   |
@@ -240,6 +242,14 @@ flowchart TB
   App -->|jobs interface, worker in the server| Jobs[pg-boss]
   Jobs -->|jobs table| DB
   %% clubedge:end
+  %% clubedge:if jobs=bullmq
+  App -->|jobs interface, worker in the server| Jobs[BullMQ]
+  Jobs -->|queues| Redis
+  %% clubedge:end
+  %% clubedge:if jobs=inngest
+  App -->|jobs interface, an event per job| Jobs[Inngest]
+  Jobs -->|calls /api/inngest to run each job| App
+  %% clubedge:end
   %% clubedge:if observability=otel
   App -->|traces and errors| Otel[OTLP collector]
   %% clubedge:end
@@ -348,8 +358,10 @@ 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/`: `JobQueue` interface, job definitions, an in-memory queue for tests, and the conformance suite every provider passes <!-- clubedge:only jobs!=none -->
 - `packages/jobs-pg-boss/`: pg-boss job queue <!-- clubedge:only jobs=pg-boss -->
+- `packages/jobs-bullmq/`: BullMQ job queue in Redis <!-- clubedge:only jobs=bullmq -->
+- `packages/jobs-inngest/`: Inngest jobs, and the handler for `/api/inngest` <!-- clubedge:only jobs=inngest -->
 - `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 -->

package/template/SETUP.md

@@ -47,7 +47,8 @@ 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 -->
+- `JOBS_WORKER` and `CRON_SECRET` (optional): see [Background jobs](#background-jobs). <!-- clubedge:only jobs=pg-boss|bullmq -->
+- `INNGEST_DEV`, `INNGEST_EVENT_KEY`, and `INNGEST_SIGNING_KEY`: see [Background jobs](#background-jobs). <!-- clubedge:only jobs=inngest -->
 - `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 -->
@@ -264,11 +265,13 @@ 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 -->
+<!-- clubedge:if jobs!=none -->
 
 ## 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.
+Jobs run outside requests, with retries, in a worker that starts inside the app server: `pnpm dev` and the production server both run it, so there is no separate process to deploy. [pg-boss](https://github.com/timgit/pg-boss) stores them in your PostgreSQL, and creates and upgrades its own tables in the `pgboss` schema when the app starts. <!-- clubedge:only jobs=pg-boss -->
+Jobs run outside requests, with retries, in a worker that starts inside the app server: `pnpm dev` and the production server both run it, so there is no separate process to deploy. [BullMQ](https://docs.bullmq.io) stores them in Redis (`REDIS_URL`, Redis 6.2 or newer), which the cache also uses; keep it on a Redis that doesn't evict keys, since jobs are data. <!-- clubedge:only jobs=bullmq -->
+[Inngest](https://www.inngest.com) runs the jobs: the app sends an event for each one, and Inngest calls the app's `/api/inngest` to run it, with retries and schedules, so nothing runs between requests and serverless hosts need no cron. In development, start Inngest's Dev Server next to `pnpm dev` with `pnpm jobs:dev`, and open its dashboard at <http://localhost:8288> to see every run; `INNGEST_DEV=1` points the app at it. In production, create an app in Inngest, set `INNGEST_EVENT_KEY` and `INNGEST_SIGNING_KEY`, remove `INNGEST_DEV`, and sync the deployed `/api/inngest` URL in Inngest's dashboard (Inngest's Vercel and Netlify integrations do it on each deploy). <!-- clubedge:only jobs=inngest -->
 
 Define a job in `apps/web/src/jobs` and add it to the list in `apps/web/src/jobs/index.ts`:
 
@@ -284,12 +287,21 @@ export const welcomeEmail = defineJob<{ userId: string }>({
 });
 ```
 
-Queue it from server code with `getJobs().enqueue(welcomeEmail, { userId })`, from `@/server/jobs`. To send any email in the background, enqueue `sendEmailJob` from `@/jobs` with the message, as the auth emails do. A thrown error fails the attempt and the job is retried (`retryLimit`, `retryDelaySeconds`, `retryBackoff`). An attempt that runs past `timeoutSeconds`, or whose server stops, is retried too, so make jobs safe to run twice. Add `schedule: "0 3 * * *"` (cron syntax) to run a job on a schedule. Restart `pnpm dev` after adding or changing a job. The dashboard's jobs card queues the sample job from `apps/web/src/jobs/sample.ts` and lists its recent runs; remove both when you add your own. <!-- clubedge:only email!=none -->
-Queue it from server code with `getJobs().enqueue(welcomeEmail, { userId })`, from `@/server/jobs`. A thrown error fails the attempt and the job is retried (`retryLimit`, `retryDelaySeconds`, `retryBackoff`). An attempt that runs past `timeoutSeconds`, or whose server stops, is retried too, so make jobs safe to run twice. Add `schedule: "0 3 * * *"` (cron syntax) to run a job on a schedule. Restart `pnpm dev` after adding or changing a job. The dashboard's jobs card queues the sample job from `apps/web/src/jobs/sample.ts` and lists its recent runs; remove both when you add your own. <!-- clubedge:only email=none -->
+Queue it from server code with `getJobs().enqueue(welcomeEmail, { userId })`, from `@/server/jobs`. To send any email in the background, enqueue `sendEmailJob` from `@/jobs` with the message, as the auth emails do. <!-- clubedge:only email!=none -->
+Queue it from server code with `getJobs().enqueue(welcomeEmail, { userId })`, from `@/server/jobs`. <!-- clubedge:only email=none -->
 
-Where no server keeps running, as on Vercel and Netlify, there is no worker: `JOBS_WORKER` defaults to `off` there, and you can set it yourself anywhere. Set `CRON_SECRET` to 16 or more random characters and call `GET /api/jobs/run` every minute or so with the header `Authorization: Bearer <CRON_SECRET>`, from Vercel Cron, a Netlify scheduled function, or any scheduler. Each call runs the jobs that are due. Scheduled jobs need a worker.
+A thrown error fails the attempt and the job is retried (`retryLimit`, `retryDelaySeconds`, `retryBackoff`). An attempt that runs past `timeoutSeconds`, or whose server stops, is retried too, so make jobs safe to run twice. Add `schedule: "0 3 * * *"` (cron syntax, UTC) to run a job on a schedule. Restart `pnpm dev` after adding or changing a job. The dashboard's jobs card queues the sample job from `apps/web/src/jobs/sample.ts` and lists its recent runs; remove both when you add your own.
 
-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.
+Where no server keeps running, as on Vercel and Netlify, there is no worker: `JOBS_WORKER` defaults to `off` there, and you can set it yourself anywhere. Set `CRON_SECRET` to 16 or more random characters and call `GET /api/jobs/run` every minute or so with the header `Authorization: Bearer <CRON_SECRET>`, from Vercel Cron, a Netlify scheduled function, or any scheduler. Each call runs the jobs that are due. <!-- clubedge:only jobs=pg-boss|bullmq -->
+Inngest keeps the job history: the jobs card reads it from Inngest's API (the Dev Server's locally), and Inngest's dashboard shows each run's attempts, output, and errors. <!-- clubedge:only jobs=inngest -->
+
+Jobs go through the provider-neutral `JobQueue` interface in `packages/jobs`, so job definitions, the routes, and the jobs card stay the same whichever provider runs them. Switch providers with `pnpm clubedge add jobs pg-boss`, `bullmq`, or `inngest`. To add another, implement `JobQueue` in a new package, return it from `apps/web/src/server/jobs.ts`, and prove it with the shared conformance suite, as each provider's tests do:
+
+```ts
+import { describeJobQueue } from "@clubedge/jobs/conformance";
+
+describeJobQueue("my-queue", (jobs, { worker }) => createMyQueue({ jobs, worker }));
+```
 
 <!-- clubedge:end -->
 <!-- clubedge:if observability!=none -->
@@ -433,7 +445,7 @@ Vercel only runs the app: the database, Redis, file storage, and email come from
 
 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 -->
+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|bullmq -->
 
 <!-- clubedge:end -->
 <!-- clubedge:if deploy=netlify -->
@@ -445,7 +457,7 @@ Netlify only runs the app: the database, Redis, file storage, and email come fro
 
 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 -->
+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|bullmq -->
 
 <!-- clubedge:end -->
 
@@ -489,7 +501,8 @@ 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 -->
+- `CRON_SECRET`, where no worker runs and a scheduler calls `/api/jobs/run`. <!-- clubedge:only jobs=pg-boss|bullmq -->
+- `INNGEST_EVENT_KEY` and `INNGEST_SIGNING_KEY`, from your Inngest app; `INNGEST_DEV` unset. <!-- clubedge:only jobs=inngest -->
 - `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 -->

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

@@ -79,6 +79,24 @@ JOBS_WORKER=
 CRON_SECRET=
 # clubedge:end
 
+# clubedge:if jobs=bullmq
+# Background jobs are stored in Redis (REDIS_URL above) through BullMQ 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 jobs=inngest
+# Background jobs run by Inngest (https://www.inngest.com), which calls this app's /api/inngest.
+# In development, start its Dev Server with pnpm jobs:dev (http://localhost:8288); INNGEST_DEV=1
+# points the app at it. In production, remove INNGEST_DEV and set the keys of your Inngest app.
+INNGEST_DEV=1
+INNGEST_EVENT_KEY=
+INNGEST_SIGNING_KEY=
+# 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.

package/template/apps/start/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/start",
-  "version": "0.19.1",
+  "version": "0.20.0",
   "private": true,
   "license": "Apache-2.0",
   "type": "module",
@@ -24,6 +24,8 @@
     "@clubedge/email-resend": "workspace:*",
     "@clubedge/email-smtp": "workspace:*",
     "@clubedge/jobs": "workspace:*",
+    "@clubedge/jobs-bullmq": "workspace:*",
+    "@clubedge/jobs-inngest": "workspace:*",
     "@clubedge/jobs-pg-boss": "workspace:*",
     "@clubedge/observability": "workspace:*",
     "@clubedge/observability-otel": "workspace:*",

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

@@ -11,6 +11,12 @@ import {
   CardTitle,
 } from "@clubedge/ui/components/card";
 
+const runnerDescriptions = {
+  worker: "Work runs outside requests in this server's worker, with retries.",
+  scheduler: "This server runs no worker: jobs run when /api/jobs/run is called.",
+  service: "A jobs service runs each job by calling this app, with retries.",
+};
+
 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. */
@@ -22,11 +28,7 @@ export function JobsCard({ status }: { status: JobsStatus }) {
       <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>
+          <CardDescription>{runnerDescriptions[status.runner]}</CardDescription>
         </div>
         <span className="grid size-9 place-items-center rounded-lg bg-primary/10 text-primary">
           <ListChecks aria-hidden="true" className="size-4" />

package/template/apps/start/src/env/production.test.ts

@@ -55,6 +55,14 @@ describe("production env check", () => {
     ).toEqual(["DATABASE_URL_DIRECT points at Neon's pooler: use the host without -pooler"]);
   });
 
+  const hasInngest = requiredVariables({}).some(({ key }) => key === "INNGEST_SIGNING_KEY");
+  it.runIf(hasInngest)("refuses Inngest's Dev Server in production", () => {
+    expect(checkProductionEnv({ ...complete(), INNGEST_DEV: "1" }).invalid).toEqual([
+      "INNGEST_DEV is set: production uses Inngest Cloud's keys, so remove it",
+    ]);
+    expect(checkProductionEnv({ ...complete(), INNGEST_DEV: "0" }).invalid).toEqual([]);
+  });
+
   it("rejects a URL that isn't absolute", () => {
     const env = { ...complete(), APP_URL: "my-app.vercel.app" };
     expect(checkProductionEnv(env).invalid).toEqual(["APP_URL is not an absolute URL"]);

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

@@ -45,10 +45,14 @@ export function requiredVariables(env: Env): Requirement[] {
     { key: "STRIPE_WEBHOOK_SECRET", use: "payments" },
     { key: "STRIPE_PRICE_PRO", use: "payments" },
     // clubedge:end
-    // clubedge:if jobs=pg-boss
+    // clubedge:if jobs=pg-boss|bullmq
     // No jobs worker runs there: Vercel Cron or another scheduler calls /api/jobs/run with it.
     { key: "CRON_SECRET", use: "background jobs, run by a cron", serverless: true },
     // clubedge:end
+    // clubedge:if jobs=inngest
+    { key: "INNGEST_EVENT_KEY", use: "background jobs (Inngest's event key)" },
+    { key: "INNGEST_SIGNING_KEY", use: "background jobs (Inngest's signing key)" },
+    // clubedge:end
   ];
   const serverless = Boolean(env.VERCEL || env.NETLIFY);
   return required.filter((requirement) => serverless || !requirement.serverless);
@@ -95,6 +99,12 @@ export function checkProductionEnv(env: Env): ProductionEnvCheck {
       invalid.push("DATABASE_URL_DIRECT points at Neon's pooler: use the host without -pooler");
     }
   }
+  // clubedge:if jobs=inngest
+  // The Dev Server only runs on a developer's machine: production talks to Inngest Cloud.
+  if (env.INNGEST_DEV?.trim() && !/^(0|false)$/i.test(env.INNGEST_DEV.trim())) {
+    invalid.push("INNGEST_DEV is set: production uses Inngest Cloud's keys, so remove it");
+  }
+  // clubedge:end
   // clubedge:if auth=better-auth
   const secret = env.BETTER_AUTH_SECRET?.trim();
   if (secret && secret.length < 32) invalid.push("BETTER_AUTH_SECRET needs at least 32 characters");

package/template/apps/start/src/routes/api/inngest.ts

@@ -0,0 +1,16 @@
+import { createFileRoute } from "@tanstack/react-router";
+import { getJobs } from "@/server/jobs";
+
+/**
+ * Inngest calls this endpoint to find the app's jobs (GET, PUT) and to run each one (POST). Its
+ * signing key authenticates the calls; providers that run jobs themselves answer 404.
+ */
+async function handle({ request }: { request: Request }): Promise<Response> {
+  const jobs = getJobs();
+  if (!jobs.handler) return Response.json({ error: "Not found" }, { status: 404 });
+  return await jobs.handler(request);
+}
+
+export const Route = createFileRoute("/api/inngest")({
+  server: { handlers: { GET: handle, POST: handle, PUT: handle } },
+});

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

@@ -1,19 +1,19 @@
 import { createServerFn } from "@tanstack/react-start";
 import { sampleJob } from "@/jobs";
-import { getJobs, isWorkerEnabled } from "./jobs";
+import { getJobs, jobsRunner } from "./jobs";
 import { sampleJobRequester } from "./jobs-forms";
 import { reportError } from "@clubedge/core";
 
 /** 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();
+  const runner = jobsRunner();
   try {
     const jobs = await getJobs().recent(sampleJob, {
       data: { requestedBy: await sampleJobRequester() },
       limit: 5,
     });
     return {
-      worker,
+      runner,
       jobs: jobs.map(({ id, name, state, createdAt }) => ({
         id,
         name,
@@ -23,7 +23,7 @@ export const getJobsStatus = createServerFn({ method: "GET" }).handler(async ()
     };
   } catch (error) {
     reportError(error, { message: "Background jobs: could not list recent jobs." });
-    return { worker, jobs: null };
+    return { runner, jobs: null };
   }
 });
 

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

@@ -28,6 +28,14 @@ export function isWorkerEnabled(): boolean {
   return !process.env.VERCEL && !process.env.AWS_LAMBDA_FUNCTION_NAME;
 }
 
+/**
+ * How this server's jobs run, for the dashboard: in its own worker, when a scheduler calls
+ * /api/jobs/run, or by a jobs service that calls the app.
+ */
+export function jobsRunner(): "worker" | "scheduler" | "service" {
+  return isWorkerEnabled() ? "worker" : "scheduler";
+}
+
 export function getCronSecret(): string | null {
   return jobsEnv().CRON_SECRET || null;
 }

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

@@ -0,0 +1,88 @@
+import "@tanstack/react-start/server-only";
+import { z } from "zod";
+import type { JobQueue } from "@clubedge/jobs";
+import { createBullMqJobs } from "@clubedge/jobs-bullmq";
+import { jobs } from "@/jobs";
+import { getServerEnv, optional, parseEnv } from "@/env/server";
+import { reportError } from "@clubedge/core";
+
+export type { JobRecord } from "@clubedge/jobs";
+
+// Jobs stored in Redis through BullMQ, behind the provider-neutral JobQueue.
+const jobsEnvSchema = z.object({
+  REDIS_URL: z.string().min(1, "REDIS_URL is required for background jobs"),
+  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;
+}
+
+/**
+ * How this server's jobs run, for the dashboard: in its own worker, when a scheduler calls
+ * /api/jobs/run, or by a jobs service that calls the app.
+ */
+export function jobsRunner(): "worker" | "scheduler" | "service" {
+  return isWorkerEnabled() ? "worker" : "scheduler";
+}
+
+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 = createBullMqJobs({
+    redisUrl: jobsEnv().REDIS_URL,
+    jobs,
+    worker: isWorkerEnabled(),
+    concurrency: env.NODE_ENV === "production" ? 4 : 1,
+    onError: (error, context) =>
+      reportError(error, {
+        message: context ? `Background job "${context.job}" failed` : "Background jobs error",
+        attributes: context,
+      }),
+  });
+  return globalForJobs.clubedgeJobs;
+}
+
+/** Starts the worker when this server should run one, retrying until Redis answers. */
+export function startJobsWorker() {
+  let jobs: JobQueue;
+  try {
+    if (!isWorkerEnabled()) return;
+    jobs = getJobs();
+  } catch (error) {
+    // Invalid configuration, such as a missing REDIS_URL, is reported once; the rest of the app
+    // keeps serving instead of failing to start.
+    reportError(error, { message: "Background jobs: the worker did not start." });
+    return;
+  }
+  const start = () =>
+    jobs.startWorker().catch((error: unknown) => {
+      reportError(error, {
+        message: "Background jobs: the worker could not start, retrying in 5 seconds.",
+      });
+      setTimeout(start, 5_000).unref();
+    });
+  void start();
+}
+
+/** Stops the worker, if this process created a queue. */
+export async function stopJobsWorker() {
+  await globalForJobs.clubedgeJobs?.stop();
+}