@clubedge/create-clubedge-app 0.10.0 → 0.12.0

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to `create-clubedge-app` are documented here.
 
+## 0.12.0
+
+- Default to Starter `v0.11.0`, which adds payments (`--payments stripe`): Stripe Checkout, the customer portal, and verified webhooks behind a provider-neutral payments interface. `--payments` needs no CLI code: it comes from the Starter's manifest.
+- Test a payments project in CI and in the release smoke test, and add the payments module in the change-modules job.
+
+## 0.11.0
+
+- Default to Starter `v0.10.0`, which adds the deploy module (`--deploy docker|fly|railway|render|vercel|netlify`), a migrator in the production image, a manual deploy workflow, and the `/api/ready` readiness endpoint. `--deploy` needs no CLI code: it comes from the Starter's manifest.
+- Test Fly.io and Vercel projects in CI and a Netlify project in the release smoke test.
+
 ## 0.10.0
 
 - Default to Starter `v0.9.0`, which adds the email module (`--email smtp|resend|none`), password reset for both auth providers, and email verification for Better Auth. `--email` 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.10.0
+create-clubedge-app v0.12.0
         |
         v
-Clubedge Starter v0.9.0
-commit e858d0b5b60bbb05f1b6aed3f4d9e841ea2df2a5
+Clubedge Starter v0.11.0
+commit b5637afcf3748e03bb7ecb1f1941a4e6c17cfa65
 ```
 
 The current relationship is:
 
 | CLI release | Default Starter release | Meaning |
 | --- | --- | --- |
-| `create-clubedge-app@0.10.0` | `clubedge-starter@v0.9.0` | The CLI's required, tested default |
+| `create-clubedge-app@0.12.0` | `clubedge-starter@v0.11.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.9.0` tag is expected to resolve to commit
-`e858d0b5b60bbb05f1b6aed3f4d9e841ea2df2a5`. The CLI verifies this before
+The `v0.11.0` tag is expected to resolve to commit
+`b5637afcf3748e03bb7ecb1f1941a4e6c17cfa65`. 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.9.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.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.
 
 ## 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, and local infrastructure 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, local infrastructure, and deployment are modules. Each has a default, and anything you leave out is removed completely: its package, its provider SDK, its environment variables, its documentation, and its lockfile entries. The Starter's `clubedge.template.json` defines the modules, so a module a newer Starter adds gets its `--<module>` flag without a CLI change; `--help` lists the modules of the Starter this CLI release creates.
 
 | Flag        | Options                                    | Default    |
 | ----------- | ------------------------------------------ | ---------- |
@@ -93,6 +93,8 @@ Authentication, file storage, caching, email, and local infrastructure are modul
 | `--storage` | `s3`, `supabase` (needs Supabase Auth), `none` | `s3`   |
 | `--cache`   | `redis` (falls back to memory without `REDIS_URL`), `memory` | `redis` |
 | `--email`   | `smtp` (any provider, or a local inbox), `resend`, `none` | `smtp` |
+| `--payments` | `stripe`, `none` (needs an auth module) | `none` |
+| `--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` |
 
 ```sh
@@ -137,7 +139,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.9.0
+pnpm dlx @clubedge/create-clubedge-app my-app --ref v0.11.0
 pnpm dlx @clubedge/create-clubedge-app my-app --ref <commit-sha>
 
 # Test local Starter changes before releasing them
