@clubedge/create-clubedge-app 0.26.0 → 0.27.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to `create-clubedge-app` are documented here.
 
+## 0.27.0
+
+- Default to Starter `v0.18.0` (#77), which stops Vercel and Netlify builds when a production variable is missing:
+  - On those hosts the platform only runs the app, and the database, Redis, storage, and email come from your providers. `pnpm check:env` now runs first in the build command of `vercel.json` and `netlify.toml`, before migrations.
+  - It lists each variable the project's modules need that is unset, points at `localhost`, or isn't an absolute URL, and stops the build. That includes `.env.example`'s `example.com` sender in `EMAIL_FROM`.
+  - Generated projects check only their own modules. `SKIP_ENV_CHECK=1` builds anyway.
+- If you deploy to Vercel or Netlify: run `pnpm clubedge upgrade`, then set the variables for every environment you build (Production and Preview).
+
 ## 0.26.0
 
 - `deploy` uses your own databases when the env file has their URLs (#74). The platform hosts everything as before when it doesn't.

package/README.md

@@ -127,7 +127,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.17.1
+pnpm dlx @clubedge/create-clubedge-app my-app --ref v0.18.0
 pnpm dlx @clubedge/create-clubedge-app my-app --ref <commit-sha>
 
 # Test local Starter changes before releasing them
@@ -146,7 +146,7 @@ pnpm clubedge add email resend payments stripe              # several modules as
 pnpm clubedge remove storage payments
 pnpm dlx @clubedge/create-clubedge-app add infra local --dry-run
 pnpm dlx @clubedge/create-clubedge-app@latest upgrade        # to the newest CLI's Starter release
-pnpm dlx @clubedge/create-clubedge-app upgrade --ref v0.17.1 # or a specific tag, branch, or commit
+pnpm dlx @clubedge/create-clubedge-app upgrade --ref v0.18.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.
@@ -210,27 +210,27 @@ In a project with `--deploy fly`, `pnpm clubedge deploy` does the same with [Fly
 Each CLI release is tested against one specific Starter release:
 
 ```text
-create-clubedge-app v0.26.0
+create-clubedge-app v0.27.0
         |
         v
-Clubedge Starter v0.17.1
-commit d9d787b6750e862b9de81a3f8f36b7aa07757f7a
+Clubedge Starter v0.18.0
+commit bcd084d7d2d2aac0600ccb35491f48c251fb3a74
 ```
 
 The current relationship is:
 
 | CLI release | Default Starter release | Meaning |
 | --- | --- | --- |
-| `create-clubedge-app@0.26.0` | `clubedge-starter@v0.17.1` | The CLI's required, tested default |
+| `create-clubedge-app@0.27.0` | `clubedge-starter@v0.18.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.17.1` tag is expected to resolve to commit
-`d9d787b6750e862b9de81a3f8f36b7aa07757f7a`. The CLI verifies this before
+The `v0.18.0` tag is expected to resolve to commit
+`bcd084d7d2d2aac0600ccb35491f48c251fb3a74`. 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.17.1`. The CLI is then updated to use that release, all generated-project checks must pass, and a new CLI version is published. This keeps Starter and CLI releases independently versioned while preserving a tested compatibility relationship.
+When the Starter changes, its maintainers first publish a new versioned release, such as `v0.18.0`. The CLI is then updated to use that release, all generated-project checks must pass, and a new CLI version is published. This keeps Starter and CLI releases independently versioned while preserving a tested compatibility relationship.
 
 Every generated project records its CLI version, Starter repository, Starter ref, Starter commit, framework, and modules in `package.json` and `README.md`.
 
@@ -285,7 +285,7 @@ CI packs the CLI with `npm pack`, scaffolds clean projects from the packed tarba
 1. Make and validate changes in `clubedge-starter`.
 2. Run lint, typecheck, unit tests, browser tests, and production build.
 3. Update the Starter package versions.
-4. Commit `main`, create a release tag such as `v0.17.1`, and publish the Starter release.
+4. Commit `main`, create a release tag such as `v0.18.0`, and publish the Starter release.
 
 ### CLI maintainers
 
@@ -321,6 +321,7 @@ Each phase ends with a Starter release and a CLI release pinned to it. The full
 | 0.24.0 | v0.17.0 | Starter v0.17.0: Railway configuration as code (`.railway/railway.ts`) instead of `railway.json` |
 | 0.25.0 | v0.17.1 | `deploy` to Fly.io (experimental); weekly Dependabot updates |
 | 0.26.0 | v0.17.1 | `deploy` uses your own databases (Supabase, Neon, Upstash) when the env file has their URLs, and reads `.env.production` |
+| 0.27.0 | v0.18.0 | Starter v0.18.0: Vercel and Netlify builds stop when a production variable is missing (`pnpm check:env`) |
 | next | | Show the Starter's version of a conflicted file next to yours |
 
 ## Community

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/create-clubedge-app",
-  "version": "0.26.0",
+  "version": "0.27.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.17.1",
-    "starterCommit": "d9d787b6750e862b9de81a3f8f36b7aa07757f7a"
+    "starterRef": "v0.18.0",
+    "starterCommit": "bcd084d7d2d2aac0600ccb35491f48c251fb3a74"
   },
   "license": "Apache-2.0",
   "repository": {

package/template/README.md

@@ -76,8 +76,8 @@ Every combination in the CI matrix is generated as a real project and runs its f
 - Deployment to Fly.io with `fly.toml`: migrations run as the release command. <!-- clubedge:only deploy=fly -->
 - Deployment to Railway with `.railway/railway.ts`: migrations run before each release, and `pnpm clubedge deploy` sets up the project. <!-- 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 -->
+- Deployment to Vercel with `apps/web/vercel.json`: the build stops when a production variable is missing, then runs migrations. <!-- clubedge:only deploy=vercel -->
+- Deployment to Netlify with `apps/web/netlify.toml`: the build stops when a production variable is missing, then runs migrations. <!-- clubedge:only deploy=netlify -->
 
 **Quality**
 
@@ -270,6 +270,7 @@ Playwright's first run may require installing Chromium with `pnpm exec playwrigh
 Local services:
 
 - `pnpm check:services`: check every configured service with a real round trip.
+- `pnpm check:env`: check that the environment has every production variable the project's modules need. Vercel and Netlify builds run it first. <!-- clubedge:only deploy=vercel|netlify -->
 - `pnpm infra:up` and `pnpm infra:down`: start and stop the local services from `docker-compose.dev.yml`. <!-- clubedge:only infra=docker -->
 - `pnpm infra:reset`: stop them and delete their data. `pnpm infra:logs` follows their logs. <!-- clubedge:only infra=docker -->
 - `pnpm infra:up` and `pnpm infra:down`: start and stop the local Supabase stack. <!-- clubedge:only infra=supabase -->

package/template/SETUP.md

@@ -408,6 +408,8 @@ Render runs `node /app/migrate.mjs` as the pre-deploy command before each deploy
 `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 only runs the app: the database, Redis, file storage, and email come from your providers (for example Supabase, Upstash, and Cloudflare R2). The build command starts with `pnpm check:env`, which stops the build when a variable the project's modules need is unset, or points at `localhost`, and lists each one. Set them for every environment you deploy (Production and Preview); `SKIP_ENV_CHECK=1` builds anyway.
+
 Vercel has no step that runs before a release, so the build command applies migrations (`pnpm db:migrate`) against the `DATABASE_URL` of the deployment's environment. Give Preview deployments their own database, or remove the migration step from `buildCommand` and run migrations yourself. Serverless functions open a connection per instance: use your provider's pooled connection URL (for example Supabase's transaction pooler or Neon's pooled endpoint).
 
 Vercel runs no worker for [background jobs](#background-jobs). Set `CRON_SECRET` and add `"crons": [{ "path": "/api/jobs/run", "schedule": "* * * * *" }]` to `vercel.json`; Vercel Cron sends the secret itself. Cron jobs more frequent than daily need a paid Vercel plan; otherwise call the endpoint from another scheduler. <!-- clubedge:only jobs=pg-boss -->
@@ -418,6 +420,8 @@ Vercel runs no worker for [background jobs](#background-jobs). Set `CRON_SECRET`
 `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 only runs the app: the database, Redis, file storage, and email come from your providers (for example Supabase, Upstash, and Cloudflare R2). The build command starts with `pnpm check:env`, which stops the build when a variable the project's modules need is unset, or points at `localhost`, and lists each one. Set them for every deploy context you build (production and deploy previews); `SKIP_ENV_CHECK=1` builds anyway.
+
 Netlify has no step that runs before a release, so the build command applies migrations (`pnpm db:migrate`) against the `DATABASE_URL` of the deploy context. Give deploy previews their own database, or remove the migration step from the build command and run migrations yourself. Serverless functions open a connection per instance: use your provider's pooled connection URL (for example Supabase's transaction pooler or Neon's pooled endpoint).
 
 Netlify runs no worker for [background jobs](#background-jobs). Set `JOBS_WORKER=off` and `CRON_SECRET`, then call `/api/jobs/run` every minute from a [scheduled function](https://docs.netlify.com/build/functions/scheduled-functions/) or another scheduler, with the header `Authorization: Bearer <CRON_SECRET>`. <!-- clubedge:only jobs=pg-boss -->

package/template/apps/start/netlify.toml

@@ -1,6 +1,7 @@
 # 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"
+  # check:env stops the build when a variable the project needs is unset; then migrations run,
+  # against the DATABASE_URL set for the deploy context.
+  command = "pnpm run check:env && pnpm --dir ../.. db:migrate && pnpm run build"
   publish = "dist"

package/template/apps/start/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/start",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "private": true,
   "license": "Apache-2.0",
   "type": "module",
@@ -9,7 +9,8 @@
     "build": "vite build",
     "start": "node --env-file-if-exists=.env.local .output/server/index.mjs",
     "typecheck": "tsr generate && tsc --noEmit",
-    "check:services": "tsx scripts/check-services.ts"
+    "check:services": "tsx scripts/check-services.ts",
+    "check:env": "tsx scripts/check-env.ts"
   },
   "dependencies": {
     "@clubedge/auth": "workspace:*",

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

@@ -0,0 +1,34 @@
+// Checks the production variables before a deploy build: `pnpm check:env`. Vercel's and Netlify's
+// build commands run it first, so a missing key stops the build. It reads the build's environment,
+// not .env.local; SKIP_ENV_CHECK=1 builds anyway.
+import { checkProductionEnv } from "../src/env/production";
+
+function main() {
+  if (process.env.SKIP_ENV_CHECK === "1") {
+    console.warn(
+      "check:env skipped (SKIP_ENV_CHECK=1): missing variables fail at runtime instead.",
+    );
+    return;
+  }
+  const { missing, local, invalid } = checkProductionEnv(process.env);
+  if (!missing.length && !local.length && !invalid.length) {
+    console.log("✓  check:env: every production variable this project needs is set.");
+    return;
+  }
+  const lines = [
+    ...missing.map(({ key, use }) => `✗  ${key} is not set (${use})`),
+    ...local.map((key) => `✗  ${key} points at localhost, which the deployed app can't reach`),
+    ...invalid.map((problem) => `✗  ${problem}`),
+  ];
+  console.error(
+    [
+      "check:env: the production environment is incomplete, so the build stops here.",
+      ...lines,
+      "Fix them in the host's environment variables for this environment (Production or Preview),",
+      "then deploy again. SKIP_ENV_CHECK=1 builds anyway.",
+    ].join("\n"),
+  );
+  process.exit(1);
+}
+
+main();

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

@@ -0,0 +1,65 @@
+import { describe, expect, it } from "vitest";
+import { checkProductionEnv, isLocalUrl, requiredVariables } from "./production";
+
+// A value for every variable this project requires, whichever modules it has.
+const complete = (extra: Record<string, string> = {}) => {
+  const env: Record<string, string> = { ...extra };
+  for (const { key } of requiredVariables(extra)) env[key] ??= "https://service.example.com";
+  if ("BETTER_AUTH_SECRET" in env) env.BETTER_AUTH_SECRET = "x".repeat(32);
+  return env;
+};
+
+describe("production env check", () => {
+  it("passes when every required variable is set", () => {
+    expect(checkProductionEnv(complete())).toEqual({ missing: [], local: [], invalid: [] });
+    expect(checkProductionEnv(complete({ VERCEL: "1" }))).toEqual({
+      missing: [],
+      local: [],
+      invalid: [],
+    });
+  });
+
+  it("always requires the database and the public URL", () => {
+    const keys = checkProductionEnv({}).missing.map(({ key }) => key);
+    expect(keys).toContain("DATABASE_URL");
+    expect(keys).toContain("APP_URL");
+  });
+
+  it("counts empty values as unset", () => {
+    const env = { ...complete(), DATABASE_URL: "  " };
+    expect(checkProductionEnv(env).missing.map(({ key }) => key)).toEqual(["DATABASE_URL"]);
+  });
+
+  it("rejects URLs to this machine", () => {
+    const env = {
+      ...complete(),
+      DATABASE_URL: "postgresql://postgres:postgres@localhost:5432/app",
+    };
+    expect(checkProductionEnv(env).local).toEqual(["DATABASE_URL"]);
+  });
+
+  it("rejects a URL that isn't absolute", () => {
+    const env = { ...complete(), APP_URL: "my-app.vercel.app" };
+    expect(checkProductionEnv(env).invalid).toEqual(["APP_URL is not an absolute URL"]);
+  });
+
+  const hasEmail = requiredVariables({}).some(({ key }) => key === "EMAIL_FROM");
+  it.runIf(hasEmail)("rejects the example.com sender from .env.example", () => {
+    const env = { ...complete(), EMAIL_FROM: "App <no-reply@example.com>" };
+    expect(checkProductionEnv(env).invalid).toEqual([
+      "EMAIL_FROM still uses example.com: set a sender on a domain you verified",
+    ]);
+    expect(checkProductionEnv({ ...env, EMAIL_FROM: "App <hi@my-app.com>" }).invalid).toEqual([]);
+  });
+
+  it("tells local URLs from hosted ones", () => {
+    expect(isLocalUrl("http://localhost:3000")).toBe(true);
+    expect(isLocalUrl("redis://127.0.0.1:6379")).toBe(true);
+    expect(isLocalUrl("postgres://u:p@host.docker.internal/app")).toBe(true);
+    expect(isLocalUrl("postgresql://u:p@aws-0-eu-west-1.pooler.supabase.com:6543/postgres")).toBe(
+      false,
+    );
+    expect(isLocalUrl("rediss://default:pw@eu1-x.upstash.io:6379")).toBe(false);
+    expect(isLocalUrl("not a url")).toBe(false);
+  });
+});

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

@@ -0,0 +1,97 @@
+// The variables a production deploy needs, for the modules this project uses. Hosts that only run
+// the app (Vercel, Netlify) check them before the build with `pnpm check:env`, so a missing key
+// stops the deploy instead of shipping an app whose features fail at runtime.
+
+type Env = Record<string, string | undefined>;
+
+/**
+ * `url`: an absolute URL to a hosted service, not this machine. `serverless`: only on hosts that
+ * run no long-lived process (Vercel, Netlify).
+ */
+export type Requirement = { key: string; use: string; url?: boolean; serverless?: boolean };
+
+/** What every production deploy of this project needs. */
+export function requiredVariables(env: Env): Requirement[] {
+  const required: Requirement[] = [
+    { key: "DATABASE_URL", use: "the database", url: true },
+    { key: "APP_URL", use: "links in emails and redirects", url: true },
+    // clubedge:if auth=supabase
+    { key: "SUPABASE_URL", use: "Supabase Auth", url: true },
+    { key: "SUPABASE_PUBLISHABLE_KEY", use: "Supabase Auth" },
+    // clubedge:end
+    // clubedge:if auth=better-auth
+    { key: "BETTER_AUTH_SECRET", use: "Better Auth sessions" },
+    // clubedge:end
+    // clubedge:if cache=redis
+    { key: "REDIS_URL", use: "the cache and rate limits", url: true },
+    // clubedge:end
+    // clubedge:if storage=s3
+    { key: "STORAGE_BUCKET", use: "file storage" },
+    { key: "STORAGE_ACCESS_KEY_ID", use: "file storage" },
+    { key: "STORAGE_SECRET_ACCESS_KEY", use: "file storage" },
+    // clubedge:end
+    // clubedge:if email=smtp
+    { key: "SMTP_URL", use: "email", url: true },
+    // clubedge:end
+    // clubedge:if email=resend
+    { key: "RESEND_API_KEY", use: "email" },
+    // clubedge:end
+    // clubedge:if email=smtp|resend
+    { key: "EMAIL_FROM", use: "the sender of every email" },
+    // clubedge:end
+    // clubedge:if payments=stripe
+    { key: "STRIPE_SECRET_KEY", use: "payments" },
+    { key: "STRIPE_WEBHOOK_SECRET", use: "payments" },
+    { key: "STRIPE_PRICE_PRO", use: "payments" },
+    // clubedge:end
+    // clubedge:if jobs=pg-boss
+    // No jobs worker runs there: Vercel Cron or another scheduler calls /api/jobs/run with it.
+    { key: "CRON_SECRET", use: "background jobs, run by a cron", serverless: true },
+    // clubedge:end
+  ];
+  const serverless = Boolean(env.VERCEL || env.NETLIFY);
+  return required.filter((requirement) => serverless || !requirement.serverless);
+}
+
+/** The host of an absolute URL, or null for a value that isn't one. */
+function urlHost(value: string): string | null {
+  try {
+    return new URL(value.trim()).hostname.toLowerCase();
+  } catch {
+    return null;
+  }
+}
+
+/** A URL to this machine: from a development env file, unreachable from the deployed app. */
+export function isLocalUrl(value: string): boolean {
+  const host = urlHost(value);
+  if (host === null) return false;
+  return (
+    ["localhost", "127.0.0.1", "0.0.0.0", "[::1]", "host.docker.internal"].includes(host) ||
+    host.endsWith(".localhost")
+  );
+}
+
+export type ProductionEnvCheck = { missing: Requirement[]; local: string[]; invalid: string[] };
+
+/** The required variables that are unset, point at this machine, or have an unusable value. */
+export function checkProductionEnv(env: Env): ProductionEnvCheck {
+  const required = requiredVariables(env);
+  const missing = required.filter(({ key }) => !env[key]?.trim());
+  const urls = required.filter(({ key, url }) => url && env[key]?.trim());
+  const local = urls.filter(({ key }) => isLocalUrl(env[key]!)).map(({ key }) => key);
+  const invalid = urls
+    .filter(({ key }) => urlHost(env[key]!) === null)
+    .map(({ key }) => `${key} is not an absolute URL`);
+  // clubedge:if auth=better-auth
+  const secret = env.BETTER_AUTH_SECRET?.trim();
+  if (secret && secret.length < 32) invalid.push("BETTER_AUTH_SECRET needs at least 32 characters");
+  // clubedge:end
+  // clubedge:if email=smtp|resend
+  // .env.example's placeholder sender: providers refuse a domain you haven't verified.
+  if (/@example\.com\b/i.test(env.EMAIL_FROM ?? "")) {
+    invalid.push("EMAIL_FROM still uses example.com: set a sender on a domain you verified");
+  }
+  // clubedge:end
+  return { missing, local, invalid };
+}

package/template/apps/start/vercel.json

@@ -1,5 +1,5 @@
 {
   "$schema": "https://openapi.vercel.sh/vercel.json",
   "framework": null,
-  "buildCommand": "pnpm --dir ../.. db:migrate && pnpm run build"
+  "buildCommand": "pnpm run check:env && pnpm --dir ../.. db:migrate && pnpm run build"
 }

package/template/apps/web/netlify.toml

@@ -1,6 +1,7 @@
 # Netlify (https://docs.netlify.com/configure-builds/file-based-configuration/). Set the site's
 # base directory to apps/web; Netlify installs its Next.js runtime automatically.
 [build]
-  # Migrations run during the build, against the DATABASE_URL set for the deploy context.
-  command = "pnpm --dir ../.. db:migrate && pnpm run build"
+  # check:env stops the build when a variable the project needs is unset; then migrations run,
+  # against the DATABASE_URL set for the deploy context.
+  command = "pnpm run check:env && pnpm --dir ../.. db:migrate && pnpm run build"
   publish = ".next"

package/template/apps/web/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/web",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "private": true,
   "license": "Apache-2.0",
   "scripts": {
@@ -8,7 +8,8 @@
     "build": "next build",
     "start": "node scripts/start-standalone.mjs",
     "typecheck": "tsc --noEmit",
-    "check:services": "tsx scripts/check-services.ts"
+    "check:services": "tsx scripts/check-services.ts",
+    "check:env": "tsx scripts/check-env.ts"
   },
   "dependencies": {
     "@clubedge/auth": "workspace:*",

package/template/apps/web/scripts/check-env.ts

@@ -0,0 +1,34 @@
+// Checks the production variables before a deploy build: `pnpm check:env`. Vercel's and Netlify's
+// build commands run it first, so a missing key stops the build. It reads the build's environment,
+// not .env.local; SKIP_ENV_CHECK=1 builds anyway.
+import { checkProductionEnv } from "../src/env/production";
+
+function main() {
+  if (process.env.SKIP_ENV_CHECK === "1") {
+    console.warn(
+      "check:env skipped (SKIP_ENV_CHECK=1): missing variables fail at runtime instead.",
+    );
+    return;
+  }
+  const { missing, local, invalid } = checkProductionEnv(process.env);
+  if (!missing.length && !local.length && !invalid.length) {
+    console.log("✓  check:env: every production variable this project needs is set.");
+    return;
+  }
+  const lines = [
+    ...missing.map(({ key, use }) => `✗  ${key} is not set (${use})`),
+    ...local.map((key) => `✗  ${key} points at localhost, which the deployed app can't reach`),
+    ...invalid.map((problem) => `✗  ${problem}`),
+  ];
+  console.error(
+    [
+      "check:env: the production environment is incomplete, so the build stops here.",
+      ...lines,
+      "Fix them in the host's environment variables for this environment (Production or Preview),",
+      "then deploy again. SKIP_ENV_CHECK=1 builds anyway.",
+    ].join("\n"),
+  );
+  process.exit(1);
+}
+
+main();

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

@@ -0,0 +1,65 @@
+import { describe, expect, it } from "vitest";
+import { checkProductionEnv, isLocalUrl, requiredVariables } from "./production";
+
+// A value for every variable this project requires, whichever modules it has.
+const complete = (extra: Record<string, string> = {}) => {
+  const env: Record<string, string> = { ...extra };
+  for (const { key } of requiredVariables(extra)) env[key] ??= "https://service.example.com";
+  if ("BETTER_AUTH_SECRET" in env) env.BETTER_AUTH_SECRET = "x".repeat(32);
+  return env;
+};
+
+describe("production env check", () => {
+  it("passes when every required variable is set", () => {
+    expect(checkProductionEnv(complete())).toEqual({ missing: [], local: [], invalid: [] });
+    expect(checkProductionEnv(complete({ VERCEL: "1" }))).toEqual({
+      missing: [],
+      local: [],
+      invalid: [],
+    });
+  });
+
+  it("always requires the database and the public URL", () => {
+    const keys = checkProductionEnv({}).missing.map(({ key }) => key);
+    expect(keys).toContain("DATABASE_URL");
+    expect(keys).toContain("NEXT_PUBLIC_APP_URL");
+  });
+
+  it("counts empty values as unset", () => {
+    const env = { ...complete(), DATABASE_URL: "  " };
+    expect(checkProductionEnv(env).missing.map(({ key }) => key)).toEqual(["DATABASE_URL"]);
+  });
+
+  it("rejects URLs to this machine", () => {
+    const env = {
+      ...complete(),
+      DATABASE_URL: "postgresql://postgres:postgres@localhost:5432/app",
+    };
+    expect(checkProductionEnv(env).local).toEqual(["DATABASE_URL"]);
+  });
+
+  it("rejects a URL that isn't absolute", () => {
+    const env = { ...complete(), NEXT_PUBLIC_APP_URL: "my-app.vercel.app" };
+    expect(checkProductionEnv(env).invalid).toEqual(["NEXT_PUBLIC_APP_URL is not an absolute URL"]);
+  });
+
+  const hasEmail = requiredVariables({}).some(({ key }) => key === "EMAIL_FROM");
+  it.runIf(hasEmail)("rejects the example.com sender from .env.example", () => {
+    const env = { ...complete(), EMAIL_FROM: "App <no-reply@example.com>" };
+    expect(checkProductionEnv(env).invalid).toEqual([
+      "EMAIL_FROM still uses example.com: set a sender on a domain you verified",
+    ]);
+    expect(checkProductionEnv({ ...env, EMAIL_FROM: "App <hi@my-app.com>" }).invalid).toEqual([]);
+  });
+
+  it("tells local URLs from hosted ones", () => {
+    expect(isLocalUrl("http://localhost:3000")).toBe(true);
+    expect(isLocalUrl("redis://127.0.0.1:6379")).toBe(true);
+    expect(isLocalUrl("postgres://u:p@host.docker.internal/app")).toBe(true);
+    expect(isLocalUrl("postgresql://u:p@aws-0-eu-west-1.pooler.supabase.com:6543/postgres")).toBe(
+      false,
+    );
+    expect(isLocalUrl("rediss://default:pw@eu1-x.upstash.io:6379")).toBe(false);
+    expect(isLocalUrl("not a url")).toBe(false);
+  });
+});

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

@@ -0,0 +1,97 @@
+// The variables a production deploy needs, for the modules this project uses. Hosts that only run
+// the app (Vercel, Netlify) check them before the build with `pnpm check:env`, so a missing key
+// stops the deploy instead of shipping an app whose features fail at runtime.
+
+type Env = Record<string, string | undefined>;
+
+/**
+ * `url`: an absolute URL to a hosted service, not this machine. `serverless`: only on hosts that
+ * run no long-lived process (Vercel, Netlify).
+ */
+export type Requirement = { key: string; use: string; url?: boolean; serverless?: boolean };
+
+/** What every production deploy of this project needs. */
+export function requiredVariables(env: Env): Requirement[] {
+  const required: Requirement[] = [
+    { key: "DATABASE_URL", use: "the database", url: true },
+    { key: "NEXT_PUBLIC_APP_URL", use: "links in emails and redirects", url: true },
+    // clubedge:if auth=supabase
+    { key: "NEXT_PUBLIC_SUPABASE_URL", use: "Supabase Auth", url: true },
+    { key: "NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY", use: "Supabase Auth" },
+    // clubedge:end
+    // clubedge:if auth=better-auth
+    { key: "BETTER_AUTH_SECRET", use: "Better Auth sessions" },
+    // clubedge:end
+    // clubedge:if cache=redis
+    { key: "REDIS_URL", use: "the cache and rate limits", url: true },
+    // clubedge:end
+    // clubedge:if storage=s3
+    { key: "STORAGE_BUCKET", use: "file storage" },
+    { key: "STORAGE_ACCESS_KEY_ID", use: "file storage" },
+    { key: "STORAGE_SECRET_ACCESS_KEY", use: "file storage" },
+    // clubedge:end
+    // clubedge:if email=smtp
+    { key: "SMTP_URL", use: "email", url: true },
+    // clubedge:end
+    // clubedge:if email=resend
+    { key: "RESEND_API_KEY", use: "email" },
+    // clubedge:end
+    // clubedge:if email=smtp|resend
+    { key: "EMAIL_FROM", use: "the sender of every email" },
+    // clubedge:end
+    // clubedge:if payments=stripe
+    { key: "STRIPE_SECRET_KEY", use: "payments" },
+    { key: "STRIPE_WEBHOOK_SECRET", use: "payments" },
+    { key: "STRIPE_PRICE_PRO", use: "payments" },
+    // clubedge:end
+    // clubedge:if jobs=pg-boss
+    // No jobs worker runs there: Vercel Cron or another scheduler calls /api/jobs/run with it.
+    { key: "CRON_SECRET", use: "background jobs, run by a cron", serverless: true },
+    // clubedge:end
+  ];
+  const serverless = Boolean(env.VERCEL || env.NETLIFY);
+  return required.filter((requirement) => serverless || !requirement.serverless);
+}
+
+/** The host of an absolute URL, or null for a value that isn't one. */
+function urlHost(value: string): string | null {
+  try {
+    return new URL(value.trim()).hostname.toLowerCase();
+  } catch {
+    return null;
+  }
+}
+
+/** A URL to this machine: from a development env file, unreachable from the deployed app. */
+export function isLocalUrl(value: string): boolean {
+  const host = urlHost(value);
+  if (host === null) return false;
+  return (
+    ["localhost", "127.0.0.1", "0.0.0.0", "[::1]", "host.docker.internal"].includes(host) ||
+    host.endsWith(".localhost")
+  );
+}
+
+export type ProductionEnvCheck = { missing: Requirement[]; local: string[]; invalid: string[] };
+
+/** The required variables that are unset, point at this machine, or have an unusable value. */
+export function checkProductionEnv(env: Env): ProductionEnvCheck {
+  const required = requiredVariables(env);
+  const missing = required.filter(({ key }) => !env[key]?.trim());
+  const urls = required.filter(({ key, url }) => url && env[key]?.trim());
+  const local = urls.filter(({ key }) => isLocalUrl(env[key]!)).map(({ key }) => key);
+  const invalid = urls
+    .filter(({ key }) => urlHost(env[key]!) === null)
+    .map(({ key }) => `${key} is not an absolute URL`);
+  // clubedge:if auth=better-auth
+  const secret = env.BETTER_AUTH_SECRET?.trim();
+  if (secret && secret.length < 32) invalid.push("BETTER_AUTH_SECRET needs at least 32 characters");
+  // clubedge:end
+  // clubedge:if email=smtp|resend
+  // .env.example's placeholder sender: providers refuse a domain you haven't verified.
+  if (/@example\.com\b/i.test(env.EMAIL_FROM ?? "")) {
+    invalid.push("EMAIL_FROM still uses example.com: set a sender on a domain you verified");
+  }
+  // clubedge:end
+  return { missing, local, invalid };
+}

package/template/apps/web/vercel.json

@@ -1,5 +1,5 @@
 {
   "$schema": "https://openapi.vercel.sh/vercel.json",
   "framework": "nextjs",
-  "buildCommand": "pnpm --dir ../.. db:migrate && pnpm run build"
+  "buildCommand": "pnpm run check:env && pnpm --dir ../.. db:migrate && pnpm run build"
 }

package/template/clubedge.template.json

@@ -425,6 +425,7 @@
     "apps/start/scripts/check-services.ts",
     "apps/start/src/components/route-error.tsx",
     "apps/start/src/env/auth.ts",
+    "apps/start/src/env/production.ts",
     "apps/start/src/jobs/index.ts",
     "apps/start/src/routes/__root.tsx",
     "apps/start/src/routes/dashboard.tsx",
@@ -442,6 +443,7 @@
     "apps/web/src/app/page.tsx",
     "apps/web/src/app/settings/actions.ts",
     "apps/web/src/env/auth.ts",
+    "apps/web/src/env/production.ts",
     "apps/web/src/instrumentation.ts",
     "apps/web/src/jobs/index.ts",
     "apps/web/src/server/auth-email.ts",
@@ -451,6 +453,7 @@
     "supabase/config.toml"
   ],
   "exclude": [
+    ".github/dependabot.yml",
     ".github/workflows/starter.yml",
     "ROADMAP.md",
     "clubedge.template.json",

package/template/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clubedge-starter-v1",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "private": true,
   "license": "Apache-2.0",
   "packageManager": "pnpm@10.9.0",
@@ -29,6 +29,7 @@
     "docker:build": "docker build -t clubedge-starter .",
     "docker:start": "docker run --rm -p 3000:3000 --env-file apps/web/.env.local clubedge-starter",
     "check:services": "pnpm --filter @clubedge/web check:services",
+    "check:env": "pnpm --filter @clubedge/web check:env",
     "clubedge": "pnpm dlx @clubedge/create-clubedge-app@latest",
     "infra:up": "docker compose -f docker-compose.dev.yml up -d --wait",
     "infra:down": "docker compose -f docker-compose.dev.yml down",

package/template/packages/auth/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/auth",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "private": true,
   "license": "Apache-2.0",
   "type": "module",

package/template/packages/auth-better-auth/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/auth-better-auth",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "description": "Better Auth adapter for @clubedge/auth, storing users and sessions in your own PostgreSQL.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/auth-supabase/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/auth-supabase",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "description": "Supabase Auth adapter for @clubedge/auth.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/cache/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/cache",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "private": true,
   "license": "Apache-2.0",
   "type": "module",

package/template/packages/cache-redis/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/cache-redis",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "description": "Redis rate limiter and cache for @clubedge/cache.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/core",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "private": true,
   "license": "Apache-2.0",
   "type": "module",

package/template/packages/db/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/db",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "private": true,
   "license": "Apache-2.0",
   "type": "module",

package/template/packages/email/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/email",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "description": "Email interface, console and in-memory providers, and message templates.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/email-resend/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/email-resend",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "description": "Resend provider for @clubedge/email, through Resend's HTTP API.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/email-smtp/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/email-smtp",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "description": "SMTP provider for @clubedge/email, for any SMTP server.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/jobs/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/jobs",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "description": "Background jobs interface: job definitions, a queue contract, and an in-memory queue.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/jobs-pg-boss/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/jobs-pg-boss",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "description": "pg-boss provider for @clubedge/jobs: a job queue stored in the project's PostgreSQL.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/local-db/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/local-db",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "description": "PostgreSQL for development without Docker: PGlite served over the PostgreSQL protocol.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/observability/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/observability",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "description": "Observability interface: error reports and spans for @clubedge/core's telemetry hooks, and an in-memory provider for tests.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/observability-otel/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/observability-otel",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "description": "OpenTelemetry provider for @clubedge/observability: traces and error logs exported over OTLP to any collector.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/observability-sentry/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/observability-sentry",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "description": "Sentry provider for @clubedge/observability: server and browser errors, traces, and source map uploads.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/payments/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/payments",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "description": "Provider-neutral payments: the PaymentProvider interface, billing logic, and subscription tables.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/payments-stripe/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/payments-stripe",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "description": "Stripe provider for @clubedge/payments: Checkout, the customer portal, and verified webhooks.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/storage/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/storage",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "private": true,
   "license": "Apache-2.0",
   "type": "module",

package/template/packages/storage-s3/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/storage-s3",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "description": "S3-compatible adapter for @clubedge/storage.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/storage-supabase/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/storage-supabase",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "description": "Supabase Storage adapter for @clubedge/storage.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/ui/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/ui",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "private": true,
   "license": "Apache-2.0",
   "type": "module",

package/template.lock.json

@@ -1,7 +1,7 @@
 {
   "repository": "Clubedge/clubedge-starter",
-  "ref": "v0.17.1",
-  "commit": "d9d787b6750e862b9de81a3f8f36b7aa07757f7a",
+  "ref": "v0.18.0",
+  "commit": "bcd084d7d2d2aac0600ccb35491f48c251fb3a74",
   "files": [
     ".dockerignore",
     ".env.example",
@@ -36,6 +36,7 @@
     "apps/start/package.json",
     "apps/start/public/.well-known/logo.svg",
     "apps/start/public/favicon.ico",
+    "apps/start/scripts/check-env.ts",
     "apps/start/scripts/check-services.ts",
     "apps/start/src/components/auth/auth-form-controls.tsx",
     "apps/start/src/components/auth/auth-page.tsx",
@@ -57,6 +58,8 @@
     "apps/start/src/config/site.ts",
     "apps/start/src/env/auth.test.ts",
     "apps/start/src/env/auth.ts",
+    "apps/start/src/env/production.test.ts",
+    "apps/start/src/env/production.ts",
     "apps/start/src/env/server.test.ts",
     "apps/start/src/env/server.ts",
     "apps/start/src/jobs/index.ts",
@@ -136,6 +139,7 @@
     "apps/web/postcss.config.mjs",
     "apps/web/public/.gitkeep",
     "apps/web/public/.well-known/logo.svg",
+    "apps/web/scripts/check-env.ts",
     "apps/web/scripts/check-services.ts",
     "apps/web/scripts/start-standalone.mjs",
     "apps/web/src/app/actions/auth.ts",
@@ -177,6 +181,8 @@
     "apps/web/src/config/site.ts",
     "apps/web/src/env/auth.ts",
     "apps/web/src/env/client.ts",
+    "apps/web/src/env/production.test.ts",
+    "apps/web/src/env/production.ts",
     "apps/web/src/env/server.test.ts",
     "apps/web/src/env/server.ts",
     "apps/web/src/instrumentation.ts",