@clubedge/create-clubedge-app 0.25.0 → 0.27.0

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 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.
+  - With `DATABASE_URL` or `REDIS_URL` in the env file (Supabase, Neon, Upstash), `deploy` creates no Railway or Fly database for it, sets your URL, and the platform only runs the app. Each URL counts on its own, so only `DATABASE_URL` keeps Redis on the platform.
+  - `deploy` reads `.env.production` from the project's root when there is one and no `--env-file` is given. An `--env-file` that doesn't exist is now a clear error.
+  - URLs to `localhost` (a development env file) are ignored with a warning.
+  - A later run without the env file keeps the database URL the service already has, instead of creating the platform's database and switching the app over. On Railway, `deploy` stops before changing anything if it can't list an existing service's variables. On Fly, an existing `DATABASE_URL` secret skips creating `<app>-db`.
+  - When the app moves from Railway's database to its own, `deploy` notes that the old one is unused; it never deletes it.
+- The showcase records a `try` walkthrough on a free Railway VM (#73).
+- `pnpm release` counts squash-merged pull requests in the changelog draft (#75).
+- Still on Starter `v0.17.1`.
+
 ## 0.25.0
 
 - `deploy` for Fly.io (experimental) (#71): in a project with `deploy fly`, `pnpm clubedge deploy` uses Fly's CLI and your Fly login.

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.
@@ -194,43 +194,43 @@ When the app is ready, the CLI opens the preview in your browser (`--no-open` tu
 In a project created with `--deploy railway` (or switched with `pnpm clubedge add deploy railway`), one command does the first deploy:
 
 ```sh
-pnpm clubedge deploy                              # asks before creating anything
-pnpm clubedge deploy --env-file .env.production   # with your production provider keys
+pnpm clubedge deploy                              # asks before creating anything; reads .env.production
+pnpm clubedge deploy --env-file .env.staging      # with another file of production keys
 pnpm clubedge deploy --dry-run                    # show the plan, create nothing
 ```
 
-With [Railway's CLI](https://docs.railway.com/cli) (the installed `railway`, or `npx @railway/cli`) and your Railway login, it creates or reuses a project named after the package, Postgres (and Redis with `cache redis`), the app's service, and a `*.up.railway.app` domain. It sets the variables it can: `DATABASE_URL` and `REDIS_URL` as references to those databases, `APP_URL` and `NEXT_PUBLIC_APP_URL`, `PORT`, and a generated `BETTER_AUTH_SECRET` that later runs keep. Values from `--env-file` come on top; the variables `.env.example` lists that nothing sets are reported, for the modules that need them (storage, email, payments). The service's settings (the migrations before each release, the `/api/health` check) go in `.railway/railway.ts`, Railway's configuration as code, which replaces `railway.json` (Railway stops reading it on 2026-12-01): `deploy` writes it when the project has none, adds Railway's TypeScript SDK (`railway`) as a dev dependency, and applies it with `railway config apply`; commit them. Then `railway up` builds the Dockerfile, and `deploy` waits for Railway's final status before printing the URL. It needs Railway CLI 5.42.1 or newer: an installed `railway`, else one npx already downloaded, else it downloads one. Running `deploy` again reuses everything, so it also adds variables and ships a new release. Railway bills usage on your plan.
+With [Railway's CLI](https://docs.railway.com/cli) (the installed `railway`, or `npx @railway/cli`) and your Railway login, it creates or reuses a project named after the package, Postgres (and Redis with `cache redis`), the app's service, and a `*.up.railway.app` domain. It sets the variables it can: `DATABASE_URL` and `REDIS_URL` as references to those databases, `APP_URL` and `NEXT_PUBLIC_APP_URL`, `PORT`, and a generated `BETTER_AUTH_SECRET` that later runs keep. Values from the env file (`.env.production` when there is one, or `--env-file`) come on top. With a `DATABASE_URL` or `REDIS_URL` in it (Supabase, Neon, Upstash), `deploy` creates no Railway database for it and the app uses yours; URLs to `localhost` are ignored, and a later run without the file keeps the URL the service has. The variables `.env.example` lists that nothing sets are reported, for the modules that need them (storage, email, payments). The service's settings (the migrations before each release, the `/api/health` check) go in `.railway/railway.ts`, Railway's configuration as code, which replaces `railway.json` (Railway stops reading it on 2026-12-01): `deploy` writes it when the project has none, adds Railway's TypeScript SDK (`railway`) as a dev dependency, and applies it with `railway config apply`; commit them. Then `railway up` builds the Dockerfile, and `deploy` waits for Railway's final status before printing the URL. It needs Railway CLI 5.42.1 or newer: an installed `railway`, else one npx already downloaded, else it downloads one. Running `deploy` again reuses everything, so it also adds variables and ships a new release. Railway bills usage on your plan.
 
 ### Deploy to Fly.io (experimental)
 
-In a project with `--deploy fly`, `pnpm clubedge deploy` does the same with [Fly's CLI](https://fly.io/docs/flyctl/install/) (install it first; it is not on npm) and your Fly login: it creates the app (`fly launch`, which writes its name and region into `fly.toml`; commit it), an unmanaged Postgres app attached as `DATABASE_URL` (one `shared-cpu-1x` machine and a 1 GB volume), Upstash Redis with `cache redis`, and imports the secrets (the public URL `https://<app>.fly.dev`, a kept `BETTER_AUTH_SECRET`, and `--env-file` values). Then `fly deploy` builds the Dockerfile with `NEXT_PUBLIC_APP_URL` as a build argument, runs the migrations as the release command, and waits for the health checks. Fly bills these on your plan; for Fly's Managed Postgres, create and attach it yourself before deploying. Running it again reuses everything.
+In a project with `--deploy fly`, `pnpm clubedge deploy` does the same with [Fly's CLI](https://fly.io/docs/flyctl/install/) (install it first; it is not on npm) and your Fly login: it creates the app (`fly launch`, which writes its name and region into `fly.toml`; commit it), an unmanaged Postgres app attached as `DATABASE_URL` (one `shared-cpu-1x` machine and a 1 GB volume) and Upstash Redis with `cache redis`, each unless the env file has its URL, and imports the secrets (the public URL `https://<app>.fly.dev`, a kept `BETTER_AUTH_SECRET`, and `--env-file` values). Then `fly deploy` builds the Dockerfile with `NEXT_PUBLIC_APP_URL` as a build argument, runs the migrations as the release command, and waits for the health checks. Fly bills these on your plan; for Fly's Managed Postgres, create and attach it yourself before deploying. Running it again reuses everything.
 
 ## Version relationship
 
 Each CLI release is tested against one specific Starter release:
 
 ```text
-create-clubedge-app v0.25.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.25.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
 
@@ -320,6 +320,8 @@ Each phase ends with a Starter release and a CLI release pinned to it. The full
 | 0.23.0 | v0.16.1 | `deploy` moves Railway projects to `.railway/railway.ts` before Railway stops reading `railway.json` |
 | 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/dist/core/deploy.js

@@ -9,9 +9,40 @@ export function serviceName(packageName) {
     const name = packageName.replace(/^@[^/]+\//, "").toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "");
     return name || "web";
 }
-/** The databases a project needs on Railway: Postgres always (Drizzle), Redis with the redis cache. */
-export function databasesFor(modules) {
-    return modules.cache === "redis" ? ["postgres", "redis"] : ["postgres"];
+/** The variable each database's URL goes in. */
+export const databaseVariables = { postgres: "DATABASE_URL", redis: "REDIS_URL" };
+/** A URL to this machine: from a development env file, unreachable from the deployed app. */
+export function isLocalUrl(value) {
+    const host = /^[a-z][a-z0-9+.-]*:\/\/(?:[^@/]*@)?(\[[^\]]*\]|[^:/?#]*)/i.exec(value.trim())?.[1]?.toLowerCase() ?? "";
+    return ["localhost", "127.0.0.1", "0.0.0.0", "[::1]", "host.docker.internal"].includes(host) || host.endsWith(".localhost");
+}
+/**
+ * The database URLs an env file provides, for databases hosted elsewhere (Supabase, Neon, Upstash):
+ * deploy uses them instead of creating the platform's own. Only the databases the project uses
+ * count, and not empty or local URLs.
+ */
+export function externalDatabaseUrls(modules, envFile) {
+    const urls = {};
+    for (const database of databasesFor(modules)) {
+        const key = databaseVariables[database];
+        const value = envFile[key];
+        if (value && !isLocalUrl(value))
+            urls[key] = value;
+    }
+    return urls;
+}
+/**
+ * The databases a project needs from the platform: Postgres always (Drizzle), Redis with the redis
+ * cache, except the ones whose URL comes from elsewhere (`external`: variable names).
+ */
+export function databasesFor(modules, external = []) {
+    const skip = new Set(external);
+    const needed = modules.cache === "redis" ? ["postgres", "redis"] : ["postgres"];
+    return needed.filter((database) => !skip.has(databaseVariables[database]));
+}
+/** References to Railway's databases, for the service's variables. */
+export function railwayReferences(databases) {
+    return Object.fromEntries(databases.map((database) => [databaseVariables[database], `\${{${railwayDatabases[database]}.${databaseVariables[database]}}}`]));
 }
 /** The variable names a project's .env.example lists, in order. */
 export function exampleKeys(example) {
@@ -36,30 +67,29 @@ export function parseEnvFile(text) {
     return values;
 }
 /**
- * The service's production variables. The CLI provides what it can: references to Railway's
- * databases, a generated Better Auth secret (unless the service already has one), the public URL,
- * and the port. Values from --env-file come next and win over those, except the database
- * references, which must point at Railway's databases. Everything else the example lists is
- * reported as unset; values the service already has count as set.
+ * The service's production variables. The CLI provides what it can: the database URLs (references
+ * to Railway's databases by default), a generated Better Auth secret (unless the service already
+ * has one), the public URL, and the port. Values from --env-file come next and win over those;
+ * their database URLs replace the platform's, except local ones (a development env file).
+ * Everything else the example lists is reported as unset; values the service already has count as set.
  */
 export function planVariables(input) {
     const { modules, keys, url, envFile, secret, attached = [] } = input;
     const existing = { ...input.existing, ...Object.fromEntries(attached.map((key) => [key, "(attached)"])) };
-    const reference = (database, variable) => `\${{${database}.${variable}}}`;
-    const databases = input.databases ?? {
-        DATABASE_URL: reference(railwayDatabases.postgres, "DATABASE_URL"),
-        ...(modules.cache === "redis" ? { REDIS_URL: reference(railwayDatabases.redis, "REDIS_URL") } : {}),
-    };
+    const external = externalDatabaseUrls(modules, envFile);
+    const databases = input.databases ?? railwayReferences(databasesFor(modules, Object.keys(external)));
     const provided = { NODE_ENV: "production", PORT: String(appPort), ...databases };
     // The public URL under both names: TanStack Start reads APP_URL, Next.js NEXT_PUBLIC_APP_URL.
     const set = { ...provided, APP_URL: url, NEXT_PUBLIC_APP_URL: url };
     if (modules.auth === "better-auth" && !existing.BETTER_AUTH_SECRET)
         set.BETTER_AUTH_SECRET = secret();
+    const databaseKeys = Object.values(databaseVariables);
     for (const [key, value] of Object.entries(envFile)) {
-        if (key === "DATABASE_URL" || key === "REDIS_URL" || value === "")
+        if (value === "" || databaseKeys.includes(key))
             continue;
         set[key] = value;
     }
+    Object.assign(set, external);
     const unset = keys.filter((key) => set[key] === undefined && !existing[key]);
     return { set, unset };
 }

package/dist/deploy-fly.js

@@ -1,14 +1,15 @@
 // `deploy` for Fly.io (experimental): creates or reuses the app (written to fly.toml), an
-// unmanaged Postgres attached as DATABASE_URL, Upstash Redis with cache redis, sets the secrets,
-// and runs `fly deploy`, which waits for the release command (migrations) and the health checks.
+// unmanaged Postgres attached as DATABASE_URL, Upstash Redis with cache redis (each unless the env
+// file points it elsewhere), sets the secrets, and runs `fly deploy`, which waits for the release
+// command (migrations) and the health checks.
 import { cancel, confirm, isCancel, log, note, outro, spinner } from "@clack/prompts";
 import { randomBytes } from "node:crypto";
 import { readFile } from "node:fs/promises";
-import { join, resolve } from "node:path";
+import { join } from "node:path";
 import process from "node:process";
 import { UsageError } from "./cli/args.js";
 import { bold, dim } from "./cli/ui.js";
-import { exampleKeys, flyAppUrl, flySecretNames, flySecretsInput, flyTomlValue, parseEnvFile, parseRedisUrl, planVariables, serviceName, } from "./core/deploy.js";
+import { exampleKeys, externalDatabaseUrls, flyAppUrl, flySecretNames, flySecretsInput, flyTomlValue, parseRedisUrl, planVariables, serviceName, } from "./core/deploy.js";
 import { spawnCommand } from "./utils/process.js";
 const flyInstallUrl = "https://fly.io/docs/flyctl/install/";
 const flyPricingUrl = "https://fly.io/docs/about/pricing/";
@@ -42,7 +43,7 @@ async function flyCli(cwd) {
     }
     throw new UsageError(`deploy to Fly.io needs Fly's CLI. Install it (${flyInstallUrl}), then run deploy again.`);
 }
-export async function deployToFly(args, project, cli) {
+export async function deployToFly(args, project, cli, envFile) {
     const root = project.root;
     const tomlPath = join(root, "fly.toml");
     const toml = await readFile(tomlPath, "utf8").catch(() => "");
@@ -51,16 +52,25 @@ export async function deployToFly(args, project, cli) {
     const named = flyTomlValue(toml, "app");
     // Fly app names are global: a new app gets a short random suffix.
     const app = named ?? `${serviceName(project.identity.packageName)}-${randomBytes(2).toString("hex")}`;
-    const redis = project.modules.cache === "redis";
     const keys = exampleKeys(await readFile(join(root, ".env.example"), "utf8").catch(() => ""));
-    const envFile = args.envFile ? parseEnvFile(await readFile(resolve(process.cwd(), args.envFile), "utf8")) : {};
+    const external = externalDatabaseUrls(project.modules, envFile);
+    // The databases to create on Fly: the ones the env file doesn't point elsewhere.
+    const postgres = !external.DATABASE_URL;
+    const redis = project.modules.cache === "redis" && !external.REDIS_URL;
+    const elsewhere = Object.keys(external);
+    const hostedLine = [
+        ...(postgres ? [`a Postgres app "${app}-db" (unmanaged: one shared-cpu-1x machine and a 1 GB volume)`] : []),
+        ...(redis ? [`Upstash Redis "${app}-redis"`] : []),
+    ];
     const secret = () => randomBytes(32).toString("hex");
     const url = flyAppUrl(app);
     if (args.dryRun) {
-        const preview = planVariables({ modules: project.modules, keys, url, existing: {}, envFile, secret: () => "<generated>", databases: {}, attached: ["DATABASE_URL", ...(redis ? ["REDIS_URL"] : [])] });
+        const preview = planVariables({ modules: project.modules, keys, url, existing: {}, envFile, secret: () => "<generated>", databases: {}, attached: [...(postgres ? ["DATABASE_URL"] : []), ...(redis ? ["REDIS_URL"] : [])] });
         log.message([
             `• Fly app "${app}"${named ? " (from fly.toml)" : ", written to fly.toml"}, at ${url}`,
-            `• Postgres "${app}-db" (unmanaged, one small machine), attached as DATABASE_URL${redis ? `; Upstash Redis "${app}-redis" as REDIS_URL` : ""}`,
+            ...(postgres ? [`• Postgres "${app}-db" (unmanaged, one small machine), attached as DATABASE_URL`] : []),
+            ...(redis ? [`• Upstash Redis "${app}-redis" as REDIS_URL`] : []),
+            ...(elsewhere.length ? [`• ${elsewhere.join(" and ")} from the env file, instead of Fly's databases`] : []),
             `• Secrets: ${Object.keys(preview.set).join(", ")}`,
             ...(preview.unset.length ? [`• Not set: ${preview.unset.join(", ")}`] : []),
             `• fly deploy, with NEXT_PUBLIC_APP_URL as a build argument: migrations, then health checks`,
@@ -71,7 +81,8 @@ export async function deployToFly(args, project, cli) {
     note([
         "This deploys the project to Fly.io, in your Fly account (experimental):",
         "",
-        `• The app "${app}", a Postgres app "${app}-db" (unmanaged: one shared-cpu-1x machine and a 1 GB volume)${redis ? `, and Upstash Redis "${app}-redis"` : ""}.`,
+        `• The app "${app}"${hostedLine.length ? `, ${hostedLine.join(", and ")}` : ""}.`,
+        ...(elsewhere.length ? [`• ${elsewhere.join(" and ")} from the env file: those databases stay where they are, and Fly runs the app.`] : []),
         "• The secrets Fly can't provide come from --env-file; the ones still unset are listed before the build.",
         "• fly deploy builds the Dockerfile, runs the migrations as the release command, and waits for the health checks.",
         "",
@@ -105,12 +116,13 @@ export async function deployToFly(args, project, cli) {
     const region = flyTomlValue(await readFile(tomlPath, "utf8"), "primary_region");
     const regionArgs = region ? ["--region", region] : [];
     const secrets = new Set(flySecretNames((await attempt(() => fly(flyBin, ["secrets", "list", "--app", app, "--json"], root))) ?? ""));
+    // A DATABASE_URL secret already set (Fly's attach, or an earlier env file) is kept as it is.
     const database = `${app}-db`;
-    if (!(await attempt(() => fly(flyBin, ["status", "--app", database], root)))) {
+    if (postgres && !secrets.has("DATABASE_URL") && !(await attempt(() => fly(flyBin, ["status", "--app", database], root)))) {
         progress.message(`Creating Postgres "${database}"`);
         await fly(flyBin, ["postgres", "create", "--name", database, "--org", "personal", ...regionArgs, "--initial-cluster-size", "1", "--vm-size", "shared-cpu-1x", "--volume-size", "1", "--autostart"], root);
     }
-    if (!secrets.has("DATABASE_URL")) {
+    if (postgres && !secrets.has("DATABASE_URL")) {
         progress.message("Attaching Postgres (DATABASE_URL)");
         await fly(flyBin, ["postgres", "attach", database, "--app", app, "--yes"], root);
     }
@@ -128,7 +140,7 @@ export async function deployToFly(args, project, cli) {
         envFile,
         secret,
         databases: redisUrl ? { REDIS_URL: redisUrl } : {},
-        attached: ["DATABASE_URL", ...(redis && !redisUrl && secrets.has("REDIS_URL") ? ["REDIS_URL"] : [])],
+        attached: [...(postgres ? ["DATABASE_URL"] : []), ...(redis && !redisUrl && secrets.has("REDIS_URL") ? ["REDIS_URL"] : [])],
     });
     // The image sets NODE_ENV and fly.toml the port: the rest are secrets, staged for the deploy.
     const { NODE_ENV: _node, PORT: _port, ...values } = plan.set;

package/dist/deploy.js

@@ -1,6 +1,7 @@
 // `deploy`: a guided first deploy to Railway, with Railway's own CLI. It creates (or reuses) the
-// project, its databases, the app's service and domain, sets the production variables, and runs
-// `railway up`; Railway then builds the image, runs the migrations, and checks /api/health.
+// project, the databases the env file doesn't point elsewhere, the app's service and domain, sets
+// the production variables, and runs `railway up`; Railway then builds the image, runs the
+// migrations, and checks /api/health.
 import { cancel, confirm, isCancel, log, note, outro, spinner } from "@clack/prompts";
 import { spawn } from "node:child_process";
 import { randomBytes } from "node:crypto";
@@ -10,7 +11,7 @@ import { dirname, join, resolve } from "node:path";
 import process from "node:process";
 import { UsageError } from "./cli/args.js";
 import { bold, dim } from "./cli/ui.js";
-import { appPort, databasesFor, deploymentStatus, exampleKeys, finalStatuses, meetsMinimumCli, minimumRailwayCli, parseDeploymentId, parseEnvFile, parseRailwayDomain, parseVariables, planVariables, railwayCliVersion, railwayDatabases, railwayIacPath, railwayIacSource, serviceName, serviceNames, } from "./core/deploy.js";
+import { appPort, databaseVariables, databasesFor, deploymentStatus, exampleKeys, externalDatabaseUrls, finalStatuses, isLocalUrl, meetsMinimumCli, minimumRailwayCli, parseDeploymentId, parseEnvFile, parseRailwayDomain, parseVariables, planVariables, railwayCliVersion, railwayDatabases, railwayIacPath, railwayIacSource, railwayReferences, serviceName, serviceNames, } from "./core/deploy.js";
 import { readProject } from "./core/project.js";
 import { deployToFly } from "./deploy-fly.js";
 import { cliCommand } from "./modify.js";
@@ -19,6 +20,28 @@ import { pathExists } from "./utils/fs.js";
 import { run, spawnCommand } from "./utils/process.js";
 const railwayTermsUrl = "https://railway.com/legal/terms";
 const deployDocsUrl = "https://starter.clubedge.live/docs/starter/deploy";
+/**
+ * The production env file: --env-file, else the project's .env.production when there is one. Its
+ * values go on top of what the platform provides; its database URLs replace the platform's databases.
+ */
+async function readDeployEnv(args, project) {
+    const path = args.envFile ? resolve(process.cwd(), args.envFile) : join(project.root, ".env.production");
+    if (!(await pathExists(path))) {
+        if (args.envFile)
+            throw new UsageError(`The env file ${args.envFile} does not exist.`);
+        return {};
+    }
+    if (!args.envFile)
+        log.info("Using .env.production (pass --env-file for another file).");
+    const values = parseEnvFile(await readFile(path, "utf8"));
+    const local = databasesFor(project.modules)
+        .map((database) => databaseVariables[database])
+        .filter((key) => values[key] && isLocalUrl(values[key]));
+    if (local.length) {
+        log.warn(`${local.join(" and ")} in the env file point at this machine, which the deployed app can't reach: ignored, so deploy creates the platform's own.`);
+    }
+    return values;
+}
 const windows = process.platform === "win32";
 const binaryName = windows ? "railway.exe" : "railway";
 async function cliVersion(command, shell) {
@@ -111,12 +134,14 @@ async function railway(cli, args, options = {}) {
     });
 }
 const attempt = async (run) => run().catch(() => null);
-async function agree(args, service, databases) {
+async function agree(args, service, databases, external) {
+    const hosted = databases.map((db) => railwayDatabases[db]).join(" and ");
     note([
         "This deploys the project to Railway, in your Railway account:",
         "",
-        `• A project with ${databases.map((db) => railwayDatabases[db]).join(" and ")}, and a service "${service}" with a public *.up.railway.app domain.`,
-        "• The production variables Railway can provide; your provider keys come from --env-file.",
+        `• A project${hosted ? ` with ${hosted}` : ""}, and a service "${service}" with a public *.up.railway.app domain.`,
+        ...(external.length ? [`• ${external.join(" and ")} from the env file: those databases stay where they are, and Railway runs the app.`] : []),
+        "• The production variables Railway can provide; your provider keys come from the env file.",
         "• Railway builds the Dockerfile, runs the migrations before the release, and checks /api/health; the first build takes several minutes.",
         `• The service's settings go in ${railwayIacPath}, which replaces railway.json; the railway package is added to read it.`,
         "",
@@ -134,19 +159,21 @@ export async function deployProject(args) {
     const cli = await cliCommand(project);
     const platform = project.modules.deploy ?? "docker";
     if (platform === "fly")
-        return await deployToFly(args, project, cli);
+        return await deployToFly(args, project, cli, await readDeployEnv(args, project));
     if (platform !== "railway") {
         throw new UsageError(`deploy sets up Railway and Fly.io for now, and this project deploys with "${platform}". Switch with \`${cli} add deploy railway\` (or fly), or follow ${deployDocsUrl} for ${platform}.`);
     }
     const service = serviceName(project.identity.packageName);
-    const databases = databasesFor(project.modules);
     const keys = exampleKeys(await readFile(join(project.root, ".env.example"), "utf8").catch(() => ""));
-    const envFile = args.envFile ? parseEnvFile(await readFile(resolve(process.cwd(), args.envFile), "utf8")) : {};
+    const envFile = await readDeployEnv(args, project);
+    const external = Object.keys(externalDatabaseUrls(project.modules, envFile));
+    const databases = databasesFor(project.modules, external);
     const secret = () => randomBytes(32).toString("hex");
     if (args.dryRun) {
         const preview = planVariables({ modules: project.modules, keys, url: "https://<service>.up.railway.app", existing: {}, envFile, secret: () => "<generated>" });
         log.message([
-            `• Railway project "${service}" with ${databases.join(" and ")}, and the service "${service}"`,
+            `• Railway project "${service}"${databases.length ? ` with ${databases.map((db) => railwayDatabases[db]).join(" and ")}` : ""}, and the service "${service}"`,
+            ...(external.length ? [`• ${external.join(" and ")} from the env file, instead of Railway's databases`] : []),
             `• A *.up.railway.app domain for port ${appPort}`,
             `• ${railwayIacPath} (written if missing, with Railway's SDK added), applied with railway config apply`,
             `• Variables: ${Object.keys(preview.set).join(", ")}`,
@@ -156,7 +183,7 @@ export async function deployProject(args) {
         outro("Dry run: nothing was created. Run again without --dry-run to deploy.");
         return;
     }
-    if (!(await agree(args, service, databases))) {
+    if (!(await agree(args, service, databases, external))) {
         cancel("Nothing was deployed.");
         return;
     }
@@ -185,7 +212,19 @@ export async function deployProject(args) {
     catch {
         // Unknown status format: create what is missing, as for a new project.
     }
-    for (const database of databases) {
+    // A database URL the service already has without that database in the project points elsewhere
+    // (an earlier --env-file): keep it. A new service has nothing to list yet; an existing one must
+    // list its variables, or deploy could create Railway's database and switch the app over.
+    const variables = await attempt(() => railway(rw, ["variable", "list", "--service", service, "--json"]));
+    if (variables === null && existing.includes(service)) {
+        throw new Error(`Railway didn't list the variables of the service "${service}", so deploy changed nothing. Run deploy again; if it keeps failing, check \`railway variable list --service ${service}\`.`);
+    }
+    const current = parseVariables(variables ?? "");
+    const kept = databasesFor(project.modules, external)
+        .filter((database) => current[databaseVariables[database]] && !existing.includes(railwayDatabases[database]))
+        .map((database) => databaseVariables[database]);
+    const hosted = databasesFor(project.modules, [...external, ...kept]);
+    for (const database of hosted) {
         if (existing.includes(railwayDatabases[database]))
             continue;
         progress.message(`Adding ${railwayDatabases[database]}`);
@@ -203,8 +242,7 @@ export async function deployProject(args) {
         throw new Error("Railway created no *.up.railway.app domain. Create one in the service's settings, then run deploy again.");
     const url = `https://${domain}`;
     progress.message("Setting the production variables");
-    const current = parseVariables((await attempt(() => railway(rw, ["variable", "list", "--service", service, "--json"]))) ?? "");
-    const plan = planVariables({ modules: project.modules, keys, url, existing: current, envFile, secret });
+    const plan = planVariables({ modules: project.modules, keys, url, existing: current, envFile, secret, databases: railwayReferences(hosted) });
     for (const [key, value] of Object.entries(plan.set)) {
         if (current[key] === value)
             continue;
@@ -239,6 +277,12 @@ export async function deployProject(args) {
     progress.message(`Applying ${railwayIacPath}`);
     await railway(rw, ["config", "apply", "--yes"]);
     progress.stop(`Railway is ready: ${url}`);
+    const unused = databasesFor(project.modules)
+        .filter((database) => !hosted.includes(database) && existing.includes(railwayDatabases[database]))
+        .map((database) => railwayDatabases[database]);
+    if (unused.length) {
+        log.info(`The app no longer uses Railway's ${unused.join(" and ")}: its URL comes from elsewhere now. Delete it in the dashboard (railway open) if you don't need its data.`);
+    }
     if (changed.length) {
         log.info(`Commit ${changed.join(", ")}: Railway reads the service's settings from ${railwayIacPath} now. railway.json is no longer needed (Railway stops reading it on 2026-12-01).`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/create-clubedge-app",
-  "version": "0.25.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();