@@ -154,7 +156,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.9.0  # or a specific tag, branch, or commit
+pnpm dlx @clubedge/create-clubedge-app upgrade --ref v0.11.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.
@@ -205,7 +207,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.9.0`, and publish the Starter release.
+4. Commit `main`, create a release tag such as `v0.11.0`, and publish the Starter release.
 
 ### CLI maintainers
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/create-clubedge-app",
-  "version": "0.10.0",
+  "version": "0.12.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.9.0",
-    "starterCommit": "e858d0b5b60bbb05f1b6aed3f4d9e841ea2df2a5"
+    "starterRef": "v0.11.0",
+    "starterCommit": "b5637afcf3748e03bb7ecb1f1941a4e6c17cfa65"
   },
   "license": "Apache-2.0",
   "repository": {

package/template/.env.example

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

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

@@ -58,10 +58,28 @@ jobs:
 
   docker:
     runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:17
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: app
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready --health-interval 5s --health-timeout 5s --health-retries 10
     steps:
       - uses: actions/checkout@v4
       - name: Build the production image
         run: docker build --tag app:ci .
+      - name: Run the image's migrations twice; the second run changes nothing
+        run: |
+          set -euo pipefail
+          for run in 1 2; do
+            docker run --rm --network host               --env DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:5432/app               app:ci node /app/migrate.mjs
+          done
+          PGPASSWORD=postgres psql --host 127.0.0.1 --username postgres --dbname app             --command "select count(*) from public.users"
       - name: Start the image and check health
         run: |
           set -euo pipefail

package/template/.github/workflows/deploy.yml

@@ -0,0 +1,109 @@
+# Deploys on demand: Actions > Deploy > Run workflow. SETUP.md lists the secrets it needs.
+name: Deploy
+on:
+  workflow_dispatch:
+permissions:
+  contents: read
+concurrency:
+  group: deploy
+  cancel-in-progress: false
+jobs:
+  # clubedge:if deploy=docker
+  # Builds the production image and publishes it to this repository's GitHub Container Registry
+  # as ghcr.io/<owner>/<repository>, tagged with the commit and latest. No secret is needed.
+  image:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: docker/setup-buildx-action@v3
+      - uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/${{ github.repository }}
+          tags: |
+            type=sha
+            type=raw,value=latest
+      - uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+  # clubedge:end
+  # clubedge:if deploy=fly
+  fly:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: superfly/flyctl-actions/setup-flyctl@master
+      # Builds on Fly's builders and runs the release command (migrations) before switching.
+      - run: flyctl deploy --remote-only
+        env:
+          FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}
+  # clubedge:end
+  # clubedge:if deploy=railway
+  railway:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      # Uploads this checkout; Railway builds the image and runs the pre-deploy migrations.
+      - run: npx --yes @railway/cli@4 up --ci --service "$RAILWAY_SERVICE"
+        env:
+          RAILWAY_TOKEN: ${{ secrets.RAILWAY_TOKEN }}
+          RAILWAY_SERVICE: ${{ vars.RAILWAY_SERVICE }}
+  # clubedge:end
+  # clubedge:if deploy=render
+  render:
+    runs-on: ubuntu-latest
+    steps:
+      # The service's deploy hook starts a deploy of its branch, with its pre-deploy migrations.
+      - run: curl --fail --silent --show-error --request POST "$RENDER_DEPLOY_HOOK_URL"
+        env:
+          RENDER_DEPLOY_HOOK_URL: ${{ secrets.RENDER_DEPLOY_HOOK_URL }}
+  # clubedge:end
+  # clubedge:if deploy=vercel
+  vercel:
+    runs-on: ubuntu-latest
+    env:
+      VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
+      VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
+      VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+      # Builds here with the project's production settings and variables (including the
+      # migrations in its build command), then uploads the result.
+      - run: npx --yes vercel@latest pull --yes --environment=production --token="$VERCEL_TOKEN"
+      - run: npx --yes vercel@latest build --prod --token="$VERCEL_TOKEN"
+      - run: npx --yes vercel@latest deploy --prebuilt --prod --token="$VERCEL_TOKEN"
+  # clubedge:end
+  # clubedge:if deploy=netlify
+  netlify:
+    runs-on: ubuntu-latest
+    env:
+      NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
+      NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      # Builds with netlify.toml (including its migrations) and the site's variables, then deploys.
+      - run: npx --yes netlify-cli@latest deploy --build --prod
+        working-directory: apps/web
+  # clubedge:end

package/template/Dockerfile

@@ -18,6 +18,10 @@ COPY --from=deps /app/ .
 COPY --from=pruner /app/out/full/ .
 COPY tsconfig.base.json ./
 RUN pnpm build
+# The production migrator (node /app/migrate.mjs): one bundled file plus every package's
+# migrations, so release commands can migrate before a new version starts.
+COPY scripts/migrate.mjs scripts/build-migrator.mjs ./scripts/
+RUN node scripts/build-migrator.mjs /app/.migrator
 
 FROM node:22-alpine AS runner
 ENV NODE_ENV=production NEXT_TELEMETRY_DISABLED=1 HOSTNAME=0.0.0.0 PORT=3000
@@ -26,6 +30,7 @@ RUN addgroup --system --gid 1001 nodejs && adduser --system --uid 1001 nextjs
 COPY --from=builder --chown=nextjs:nodejs /app/apps/web/.next/standalone ./
 COPY --from=builder --chown=nextjs:nodejs /app/apps/web/public ./apps/web/public
 COPY --from=builder --chown=nextjs:nodejs /app/apps/web/.next/static ./apps/web/.next/static
+COPY --from=builder --chown=nextjs:nodejs /app/.migrator ./
 WORKDIR /app/apps/web
 USER nextjs
 EXPOSE 3000

package/template/README.md

@@ -27,8 +27,16 @@ This repository contains the same application for two frameworks, Next.js (`apps
 - Fixed-window rate limiter and cache in process memory, suited to a single server instance. <!-- clubedge:only cache=memory -->
 - Email over SMTP, for any provider or a local inbox; development prints emails to the server log until SMTP is configured. <!-- clubedge:only email=smtp -->
 - Email through Resend; development prints emails to the server log until the API key is set. <!-- clubedge:only email=resend -->
