@clubedge/create-clubedge-app 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to `create-clubedge-app` are documented here.
 
+## 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.10.0
         |
         v
-Clubedge Starter v0.8.0
-commit 0b77577a3fe77617c84e250d8b220169b72a297e
+Clubedge Starter v0.9.0
+commit e858d0b5b60bbb05f1b6aed3f4d9e841ea2df2a5
 ```
 
 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.10.0` | `clubedge-starter@v0.9.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.9.0` tag is expected to resolve to commit
+`e858d0b5b60bbb05f1b6aed3f4d9e841ea2df2a5`. 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.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.
 
 ## Requirements
 
@@ -85,13 +85,14 @@ 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, 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.
 
 | 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` |
 | `--infra`   | `docker` (Docker Compose), `supabase` (Supabase CLI), `local` (no Docker: PGlite and a local folder), `none` | `docker` |
 
 ```sh
@@ -136,7 +137,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.9.0
 pnpm dlx @clubedge/create-clubedge-app my-app --ref <commit-sha>
 
 # Test local Starter changes before releasing them
@@ -153,7 +154,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.9.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 +205,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.9.0`, and publish the Starter release.
 
 ### CLI maintainers
 
@@ -218,7 +219,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.10.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.9.0",
+    "starterCommit": "e858d0b5b60bbb05f1b6aed3f4d9e841ea2df2a5"
   },
   "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/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,10 +19,14 @@ 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.
 
@@ -47,6 +51,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 +211,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

package/template/SETUP.md

@@ -43,6 +43,8 @@ The variables are:
 - `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 -->
 - `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 -->
 - `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 -->
 
@@ -62,13 +64,13 @@ The app is available at <http://localhost:3000> and the liveness endpoint at <ht
 
 Create or select a Supabase project and copy its URL and publishable key from the project's API settings into the Supabase variables above. Authentication runs on the server, which validates every user with Supabase; never use a service role key.
 
-In Supabase Auth URL configuration, add this redirect URL for local email confirmation:
+In Supabase Auth URL configuration, add this redirect URL for local email confirmation and password reset links:
 
 ```text
-http://localhost:3000/auth/callback
+http://localhost:3000/auth/callback**
 ```
 
-For deployed environments, add your deployed origin followed by `/auth/callback`. Until the Supabase variables are set, the dashboard stays viewable as a demo and the login page explains what is missing; once they are set, the dashboard redirects signed-out visitors to the login page.
+For deployed environments, add your deployed origin followed by `/auth/callback**`. The `**` lets links carry the page to open next, such as `/reset-password`. Supabase sends the confirmation and password reset emails itself; configure its SMTP settings in the Supabase project to send them from your own domain. Until the Supabase variables are set, the dashboard stays viewable as a demo and the login page explains what is missing; once they are set, the dashboard redirects signed-out visitors to the login page.
 
 <!-- clubedge:end -->
 
