@clubedge/create-clubedge-app 0.9.0 → 0.11.0

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to `create-clubedge-app` are documented here.
 
+## 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.
+- Fix a doubled blank line in `.env.local` when `add` or `remove` swaps one section of variables for another, such as switching `--email smtp` to `resend`.
+- Take module flags from the Starter's manifest: any `--<module> <option>` flag is accepted and validated against the modules the Starter describes, so new Starter modules need no CLI release. A mistyped module lists the Starter's modules; an unknown flag without a value is still an error.
+- Build the help text's framework and module lines, and the "customize the included services" prompt, from the Starter's manifest.
+
 ## 0.9.0
 
 - Default to Starter `v0.8.0`, whose projects have a `clubedge` script: `pnpm clubedge add`, `remove`, and `upgrade`.

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.9.0
+create-clubedge-app v0.11.0
         |
         v
-Clubedge Starter v0.8.0
-commit 0b77577a3fe77617c84e250d8b220169b72a297e
+Clubedge Starter v0.10.0
+commit 9d8fec71b3851c2d615735fb37edb6bb0e568761
 ```
 
 The current relationship is:
 
 | CLI release | Default Starter release | Meaning |
 | --- | --- | --- |
-| `create-clubedge-app@0.9.0` | `clubedge-starter@v0.8.0` | The CLI's required, tested default |
+| `create-clubedge-app@0.11.0` | `clubedge-starter@v0.10.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.8.0` tag is expected to resolve to commit
-`0b77577a3fe77617c84e250d8b220169b72a297e`. The CLI verifies this before
+The `v0.10.0` tag is expected to resolve to commit
+`9d8fec71b3851c2d615735fb37edb6bb0e568761`. 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.8.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.10.0`. The CLI is then updated to use that release, all generated-project checks must pass, and a new CLI version is published. This keeps Starter and CLI releases independently versioned while preserving a tested compatibility relationship.
 
 ## Requirements
 
@@ -85,13 +85,15 @@ Either way, the app lives in `apps/web` and uses the same shared packages, so th
 
 ### Choosing services
 
-Authentication, file storage, and caching 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.
+Authentication, file storage, caching, email, local infrastructure, and deployment are modules. Each has a default, and anything you leave out is removed completely: its package, its provider SDK, its environment variables, its documentation, and its lockfile entries. The Starter's `clubedge.template.json` defines the modules, so a module a newer Starter adds gets its `--<module>` flag without a CLI change; `--help` lists the modules of the Starter this CLI release creates.
 
 | Flag        | Options                                    | Default    |
 | ----------- | ------------------------------------------ | ---------- |
 | `--auth`    | `supabase`, `better-auth`, `none`          | `supabase` |
 | `--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` |
+| `--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
@@ -136,7 +138,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.8.0
+pnpm dlx @clubedge/create-clubedge-app my-app --ref v0.10.0
 pnpm dlx @clubedge/create-clubedge-app my-app --ref <commit-sha>
 
 # Test local Starter changes before releasing them
@@ -153,7 +155,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.8.0  # or a specific tag, branch, or commit
+pnpm dlx @clubedge/create-clubedge-app upgrade --ref v0.10.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.
@@ -204,7 +206,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.8.0`, and publish the Starter release.
+4. Commit `main`, create a release tag such as `v0.10.0`, and publish the Starter release.
 
 ### CLI maintainers
 
@@ -218,7 +220,7 @@ The required CI job always tests the pinned default. The scheduled compatibility
 
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for development and pull request guidance. Report vulnerabilities privately as described in [SECURITY.md](SECURITY.md).
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development and pull request guidance, and [ROADMAP.md](ROADMAP.md) for the planned phases. Report vulnerabilities privately as described in [SECURITY.md](SECURITY.md).
 
 ## License
 

package/dist/cli/args.js

@@ -1,32 +1,70 @@
 import { parseArgs } from "node:util";