+- Subscriptions with Stripe Checkout and the customer portal, kept in sync by verified webhooks, behind a provider-neutral payments interface. <!-- clubedge:only payments=stripe -->
 - 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.
+- A manual deploy workflow for the chosen platform, and a readiness endpoint (`/api/ready`) that checks the database.
+- Deployment to Fly.io with `fly.toml`: migrations run as the release command. <!-- clubedge:only deploy=fly -->
+- Deployment to Railway with `railway.json`: migrations run before each deploy. <!-- clubedge:only deploy=railway -->
+- Deployment to Render with a `render.yaml` Blueprint: migrations run before each deploy. <!-- clubedge:only deploy=render -->
+- Deployment to Vercel with `apps/web/vercel.json`: migrations run during the build. <!-- clubedge:only deploy=vercel -->
+- Deployment to Netlify with `apps/web/netlify.toml`: migrations run during the build. <!-- clubedge:only deploy=netlify -->
 
 ## Architecture
 
@@ -214,6 +222,8 @@ The TanStack Start app is `apps/start`, run with `pnpm --filter @clubedge/start
 - `packages/email/`: `EmailProvider` interface with console and in-memory providers <!-- clubedge:only email!=none -->
 - `packages/email-smtp/`: SMTP email provider <!-- clubedge:only email=smtp -->
 - `packages/email-resend/`: Resend email provider <!-- clubedge:only email=resend -->
+- `packages/payments/`: `PaymentProvider` interface, billing logic, and the subscription tables <!-- clubedge:only payments!=none -->
+- `packages/payments-stripe/`: Stripe payment provider <!-- clubedge:only payments=stripe -->
 - `packages/ui/`: shared shadcn/ui components, utilities, and global theme styles
 - `.github/`: CI workflow, issue forms, and pull request template
 - `SETUP.md`, `CONTRIBUTING.md`, `SECURITY.md`: setup, contribution, and security guides

package/template/SETUP.md

@@ -45,6 +45,7 @@ The variables are:
 - `REDIS_URL` (optional): see [Redis](#redis). <!-- clubedge:only cache=redis -->
 - `SMTP_URL` and `EMAIL_FROM` (for sending email): see [Email](#email). <!-- clubedge:only email=smtp -->
 - `RESEND_API_KEY` and `EMAIL_FROM` (for sending email): see [Email](#email). <!-- clubedge:only email=resend -->
+- `STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET`, and `STRIPE_PRICE_<PLAN>` (for payments): see [Payments](#payments). <!-- clubedge:only payments=stripe -->
 - `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 -->
 