@@ -82,7 +84,13 @@ Better Auth keeps users, passwords, and sessions in your PostgreSQL database, in
 openssl rand -base64 32
 ```
 
-Put the result in `BETTER_AUTH_SECRET`. Until it is set, the dashboard stays viewable as a demo and the login page explains what is missing; once it is set, the dashboard redirects signed-out visitors to the login page. Sign-up signs the user in immediately; add email verification in `packages/auth-better-auth` if your application needs it. Signing in again on another device creates another session row, and signing out deletes it.
+Put the result in `BETTER_AUTH_SECRET`. Until it is set, the dashboard stays viewable as a demo and the login page explains what is missing; once it is set, the dashboard redirects signed-out visitors to the login page. Signing in again on another device creates another session row, and signing out deletes it.
+
+Sign-up signs the user in immediately; add email verification in `packages/auth-better-auth` if your application needs it. <!-- clubedge:only email=none -->
+Better Auth sends its emails through the [email module](#email): <!-- clubedge:only email!=none -->
+
+- **Password reset:** "Forgot password?" on the login page emails a link to `/reset-password`, valid for one hour and usable once. <!-- clubedge:only email!=none -->
+- **Email verification:** every new account gets a confirmation link. Sign-up signs the user in right away unless `BETTER_AUTH_REQUIRE_EMAIL_VERIFICATION=true`, which refuses sign-in until the link is opened. <!-- clubedge:only email!=none -->
 
 <!-- clubedge:end -->
 
@@ -101,6 +109,7 @@ pnpm check:services
 - PostgreSQL 17 on port 5432, database `app`, user and password `postgres`. Data survives restarts in a Docker volume.
 - Redis on port 6379. <!-- clubedge:only cache=redis -->
 - S3-compatible storage (adobe/s3mock) on port 9090 with the bucket `app`. It accepts any credentials and is for development only. <!-- clubedge:only storage=s3 -->
+- Mailpit, which catches every email the app sends: SMTP on port 1025, and the inbox at http://localhost:8025. <!-- clubedge:only email=smtp -->
 
 `pnpm infra:down` stops the services, `pnpm infra:reset` also deletes their data, and `pnpm infra:logs` follows their logs. The file is for development; in production, point the same variables at managed services.
 
@@ -118,6 +127,8 @@ pnpm check:services
 
 The database is on port 54322 and the API on port 54321, matching the example environment. Copy the publishable key from `pnpm infra:status` into the Supabase variables. Email confirmation is off locally, so sign-up signs the user in directly. `pnpm infra:down` stops the stack and `pnpm infra:reset` also deletes its data.
 
+The app's own email goes to the same inbox over SMTP, on port 54325. <!-- clubedge:only email=smtp -->
+
 <!-- clubedge:end -->
 <!-- clubedge:if infra=local -->
 
@@ -126,6 +137,7 @@ This project runs its development services without Docker or any other installat
 - **PostgreSQL:** `pnpm dev` also starts [PGlite](https://pglite.dev), PostgreSQL compiled to WebAssembly, and serves it on `127.0.0.1:5433`. Each start applies the migrations. Data is kept in `.data/pglite`. `pnpm infra:up` runs the database on its own, for `pnpm check:services` or browser tests.
 - **Files:** while `STORAGE_DIRECTORY` is set, uploads are stored in that folder (`.data/storage`) instead of S3. Set the S3 variables and remove `STORAGE_DIRECTORY` to use object storage. <!-- clubedge:only storage=s3 -->
 - **Cache:** without `REDIS_URL`, the cache and rate limits use process memory. <!-- clubedge:only cache=redis -->
+- **Email:** without a provider configured, emails are printed to the `pnpm dev` output, links included. <!-- clubedge:only email!=none -->
 
 PGlite runs a single database session, so connections take turns. That is plenty for development but not for production: deploy against a managed PostgreSQL by setting `DATABASE_URL`. Supabase Auth and Supabase Storage need a Supabase project, local or hosted. Better Auth works fully offline. `pnpm infra:reset` deletes everything in `.data/`.
 
@@ -174,6 +186,28 @@ Without `REDIS_URL`, the rate limiter and cache use process memory. Memory limit
 
 The rate limiter and cache keep their state in process memory, which suits a single server instance. Limits and cached values are not shared between instances and reset on restart.
 
+<!-- clubedge:end -->
+<!-- clubedge:if email!=none -->
+
+## Email
+
+The app sends email through the `EmailProvider` in `apps/web/src/server/email.ts`. Server code imports `email` from `@/server/email` and calls `email.send({ to, subject, text, html })`.
+
+<!-- clubedge:end -->
+<!-- clubedge:if email=smtp -->
+
+Set `SMTP_URL` to any SMTP server, for example `smtps://user:password@smtp.example.com:465`, and `EMAIL_FROM` to the sender, as `Name <address>` or an address. Most email providers (Resend, Postmark, Amazon SES, SendGrid, Mailgun) offer an SMTP endpoint.
+
+<!-- clubedge:end -->
+<!-- clubedge:if email=resend -->
+
+Set `RESEND_API_KEY` to a [Resend](https://resend.com) API key and `EMAIL_FROM` to a sender on a domain you verified in Resend, as `Name <address>` or an address. A key limited to sending is enough.
+
+<!-- clubedge:end -->
+<!-- clubedge:if email!=none -->
+
+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 storage!=none -->
 

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

@@ -24,6 +24,8 @@ 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
@@ -33,6 +35,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/apps/start/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/start",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "private": true,
   "license": "Apache-2.0",
   "type": "module",
@@ -19,6 +19,9 @@
     "@clubedge/cache-redis": "workspace:*",
     "@clubedge/core": "workspace:*",
     "@clubedge/db": "workspace:*",
+    "@clubedge/email": "workspace:*",
+    "@clubedge/email-resend": "workspace:*",
+    "@clubedge/email-smtp": "workspace:*",
     "@clubedge/storage": "workspace:*",
     "@clubedge/storage-s3": "workspace:*",
     "@clubedge/storage-supabase": "workspace:*",

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

@@ -8,6 +8,12 @@ import { createRedisCache } from "@clubedge/cache-redis";
 // clubedge:if storage=s3
 import { createS3Storage } from "@clubedge/storage-s3";
 // clubedge:end
+// clubedge:if email=smtp
+import { createSmtpEmail } from "@clubedge/email-smtp";
+// clubedge:end
+// clubedge:if email=resend
+import { createResendEmail } from "@clubedge/email-resend";
+// clubedge:end
 // clubedge:if storage=s3 && infra=local
 import { createFileSystemStorage } from "@clubedge/storage/file-system";
 // clubedge:end
@@ -62,6 +68,38 @@ async function main() {
       },
     },
     // clubedge:end
+    // clubedge:if email=smtp
+    {
+      name: "Email (SMTP)",
+      skip: env.SMTP_URL ? undefined : "SMTP_URL is not set; development prints emails to the log",
+      async run() {
+        // Connects and authenticates without sending anything.
+        const email = createSmtpEmail({
+          url: env.SMTP_URL!,
+          from: env.EMAIL_FROM || "no-reply@example.com",
+        });
+        await email.verify();
+        return `connected to ${new URL(env.SMTP_URL!).host}`;
+      },
+    },
+    // clubedge:end
+    // clubedge:if email=resend
+    {
+      name: "Email (Resend)",
+      skip: env.RESEND_API_KEY
+        ? undefined
+        : "RESEND_API_KEY is not set; development prints emails to the log",
+      async run() {
+        // Checks the API key without sending anything.
+        const email = createResendEmail({
+          apiKey: env.RESEND_API_KEY!,
+          from: env.EMAIL_FROM || "no-reply@example.com",
+        });
+        await email.verify();
+        return "API key accepted";
+      },
+    },
+    // clubedge:end
     // clubedge:if storage=s3 && infra=local
     {
       name: "Local folder storage",