-/** Module flags the CLI accepts. Which options exist is up to the Starter's manifest. */
-export const MODULE_FLAGS = ["auth", "storage", "cache", "infra"];
 export class UsageError extends Error {
     name = "UsageError";
 }
+/** The CLI's own long options; every other --name value flag selects a module option. */
+const OPTIONS = {
+    framework: { type: "string" },
+    ref: { type: "string" },
+    "template-dir": { type: "string" },
+    install: { type: "boolean", default: true },
+    git: { type: "boolean", default: true },
+    yes: { type: "boolean", short: "y", default: false },
+    "dry-run": { type: "boolean", default: false },
+    force: { type: "boolean", default: false },
+    help: { type: "boolean", short: "h", default: false },
+    version: { type: "boolean", short: "v", default: false },
+};
+const isOwnOption = (name) => name in OPTIONS || (name.startsWith("no-") && OPTIONS[name.slice(3)]?.type === "boolean");
+/**
+ * Takes module flags (`--email smtp` or `--email=smtp`) out of the arguments, leaving the CLI's
+ * own options for the strict parser. A flag that is neither needs a value, so a stray unknown
+ * flag such as --verbose is still reported.
+ */
+function extractModuleFlags(argv) {
+    const rest = [];
+    const modules = {};
+    for (let i = 0; i < argv.length; i++) {
+        const argument = argv[i];
+        if (argument === "--") {
+            rest.push(...argv.slice(i));
+            break;
+        }
+        const match = /^--([^=]+)(?:=(.*))?$/.exec(argument);
+        if (!match || isOwnOption(match[1])) {
+            rest.push(argument);
+            // A string option's value is never a flag of its own.
+            if (match && match[2] === undefined && OPTIONS[match[1]]?.type === "string") {
+                if (argv[i + 1] !== undefined)
+                    rest.push(argv[++i]);
+            }
+            continue;
+        }
+        const [, name, inline] = match;
+        if (!/^[a-z][a-z0-9-]*$/.test(name))
+            throw new UsageError(`Unknown option --${name}. Run with --help to see available options.`);
+        const next = argv[i + 1];
+        const value = inline ?? (next !== undefined && !next.startsWith("-") ? argv[++i] : undefined);
+        if (value === undefined) {
+            throw new UsageError(`Unknown option --${name}. Module flags take an option, such as --${name} none. Run with --help to see available options.`);
+        }
+        if (!value.trim())
+            throw new UsageError(`--${name} requires an option, such as none.`);
+        modules[name] = value.trim();
+    }
+    return { rest, modules };
+}
 export function parseCliArgs(argv) {
+    const { rest, modules } = extractModuleFlags(argv);
     let parsed;
     try {
         parsed = parseArgs({
-            args: argv,
+            args: rest,
             allowPositionals: true,
             allowNegative: true,
             strict: true,
             options: {
-                framework: { type: "string" },
-                auth: { type: "string" },
-                storage: { type: "string" },
-                cache: { type: "string" },
-                infra: { type: "string" },
-                ref: { type: "string" },
-                "template-dir": { type: "string" },
-                install: { type: "boolean", default: true },
-                git: { type: "boolean", default: true },
-                yes: { type: "boolean", short: "y", default: false },
-                "dry-run": { type: "boolean", default: false },
-                force: { type: "boolean", default: false },
-                help: { type: "boolean", short: "h", default: false },
-                version: { type: "boolean", short: "v", default: false },
+                ...OPTIONS,
             },
         });
     }
@@ -39,7 +77,7 @@ export function parseCliArgs(argv) {
     if (command.name === "create" && positionals.length > 1) {
         throw new UsageError("Only one project directory can be provided.");
     }
-    if (command.name !== "create" && (values.framework !== undefined || MODULE_FLAGS.some((id) => values[id]))) {
+    if (command.name !== "create" && (values.framework !== undefined || Object.keys(modules).length)) {
         throw new UsageError("--framework and module flags only apply when creating a project; use add or remove to change one module.");
     }
     if ((command.name === "add" || command.name === "remove") && values.ref !== undefined) {
@@ -48,15 +86,6 @@ export function parseCliArgs(argv) {
     if (values.framework !== undefined && !values.framework.trim()) {
         throw new UsageError("--framework requires a framework id, such as next or tanstack-start.");
     }
-    const modules = {};
-    for (const module of MODULE_FLAGS) {
-        const value = values[module];
-        if (value === undefined)
-            continue;
-        if (!value.trim())
-            throw new UsageError(`--${module} requires an option, such as none.`);
-        modules[module] = value.trim();
-    }
     if (values.ref !== undefined && !values.ref.trim()) {
         throw new UsageError("--ref requires a tag, branch, or commit.");
     }

package/dist/cli/ui.js

@@ -52,7 +52,32 @@ export function showBanner() {
     console.log(`  ${dim("By Clubedge")}  ${dim("·")}  ${paint(gradientFrom, siteUrl)}`);
     console.log("");
 }
-export function helpText() {
+/** "a (default), b, or c" */
+function choices(ids, defaultId) {
+    const labels = ids.map((id) => (id === defaultId ? `${id} (default)` : id));
+    return labels.length > 1 ? `${labels.slice(0, -1).join(", ")}${labels.length > 2 ? "," : ""} or ${labels.at(-1)}` : labels[0] ?? "";
+}
+/**
+ * The framework and module flags of a Starter, from its manifest, so new modules appear in the
+ * help without CLI changes. Without a manifest, a generic line explains module flags.
+ */
+export function selectionHelp(manifest) {
+    const line = (flag, text) => `  ${flag.padEnd(24)}${text}`;
+    if (!manifest) {
+        return [
+            line("--framework <id>", "App framework, such as next or tanstack-start"),
+            line("--<module> <option>", "A module option, such as --auth none; the Starter lists its modules"),
+        ].join("\n");
+    }
+    const frameworks = Object.keys(manifest.frameworks);
+    return [
+        ...(frameworks.length > 1
+            ? [line("--framework <id>", `App framework: ${choices(frameworks, manifest.defaultFramework)}`)]
+            : []),
+        ...Object.entries(manifest.modules).map(([id, module]) => line(`--${id} <id>`, `${module.name}: ${choices(Object.keys(module.options), module.default)}`)),
+    ].join("\n");
+}
+export function helpText(manifest = null) {
     return `
 create-clubedge-app ${cliVersion}
 
@@ -74,11 +99,7 @@ Usage:
   markers. Commit first so you can review the result with git diff.
 
 Options:
-  --framework <id>        App framework: next (default) or tanstack-start
-  --auth <id>             Authentication: supabase (default), better-auth, or none
-  --storage <id>          File storage: s3 (default), supabase, or none
-  --cache <id>            Cache and rate limits: redis (default) or memory
-  --infra <id>            Local services: docker (default), supabase, local, or none
+${selectionHelp(manifest)}
   --ref <ref>             Download this Starter tag, branch, or commit from GitHub instead
                           (upgrade: the Starter to upgrade to)
   --template-dir <path>   Scaffold from a local Starter checkout (for Starter development)

package/dist/core/env.js

@@ -76,10 +76,17 @@ export function updateEnvFile(local, baseExample, targetExample) {
         while (anchor >= 0 && !keyOf(target[anchor]))
             anchor--;
         const position = anchor >= 0 ? find(lines, keyOf(target[anchor])) : -1;
-        if (position === -1)
+        if (position === -1) {
             appended.push(...commentsAbove(target, at), line);
-        else
-            lines.splice(position + 1, 0, ...target.slice(anchor + 1, at + 1));
+            return;
+        }
+        const between = target.slice(anchor + 1, at + 1);
+        // A removed section can leave its blank separator after the anchor; reuse it rather than
+        // adding a second one.
+        // The last element is the end of the file after its final newline, not a blank line.
+        const followedByBlank = position + 1 < lines.length - 1 && lines[position + 1].trim() === "";
+        const reuseBlank = between[0]?.trim() === "" && followedByBlank;
+        lines.splice(position + (reuseBlank ? 2 : 1), 0, ...(reuseBlank ? between.slice(1) : between));
     });
     let text = lines.join(eol);
     // Removed variables can leave blank lines in a row, as removed template blocks do.

package/dist/index.js

@@ -7,8 +7,8 @@ import { dim, helpText, showBanner } from "./cli/ui.js";
 import { assertTargetIsUsable, executePlan } from "./core/execute.js";
 import { readTemplateManifest } from "./core/manifest.js";
 import { createPlan, describePlan, selectFramework } from "./core/plan.js";
-import { resolveTemplateSource } from "./core/source.js";
-import { cliUrl, cliVersion, siteUrl } from "./package-info.js";
+import { readBundledTemplate, resolveTemplateSource } from "./core/source.js";
+import { cliUrl, cliVersion, siteUrl, starterPin } from "./package-info.js";
 import { changeProject } from "./modify.js";
 import { initializeGit } from "./steps/git.js";
 import { detectLauncher, installDependencies, resolvePnpm } from "./steps/install.js";
@@ -63,7 +63,9 @@ async function chooseModules(manifest, requested, interactive) {
     if (!interactive || unasked.length === 0)
         return requested;
     const customize = await confirm({
-        message: "Customize the included services (auth, storage, cache, local infrastructure)?",
+        message: `Customize the included services (${Object.values(manifest.modules)
+            .map((module) => module.name.toLowerCase())
+            .join(", ")})?`,
         initialValue: false,
     });
     if (isCancel(customize))
@@ -193,6 +195,19 @@ async function createProject(args) {
         later +
         `${dim("Docs")}     ${cliUrl}\n${dim("Clubedge")} ${siteUrl}`);
 }
+/** The bundled Starter's manifest, for the help text; null in a checkout without a bundle. */
+async function bundledManifest() {
+    try {
+        const bundled = await readBundledTemplate();
+        // A checkout can hold an older bundle; only the pinned release describes what this CLI creates.
+        if (!bundled || bundled.commit !== starterPin.starterCommit)
+            return null;
+        return await readTemplateManifest(bundled.root);
+    }
+    catch {
+        return null;
+    }
+}
 export async function main(argv = process.argv.slice(2)) {
     try {
         const args = parseCliArgs(argv);
@@ -202,7 +217,7 @@ export async function main(argv = process.argv.slice(2)) {
         }
         showBanner();
         if (args.help) {
-            console.log(helpText());
+            console.log(helpText(await bundledManifest()));
             return;
         }
         assertSupportedNode();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/create-clubedge-app",
-  "version": "0.9.0",
+  "version": "0.11.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.8.0",
-    "starterCommit": "0b77577a3fe77617c84e250d8b220169b72a297e"
+    "starterRef": "v0.10.0",
+    "starterCommit": "9d8fec71b3851c2d615735fb37edb6bb0e568761"
   },
   "license": "Apache-2.0",
   "repository": {

package/template/.env.example

@@ -22,6 +22,8 @@ NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=
 # Better Auth keeps users and sessions in DATABASE_URL (run pnpm db:migrate first).
 # Generate a secret with: openssl rand -base64 32
 BETTER_AUTH_SECRET=
+# true refuses sign-in until the email address is confirmed through the emailed link. # clubedge:only email!=none
+BETTER_AUTH_REQUIRE_EMAIL_VERIFICATION=false # clubedge:only email!=none
 # clubedge:end
 
 # clubedge:if cache=redis
@@ -31,6 +33,24 @@ REDIS_URL= # clubedge:only infra!=docker
 REDIS_URL=redis://localhost:6379 # clubedge:only infra=docker
 # clubedge:end
 
+# clubedge:if email=smtp
+# Email over SMTP: any provider's SMTP endpoint (smtps:// for TLS). Without it, development
+# prints emails to the server log and production refuses to send.
+SMTP_URL= # clubedge:only infra!=docker|supabase
+# Mailpit from docker-compose.dev.yml; read the emails at http://localhost:8025. # clubedge:only infra=docker
+SMTP_URL=smtp://localhost:1025 # clubedge:only infra=docker
+# The local Supabase inbox; read the emails at http://127.0.0.1:54324. # clubedge:only infra=supabase
+SMTP_URL=smtp://127.0.0.1:54325 # clubedge:only infra=supabase
+EMAIL_FROM=App <no-reply@example.com>
+# clubedge:end
+
+# clubedge:if email=resend
+# Resend (https://resend.com). EMAIL_FROM must use a domain verified in Resend. Without the
+# key, development prints emails to the server log and production refuses to send.
+RESEND_API_KEY=
+EMAIL_FROM=App <no-reply@example.com>
+# 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

@@ -7,7 +7,7 @@ Clubedge Starter is a production-oriented, modular React application foundation.
 
 <!-- clubedge:if starter-repository -->
 
-This repository contains the same application for two frameworks, Next.js (`apps/web`) and TanStack Start (`apps/start`), plus every optional module. [create-clubedge-app](https://github.com/Clubedge/create-clubedge-app) generates a project with one framework and only the modules you choose; sections of this README marked for a framework or module appear only in projects that use it. Contributions and bug reports are welcome; see [CONTRIBUTING.md](CONTRIBUTING.md). Repository maintainers can use [PUBLISHING.md](PUBLISHING.md) for the GitHub launch checklist.
+This repository contains the same application for two frameworks, Next.js (`apps/web`) and TanStack Start (`apps/start`), plus every optional module. [create-clubedge-app](https://github.com/Clubedge/create-clubedge-app) generates a project with one framework and only the modules you choose; sections of this README marked for a framework or module appear only in projects that use it. Contributions and bug reports are welcome; see [CONTRIBUTING.md](CONTRIBUTING.md). Repository maintainers can use [PUBLISHING.md](PUBLISHING.md) for the GitHub launch checklist, and [ROADMAP.md](ROADMAP.md) describes the planned phases.
 
 <!-- clubedge:end -->
 
@@ -19,12 +19,23 @@ This repository contains the same application for two frameworks, Next.js (`apps
 - Drizzle ORM and PostgreSQL schema, migrations, and seed commands.
 - 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 -->
+- 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 -->
 - S3-compatible storage adapter for AWS S3, Cloudflare R2, and MinIO. <!-- clubedge:only storage=s3 -->
 - Supabase Storage adapter that uses the signed-in user's session. <!-- clubedge:only storage=supabase -->
 - Fixed-window rate limiter and cache on Redis, falling back to process memory without `REDIS_URL`. <!-- clubedge:only cache=redis -->
 - 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 -->
 - 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
 
@@ -47,6 +58,12 @@ flowchart TB
   %% clubedge:if cache=redis
   App -->|cache and rate limits| Redis[(Redis, or memory)]
   %% clubedge:end
+  %% clubedge:if email=smtp
+  App -->|email interface| SMTP[SMTP server, or the log]
+  %% clubedge:end
+  %% clubedge:if email=resend
+  App -->|email interface| Resend[Resend, or the log]
+  %% clubedge:end
   %% clubedge:if storage=s3
   App -->|storage interface| S3[S3-compatible storage: AWS S3, R2, MinIO]
   %% clubedge:end
@@ -201,6 +218,9 @@ The TanStack Start app is `apps/start`, run with `pnpm --filter @clubedge/start
 - `packages/storage-supabase/`: Supabase Storage adapter <!-- clubedge:only storage=supabase -->
 - `packages/cache/`: `Cache` and `RateLimiter` interfaces with in-memory implementations
 - `packages/cache-redis/`: Redis rate limiter and cache <!-- clubedge:only cache=redis -->
+- `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/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