@@ -56,7 +57,7 @@ Start the development server:
 pnpm dev
 ```
 
-The app is available at <http://localhost:3000> and the liveness endpoint at <http://localhost:3000/api/health>.
+The app is available at <http://localhost:3000>, the liveness endpoint at <http://localhost:3000/api/health>, and the readiness endpoint, which also checks the database, at <http://localhost:3000/api/ready>.
 
 <!-- clubedge:if auth=supabase -->
 
@@ -208,6 +209,33 @@ Set `RESEND_API_KEY` to a [Resend](https://resend.com) API key and `EMAIL_FROM`
 
 Without a provider configured, development prints each email to the server log, so you can open links from the terminal, and production refuses to send. `pnpm check:services` confirms that the provider accepts the settings without sending anything.
 
+<!-- clubedge:end -->
+<!-- clubedge:if payments!=none -->
+
+## Payments
+
+The plans users can buy are in `apps/web/src/config/plans.ts`, with the app's own ids. The dashboard's billing card offers checkout for each plan, then shows the subscription and opens billing management. Server code reads a user's plan with `getBilling().subscriptionFor(userId)` and `isEntitled` from `@/server/payments`, and the `subscriptions` table keeps it in sync through the provider's webhook at `/api/webhooks/payments`.
+
+<!-- clubedge:end -->
+<!-- clubedge:if payments=stripe -->
+
+[Stripe](https://stripe.com) runs checkout and billing management. In test mode:
+
+1. Copy the secret key from the dashboard's API keys into `STRIPE_SECRET_KEY`.
+2. Create a recurring price for each plan and put its id in `STRIPE_PRICE_<PLAN>`, such as `STRIPE_PRICE_PRO`.
+3. Forward webhooks to your machine with the [Stripe CLI](https://docs.stripe.com/stripe-cli), and put the signing secret it prints in `STRIPE_WEBHOOK_SECRET`:
+
+```sh
+stripe listen --forward-to localhost:3000/api/webhooks/payments
+```
+
+Turn on the customer portal in the dashboard's billing settings, so "Manage billing" works. In production, add a webhook endpoint for `https://<your-domain>/api/webhooks/payments` with the events `checkout.session.completed` and `customer.subscription.created`, `.updated`, `.deleted`, `.paused`, and `.resumed`, and use its signing secret. Every webhook's signature is verified, each event is applied once, and subscription events read the subscription's current state from Stripe, so retried or out-of-order deliveries are safe.
+
+<!-- clubedge:end -->
+<!-- clubedge:if payments!=none -->
+
+Payments go through the provider-neutral `PaymentProvider` interface in `packages/payments`. To use another provider, implement that interface in a new package and return it from `apps/web/src/server/payments.ts`; billing logic, the tables, the routes, and the billing card stay the same.
+
 <!-- clubedge:end -->
 <!-- clubedge:if storage!=none -->
 
@@ -262,6 +290,90 @@ pnpm docker:start
 The image runs the Next.js standalone output as an unprivileged user. Ensure the configured database and provider hosts are reachable from the container. <!-- clubedge:only framework=next -->
 The image runs the self-contained Nitro server bundle as an unprivileged user, with no `node_modules`. Ensure the configured database and provider hosts are reachable from the container. <!-- clubedge:only framework=tanstack-start -->
 
