@clubedge/create-clubedge-app 0.30.1 → 0.32.0

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 All notable changes to `create-clubedge-app` are documented here.
 
+## 0.32.0
+
+- **Pluggable authentication**: default to Starter `v0.21.0` (#93). Authentication now has four providers behind one interface, so the pages, settings, payments, and jobs stay the same whichever signs users in:
+  - `--auth supabase` and `--auth better-auth`, as before.
+  - **`--auth firebase`** (new): Firebase Authentication from the server, with session cookies. `pnpm auth:dev` starts the Auth Emulator, so development needs no Firebase account. Reset and confirmation emails go through the app's email module.
+  - **`--auth appwrite`** (new): Appwrite accounts on Appwrite Cloud or your own server, with session cookies and an API key. Appwrite sends its own emails.
+  - `@clubedge/auth/conformance` is one test suite every auth provider passes: sign-up and sign-in, sign-out, reset through the emailed link, password changes that sign out other sessions, and account deletion. The Starter's CI runs it against all four, including Appwrite Cloud.
+  - Stripe payments work with every provider.
+  - Switch an existing project with `pnpm clubedge add auth firebase` or `pnpm clubedge add auth appwrite`. After `pnpm clubedge upgrade`, run `pnpm db:migrate`: `users.auth_user_id` becomes text, since Firebase's and Appwrite's user ids aren't UUIDs.
+
+## 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.21.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.21.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.32.0
         |
         v
-Clubedge Starter v0.19.1
-commit b113170a55a6d9990ca418f4968a7f50ebac1bca
+Clubedge Starter v0.21.0
+commit 8f1201f2d526347ccf0365a701aaa20e883f8d8a
 ```
 
 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.32.0` | `clubedge-starter@v0.21.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.21.0` tag is expected to resolve to commit
+`8f1201f2d526347ccf0365a701aaa20e883f8d8a`. 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.21.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.21.0`, and publish the Starter release.
 
 ### CLI maintainers
 
@@ -375,6 +375,8 @@ 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 |
+| 0.32.0 | v0.21.0 | Pluggable authentication: `--auth firebase` and `--auth appwrite` next to Supabase and Better Auth, 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.32.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.21.0",
+    "starterCommit": "8f1201f2d526347ccf0365a701aaa20e883f8d8a"
   },
   "license": "Apache-2.0",
   "repository": {

package/template/.env.example

@@ -35,6 +35,27 @@ BETTER_AUTH_SECRET=
 BETTER_AUTH_REQUIRE_EMAIL_VERIFICATION=false # clubedge:only email!=none
 # clubedge:end
 
+# clubedge:if auth=firebase
+# Firebase Authentication. In development, pnpm auth:dev starts the Auth Emulator, which these
+# values point at. In production, set your project's id and Web API key (Project settings,
+# General) and a service account (Project settings, Service accounts), and remove
+# FIREBASE_AUTH_EMULATOR_HOST.
+FIREBASE_PROJECT_ID=demo-clubedge
+FIREBASE_API_KEY=demo-api-key
+FIREBASE_CLIENT_EMAIL=
+FIREBASE_PRIVATE_KEY=
+FIREBASE_AUTH_EMULATOR_HOST=127.0.0.1:9099
+# clubedge:end
+
+# clubedge:if auth=appwrite
+# Appwrite (https://appwrite.io), on Appwrite Cloud or your own server. Create a project, add a
+# Web platform for this app's hostname (localhost in development), and an API key with the
+# sessions.write and users.write scopes. Appwrite sends its own emails (its SMTP settings).
+APPWRITE_ENDPOINT=https://cloud.appwrite.io/v1
+APPWRITE_PROJECT_ID=
+APPWRITE_API_KEY=
+# clubedge:end
+
 # clubedge:if cache=redis
 # Optional cache and rate limits (Redis protocol; rediss:// enables TLS). Without it, both use
 # process memory. Upstash example: rediss://default:YOUR_PASSWORD@your-database.upstash.io:6379
@@ -77,6 +98,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,21 @@ 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
+      FIREBASE_AUTH_EMULATOR_HOST: 127.0.0.1:9099 # clubedge:only auth=firebase
+      FIREBASE_PROJECT_ID: demo-clubedge # clubedge:only auth=firebase
     steps:
       - uses: actions/checkout@v7
       - uses: pnpm/action-setup@v6
@@ -22,6 +35,15 @@ jobs:
       - run: pnpm format:check
       - run: pnpm lint
       - run: pnpm typecheck
+      # clubedge:if auth=firebase
+      # Firebase's Auth Emulator (firebase.json), for the Firebase provider's conformance tests.
+      - name: Start the Firebase Auth Emulator
+        run: |
+          nohup npx --yes firebase-tools@15 emulators:start --only auth --project demo-clubedge \
+            > "$RUNNER_TEMP/firebase.log" 2>&1 &
+          timeout 240 bash -c 'until curl --silent --output /dev/null http://127.0.0.1:9099/; do sleep 2; done' \
+            || { cat "$RUNNER_TEMP/firebase.log"; exit 1; }
+      # clubedge:end
       - run: pnpm test
       # Build the way the app is developed: with the env example copied into place.
       - run: cp .env.example apps/web/.env.local

package/template/README.md

@@ -57,6 +57,8 @@ Every combination in the CI matrix is generated as a real project and runs its f
 
 - Supabase Auth with server-verified sessions in secure cookies, a protected dashboard, and rate-limited sign-in. <!-- clubedge:only auth=supabase -->
 - Better Auth with users and sessions in your own PostgreSQL, secure session cookies, a protected dashboard, and rate-limited sign-in. <!-- clubedge:only auth=better-auth -->
+- Firebase Authentication through the app's own pages, with server-side session cookies, a protected dashboard, and rate-limited sign-in; the Auth Emulator in development. <!-- clubedge:only auth=firebase -->
+- Appwrite accounts through the app's own pages, on Appwrite Cloud or your own server, with server-side session cookies, a protected dashboard, and rate-limited sign-in. <!-- clubedge:only auth=appwrite -->
 - Password reset by email, and email verification that can be required before sign-in. <!-- clubedge:only auth=better-auth && email!=none -->
 - Password reset by email, sent by Supabase. <!-- clubedge:only auth=supabase -->
 - An account settings page: display name, password change, and account deletion. <!-- clubedge:only auth!=none -->
@@ -68,6 +70,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 -->
 
@@ -95,12 +99,12 @@ Pick modules when you create a project, and change them later with `pnpm clubedg
 | Module        | Options                                                   | Default    |
 | ------------- | --------------------------------------------------------- | ---------- |
 | Framework     | `next`, `tanstack-start`                                  | `next`     |
-| Auth          | `supabase`, `better-auth`, `none`                         | `supabase` |
+| Auth          | `supabase`, `better-auth`, `firebase`, `appwrite`, `none` | `supabase` |
 | Storage       | `s3`, `supabase`, `none`                                  | `s3`       |
 | 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`   |
@@ -217,6 +221,12 @@ flowchart TB
   App -->|auth interface and server sessions| Auth[Better Auth]
   Auth -->|users and sessions| DB
   %% clubedge:end
+  %% clubedge:if auth=firebase
+  App -->|auth interface and server sessions| Auth[Firebase Authentication]
+  %% clubedge:end
+  %% clubedge:if auth=appwrite
+  App -->|auth interface and server sessions| Auth[Appwrite]
+  %% clubedge:end
   %% clubedge:if cache=redis
   App -->|cache and rate limits| Redis[(Redis, or memory)]
   %% clubedge:end
@@ -240,6 +250,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
@@ -338,6 +356,8 @@ The TanStack Start app is `apps/start`, run with `pnpm --filter @clubedge/start
 - `packages/auth/`: `AuthProvider` and `CookieStore` interfaces <!-- clubedge:only auth!=none -->
 - `packages/auth-supabase/`: Supabase Auth adapter <!-- clubedge:only auth=supabase -->
 - `packages/auth-better-auth/`: Better Auth adapter, with its own tables and migrations <!-- clubedge:only auth=better-auth -->
+- `packages/auth-firebase/`: Firebase Authentication adapter, with session cookies <!-- clubedge:only auth=firebase -->
+- `packages/auth-appwrite/`: Appwrite adapter, with session cookies <!-- clubedge:only auth=appwrite -->
 - `packages/storage/`: `StorageProvider` interface <!-- clubedge:only storage!=none -->
 - `packages/storage-s3/`: S3-compatible storage adapter <!-- clubedge:only storage=s3 -->
 - `packages/storage-supabase/`: Supabase Storage adapter <!-- clubedge:only storage=supabase -->
@@ -348,8 +368,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

@@ -43,11 +43,14 @@ The variables are:
 - `NEXT_PUBLIC_SUPABASE_URL` and `NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY` (for sign-in): see [Supabase Auth](#supabase-auth). <!-- clubedge:only framework=next && auth=supabase -->
 - `SUPABASE_URL` and `SUPABASE_PUBLISHABLE_KEY` (for sign-in): see [Supabase Auth](#supabase-auth). <!-- clubedge:only framework=tanstack-start && auth=supabase -->
 - `BETTER_AUTH_SECRET` (for sign-in): see [Better Auth](#better-auth). <!-- clubedge:only auth=better-auth -->
+- `FIREBASE_PROJECT_ID`, `FIREBASE_API_KEY`, and in production a service account: see [Firebase Authentication](#firebase-authentication). <!-- clubedge:only auth=firebase -->
+- `APPWRITE_ENDPOINT`, `APPWRITE_PROJECT_ID`, and `APPWRITE_API_KEY` (for sign-in): see [Appwrite](#appwrite). <!-- clubedge:only auth=appwrite -->
 - `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 -->
+- `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 -->
@@ -102,6 +105,41 @@ These emails are sent by the `send-email` [background job](#background-jobs), so
 
 <!-- clubedge:end -->
 
+<!-- clubedge:if auth=firebase -->
+
+## Firebase Authentication
+
+[Firebase Authentication](https://firebase.google.com/docs/auth) checks passwords and keeps the accounts; the app's own pages sign users in, and the server holds the session in an HTTP-only cookie (a Firebase session cookie, checked for revocation on each request). Password reset and email confirmation links are generated by Firebase and sent through the [email module](#email), so they open the app's own pages and need no setup in the Firebase console. <!-- clubedge:only email!=none -->
+[Firebase Authentication](https://firebase.google.com/docs/auth) checks passwords and keeps the accounts; the app's own pages sign users in, and the server holds the session in an HTTP-only cookie (a Firebase session cookie, checked for revocation on each request). Without the email module there is no password reset. <!-- clubedge:only email=none -->
+
+In development, `pnpm auth:dev` starts Firebase's Auth Emulator (`firebase.json`, port 9099), which the example environment points at: no Firebase project or account is needed. Accounts live in memory until it stops.
+
+In production:
+
+1. In the [Firebase console](https://console.firebase.google.com), create a project and turn on **Email/Password** under Authentication, Sign-in method.
+2. Set `FIREBASE_PROJECT_ID` and `FIREBASE_API_KEY` (the Web API key, under Project settings, General).
+3. Under Project settings, Service accounts, generate a private key, and set `FIREBASE_CLIENT_EMAIL` and `FIREBASE_PRIVATE_KEY` from it (the key's line breaks as `\n` are fine).
+4. Remove `FIREBASE_AUTH_EMULATOR_HOST`; `pnpm check:env` refuses it in production.
+
+Changing a password or resetting it signs out every other session; deleting an account removes it from Firebase after the app's own data for the user.
+
+<!-- clubedge:end -->
+
+<!-- clubedge:if auth=appwrite -->
+
+## Appwrite
+
+[Appwrite](https://appwrite.io) keeps the accounts, on Appwrite Cloud or your own server; the app's own pages sign users in, and the server holds the session's secret in an HTTP-only cookie (`a_session_<project>`). Appwrite sends the email confirmation and password recovery emails itself, through its SMTP settings, with links back to the app's `/auth/callback` and `/reset-password`.
+
+1. Create a project in [Appwrite Cloud](https://cloud.appwrite.io) (free tier) or on your Appwrite server.
+2. Under Overview, Platforms, add a **Web** platform for the app's hostname: `localhost` in development, your domain in production. Appwrite only sends links to registered hostnames.
+3. Under Overview, Integrations, API keys, create a key with the `sessions.write` and `users.write` scopes.
+4. Set `APPWRITE_ENDPOINT` (such as `https://cloud.appwrite.io/v1`), `APPWRITE_PROJECT_ID`, and `APPWRITE_API_KEY`. The key stays on the server.
+
+Changing or resetting a password signs out every other session; deleting an account removes the Appwrite user after the app's own data for them. A self-hosted Appwrite sends email only once its SMTP settings (`_APP_SMTP_HOST` and the rest) are set.
+
+<!-- clubedge:end -->
+
 ## Local services
 
 <!-- clubedge:if infra=docker -->
@@ -264,11 +302,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 +324,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 +482,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 +494,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 +538,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

@@ -37,6 +37,27 @@ BETTER_AUTH_SECRET=
 BETTER_AUTH_REQUIRE_EMAIL_VERIFICATION=false # clubedge:only email!=none
 # clubedge:end
 
+# clubedge:if auth=firebase
+# Firebase Authentication. In development, pnpm auth:dev starts the Auth Emulator, which these
+# values point at. In production, set your project's id and Web API key (Project settings,
+# General) and a service account (Project settings, Service accounts), and remove
+# FIREBASE_AUTH_EMULATOR_HOST.
+FIREBASE_PROJECT_ID=demo-clubedge
+FIREBASE_API_KEY=demo-api-key
+FIREBASE_CLIENT_EMAIL=
+FIREBASE_PRIVATE_KEY=
+FIREBASE_AUTH_EMULATOR_HOST=127.0.0.1:9099
+# clubedge:end
+
+# clubedge:if auth=appwrite
+# Appwrite (https://appwrite.io), on Appwrite Cloud or your own server. Create a project, add a
+# Web platform for this app's hostname (localhost in development), and an API key with the
+# sessions.write and users.write scopes. Appwrite sends its own emails (its SMTP settings).
+APPWRITE_ENDPOINT=https://cloud.appwrite.io/v1
+APPWRITE_PROJECT_ID=
+APPWRITE_API_KEY=
+# clubedge:end
+
 # clubedge:if cache=redis
 # Optional cache and rate limits (Redis protocol; rediss:// enables TLS). Without it, both use
 # process memory. Upstash example: rediss://default:YOUR_PASSWORD@your-database.upstash.io:6379
@@ -79,6 +100,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.21.0",
   "private": true,
   "license": "Apache-2.0",
   "type": "module",
@@ -14,7 +14,9 @@
   },
   "dependencies": {
     "@clubedge/auth": "workspace:*",
+    "@clubedge/auth-appwrite": "workspace:*",
     "@clubedge/auth-better-auth": "workspace:*",
+    "@clubedge/auth-firebase": "workspace:*",
     "@clubedge/auth-supabase": "workspace:*",
     "@clubedge/cache": "workspace:*",
     "@clubedge/cache-redis": "workspace:*",
@@ -24,6 +26,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/auth.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { optional, parseEnv } from "./server";
-// clubedge:if auth=better-auth
+// clubedge:if auth=better-auth|firebase|appwrite
 import { getAppUrl } from "./server";
 // clubedge:end
 
@@ -60,3 +60,68 @@ export function getBetterAuthEnv(): BetterAuthEnv | null {
   };
 }
 // clubedge:end
+
+// clubedge:if auth=firebase
+const firebaseAuthSchema = z.object({
+  FIREBASE_PROJECT_ID: optional(z.string()),
+  // The project's Web API key: Project settings, General.
+  FIREBASE_API_KEY: optional(z.string()),
+  // A service account: Project settings, Service accounts. Not needed with the emulator.
+  FIREBASE_CLIENT_EMAIL: optional(z.string()),
+  FIREBASE_PRIVATE_KEY: optional(z.string()),
+  // The Auth Emulator (pnpm auth:dev) in development, such as 127.0.0.1:9099.
+  FIREBASE_AUTH_EMULATOR_HOST: optional(z.string()),
+});
+
+export interface FirebaseAuthEnv {
+  projectId: string;
+  apiKey: string;
+  clientEmail?: string;
+  privateKey?: string;
+  emulatorHost?: string;
+  baseUrl: string;
+}
+
+/** Firebase Auth settings, or null until the project id and Web API key are set. */
+export function getFirebaseAuthEnv(): FirebaseAuthEnv | null {
+  const env = parseEnv(firebaseAuthSchema, "Firebase Auth");
+  if (!env.FIREBASE_PROJECT_ID || !env.FIREBASE_API_KEY) return null;
+  return {
+    projectId: env.FIREBASE_PROJECT_ID,
+    apiKey: env.FIREBASE_API_KEY,
+    ...(env.FIREBASE_CLIENT_EMAIL ? { clientEmail: env.FIREBASE_CLIENT_EMAIL } : {}),
+    ...(env.FIREBASE_PRIVATE_KEY ? { privateKey: env.FIREBASE_PRIVATE_KEY } : {}),
+    ...(env.FIREBASE_AUTH_EMULATOR_HOST ? { emulatorHost: env.FIREBASE_AUTH_EMULATOR_HOST } : {}),
+    baseUrl: getAppUrl(),
+  };
+}
+// clubedge:end
+
+// clubedge:if auth=appwrite
+const appwriteAuthSchema = z.object({
+  // The API endpoint, such as https://cloud.appwrite.io/v1 or your server's /v1.
+  APPWRITE_ENDPOINT: optional(z.url()),
+  APPWRITE_PROJECT_ID: optional(z.string()),
+  // An API key with the sessions.write and users.write scopes (Overview, Integrations, API keys).
+  APPWRITE_API_KEY: optional(z.string()),
+});
+
+export interface AppwriteAuthEnv {
+  endpoint: string;
+  projectId: string;
+  apiKey: string;
+  baseUrl: string;
+}
+
+/** Appwrite settings, or null until the endpoint, project, and API key are set. */
+export function getAppwriteAuthEnv(): AppwriteAuthEnv | null {
+  const env = parseEnv(appwriteAuthSchema, "Appwrite");
+  if (!env.APPWRITE_ENDPOINT || !env.APPWRITE_PROJECT_ID || !env.APPWRITE_API_KEY) return null;
+  return {
+    endpoint: env.APPWRITE_ENDPOINT,
+    projectId: env.APPWRITE_PROJECT_ID,
+    apiKey: env.APPWRITE_API_KEY,
+    baseUrl: getAppUrl(),
+  };
+}
+// clubedge:end

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"]);