+The image also contains the production migrator, which applies every package's migrations with only `DATABASE_URL`:
+
+```sh
+docker run --rm --env DATABASE_URL="postgresql://..." <image> node /app/migrate.mjs
+```
+
+Run it before a new version starts serving; it skips migrations that are already applied.
+
+## Deploy
+
+<!-- clubedge:if deploy=docker -->
+
+Run the production image on any host or orchestrator that runs containers: build it with `pnpm docker:build` or in CI, push it to a registry, and start it with the production environment. Before each release, run the migrator above as a one-off task (a Kubernetes Job, an ECS task, or `docker run`), then roll out the new containers. Point the platform's health check at `/api/health`.
+
+<!-- clubedge:end -->
+<!-- clubedge:if deploy=fly -->
+
+`fly.toml` deploys the production image to [Fly.io](https://fly.io):
+
+```sh
+fly launch --no-deploy        # creates the app; keep the existing fly.toml
+fly secrets set DATABASE_URL="postgresql://..."
+fly deploy
+```
+
+Set the other production variables listed below with `fly secrets set`. Each deploy runs `node /app/migrate.mjs` as its release command, in a temporary machine, before the new version replaces the old one; a failed migration stops the deploy. Health checks call `/api/health`.
+
+<!-- clubedge:end -->
+<!-- clubedge:if deploy=railway -->
+
+`railway.json` deploys the production image to [Railway](https://railway.com): create a project from this repository, add the production variables listed below to the service, and deploy. Railway runs `node /app/migrate.mjs` as the pre-deploy command, so a failed migration stops the release, and checks `/api/health` before switching traffic.
+
+<!-- clubedge:end -->
+<!-- clubedge:if deploy=render -->
+
+`render.yaml` is a [Render](https://render.com) Blueprint: in the dashboard, choose New, then Blueprint, and select this repository. Render asks for each variable marked `sync: false` and generates `BETTER_AUTH_SECRET`. <!-- clubedge:only auth=better-auth -->
+`render.yaml` is a [Render](https://render.com) Blueprint: in the dashboard, choose New, then Blueprint, and select this repository. Render asks for each variable marked `sync: false`. <!-- clubedge:only auth!=better-auth -->
+
+Render runs `node /app/migrate.mjs` as the pre-deploy command before each deploy goes live, and a failed migration stops the deploy. Pre-deploy commands need a paid instance type. On the free type, remove `preDeployCommand` from `render.yaml` and apply migrations yourself before deploying, from your machine or CI, with `DATABASE_URL` set to the production database: `pnpm db:migrate`, or the migrator in the image as shown above. Health checks call `/api/health`.
+
+<!-- clubedge:end -->
+<!-- clubedge:if deploy=vercel -->
+
+`apps/web/vercel.json` deploys the app to [Vercel](https://vercel.com). Import the repository, set the project's Root Directory to `apps/web`, add the production variables listed below, and deploy. Vercel installs the whole pnpm workspace and builds the app. <!-- clubedge:only framework=next -->
+`apps/web/vercel.json` deploys the app to [Vercel](https://vercel.com). Import the repository, set the project's Root Directory to `apps/web`, add the production variables listed below, and deploy. The build detects Vercel and writes Vercel's Build Output, with server routes as functions. <!-- clubedge:only framework=tanstack-start -->
+
+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).
+
+<!-- clubedge:end -->
+<!-- clubedge:if deploy=netlify -->
+
+`apps/web/netlify.toml` deploys the app to [Netlify](https://www.netlify.com). Import the repository, set the site's Base directory to `apps/web`, add the production variables listed below, and deploy. Netlify installs its Next.js runtime automatically. <!-- clubedge:only framework=next -->
+`apps/web/netlify.toml` deploys the app to [Netlify](https://www.netlify.com). Import the repository, set the site's Base directory to `apps/web`, add the production variables listed below, and deploy. The build detects Netlify and writes its functions and static assets. <!-- clubedge:only framework=tanstack-start -->
+
+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).
+
+<!-- clubedge:end -->
+
+`.github/workflows/deploy.yml` deploys on demand: in GitHub, open Actions, then Deploy, then Run workflow.
+
+- It builds the production image and publishes it to this repository's GitHub Container Registry as `ghcr.io/<owner>/<repository>`, tagged with the commit and `latest`, using the workflow's own token. Run the migrator from that image before rolling it out. <!-- clubedge:only deploy=docker -->
+- It needs the secret `FLY_API_TOKEN`, from `fly tokens create deploy`. <!-- clubedge:only deploy=fly -->
+- It needs the secret `RAILWAY_TOKEN`, a project token from the project's settings, and the variable `RAILWAY_SERVICE`, the service's name. <!-- clubedge:only deploy=railway -->
+- It needs the secret `RENDER_DEPLOY_HOOK_URL`, the deploy hook from the service's settings. <!-- clubedge:only deploy=render -->
+- It needs the secrets `VERCEL_TOKEN`, from your account settings, and `VERCEL_ORG_ID` and `VERCEL_PROJECT_ID`, which `vercel link` writes to `.vercel/project.json`. <!-- clubedge:only deploy=vercel -->
+- It needs the secrets `NETLIFY_AUTH_TOKEN`, a personal access token, and `NETLIFY_SITE_ID`, from the site's settings. <!-- clubedge:only deploy=netlify -->
+
+`/api/health` answers as long as the app runs, so platforms use it to decide whether to restart the app. `/api/ready` also checks that the database answers, returning 200 or 503 without details: point load balancers and readiness probes at it, so traffic waits while the database is unreachable instead of the app restarting.
+
+Production needs these variables:
+
+- `DATABASE_URL`, pointing at a managed PostgreSQL database.
+- `NEXT_PUBLIC_APP_URL`, the deployed origin. <!-- clubedge:only framework=next -->
+- `APP_URL`, the deployed origin. <!-- clubedge:only framework=tanstack-start -->
+- `NEXT_PUBLIC_SUPABASE_URL` and `NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY`, from the Supabase project. <!-- clubedge:only framework=next && auth=supabase -->
+- `SUPABASE_URL` and `SUPABASE_PUBLISHABLE_KEY`, from the Supabase project. <!-- clubedge:only framework=tanstack-start && auth=supabase -->
+- `BETTER_AUTH_SECRET`, at least 32 random characters, different from development. <!-- clubedge:only auth=better-auth -->
+- `SMTP_URL` and `EMAIL_FROM`; without them, production refuses to send email. <!-- clubedge:only email=smtp -->
+- `RESEND_API_KEY` and `EMAIL_FROM`; without them, production refuses to send email. <!-- clubedge:only email=resend -->
+- `STRIPE_SECRET_KEY` (live mode), `STRIPE_WEBHOOK_SECRET` from the production webhook endpoint, and `STRIPE_PRICE_<PLAN>` for each plan. <!-- clubedge:only payments=stripe -->
+- `REDIS_URL`, when you run more than one instance. <!-- clubedge:only cache=redis -->
+- The `STORAGE_*` variables for your S3-compatible bucket. <!-- clubedge:only storage=s3 -->
+- `SUPABASE_STORAGE_BUCKET`. <!-- clubedge:only storage=supabase -->
+
 ## Checks
 
 Run the checks relevant to your change before opening a pull request:

package/template/_gitignore

@@ -22,3 +22,6 @@ supabase/.temp/
 supabase/.branches/
 # Local database and files for --infra local
 .data/
+# Build output of the Vercel and Netlify presets
+.vercel/
+.netlify/

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

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

package/template/apps/start/Dockerfile

@@ -25,6 +25,10 @@ COPY --from=deps /app/ .
 COPY --from=pruner /app/out/full/ .
 COPY tsconfig.base.json ./
 RUN pnpm build
+# The production migrator (node /app/migrate.mjs): one bundled file plus every package's
+# migrations, so release commands can migrate before a new version starts.
+COPY scripts/migrate.mjs scripts/build-migrator.mjs ./scripts/
+RUN node scripts/build-migrator.mjs /app/.migrator
 
 # Nitro bundles the server and its dependencies into .output, so no node_modules are needed.
 FROM node:22-alpine AS runner
@@ -33,6 +37,7 @@ ENV NODE_ENV=production HOST=0.0.0.0 PORT=3000
 WORKDIR /app
 RUN addgroup --system --gid 1001 nodejs && adduser --system --uid 1001 app
 COPY --from=builder --chown=app:nodejs /app/${APP_DIR}/.output ./.output
+COPY --from=builder --chown=app:nodejs /app/.migrator ./
 USER app
 EXPOSE 3000
 CMD ["node", ".output/server/index.mjs"]

package/template/apps/start/netlify.toml

@@ -0,0 +1,6 @@
+# Netlify (https://docs.netlify.com/configure-builds/file-based-configuration/). Set the site's
+# base directory to apps/web; the build detects Netlify and writes its functions and assets.
+[build]
+  # Migrations run during the build, against the DATABASE_URL set for the deploy context.
+  command = "pnpm --dir ../.. db:migrate && pnpm run build"
+  publish = "dist"

package/template/apps/start/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/start",
-  "version": "0.9.0",
+  "version": "0.11.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/payments": "workspace:*",
+    "@clubedge/payments-stripe": "workspace:*",
     "@clubedge/storage": "workspace:*",
     "@clubedge/storage-s3": "workspace:*",
     "@clubedge/storage-supabase": "workspace:*",

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

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