@clubedge/create-clubedge-app 0.26.0 → 0.28.0

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to `create-clubedge-app` are documented here.
 
+## 0.28.0
+
+- `pnpm clubedge deploy` deploys to Vercel (experimental) (#80), in projects created with `--deploy vercel`:
+  - It signs in with `vercel login` when you are signed out, then creates or reuses the project with `apps/web` as its Root Directory and writes `.vercelignore` so `.env` files stay on your machine.
+  - It sets the production variables from `.env.production` (or `--env-file`), the public URL, and a generated `BETTER_AUTH_SECRET`, then runs `vercel deploy --prod`. `DATABASE_URL` must point at your provider (Neon, Supabase, ...), since Vercel only runs the app.
+  - When Vercel names the app something other than `<project>.vercel.app`, it sets that URL and deploys again, since the build compiles it in.
+- The README opens with the banner the CLI prints (#79).
+- Still on Starter `v0.18.0`.
+
+## 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

@@ -1,5 +1,7 @@
 <div align="center">
 
+<img src="https://raw.githubusercontent.com/Clubedge/create-clubedge-app/main/.github/assets/cover.png" alt="Terminal running pnpm dlx @clubedge/create-clubedge-app my-app and printing the CLUBEDGE STARTER banner" width="100%">
+
 # create-clubedge-app
 
 **Create a production-ready Next.js or TanStack Start app with one command, and keep it up to date.**
@@ -127,7 +129,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 +148,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.
@@ -205,32 +207,36 @@ With [Railway's CLI](https://docs.railway.com/cli) (the installed `railway`, or
 
 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.
 
+### Deploy to Vercel (experimental)
+
+In a project with `--deploy vercel`, `pnpm clubedge deploy` uses [Vercel's CLI](https://vercel.com/docs/cli) (the installed `vercel`, else the latest through npx) and your Vercel login, running `vercel login` first when you are signed out. Vercel only runs the app, so the database and the other services come from the env file: `DATABASE_URL` (your provider's pooled URL, for example Neon's or Supabase's) is required. It creates or reuses a project named after the package, built from `apps/web` with the whole workspace uploaded, and writes a `.vercelignore` when the project has none, so `.env` files stay on your machine (commit it). It sets the production variables: the env file's values, the public URL, and a generated `BETTER_AUTH_SECRET` with Better Auth. `STORAGE_DIRECTORY` is left out, since Vercel keeps no disk. Then `vercel deploy --prod` builds the app, after `check:env` and the migrations. When Vercel names the app something other than `https://<project>.vercel.app`, `deploy` sets that URL and deploys again, since the build compiles it in. Running it again reuses the project. Vercel bills usage on your plan.
+
 ## Version relationship
 
 Each CLI release is tested against one specific Starter release:
 
 ```text
-create-clubedge-app v0.26.0
+create-clubedge-app v0.28.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.28.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 +291,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 +327,8 @@ 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`) |
+| 0.28.0 | v0.18.0 | `deploy` to Vercel (experimental) |
 | next | | Show the Starter's version of a conflicted file next to yours |
 
 ## Community

package/dist/cli/ui.js

@@ -124,10 +124,10 @@ ${selectionHelp(manifest)}
   --dry-run               Show what would be created or changed without writing anything
   --force                 add/remove: change a project with uncommitted changes or without Git
   --no-services           doctor: skip pnpm check:services
-  --no-open               try: do not open the preview in the browser
+  --no-open               try, deploy (Vercel): do not open the URL in the browser
   --claim                 try: open the page that claims the VM, to share the preview
   --status                try: the last VM's preview, time left, and claim link
-  --env-file <path>       deploy (Railway, Fly.io): production values, such as .env.production
+  --env-file <path>       deploy: production values (default: .env.production when there is one)
   -y, --yes               Accept defaults and never prompt (default directory: my-app)
   --no-install            Skip dependency installation
   --no-git                Skip Git repository initialization

package/dist/core/deploy.js

@@ -87,6 +87,9 @@ export function planVariables(input) {
     for (const [key, value] of Object.entries(envFile)) {
         if (value === "" || databaseKeys.includes(key))
             continue;
+        // A development env file's localhost URL would send emailed links to this machine.
+        if (appUrlKeys.includes(key) && isLocalUrl(value))
+            continue;
         set[key] = value;
     }
     Object.assign(set, external);
@@ -166,10 +169,10 @@ export function railwayCliVersion(output) {
     const match = /\b(\d+)\.(\d+)\.(\d+)\b/.exec(output);
     return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : null;
 }
-export function meetsMinimumCli(version) {
+export function meetsMinimumCli(version, minimum = minimumRailwayCli) {
     for (let i = 0; i < 3; i++) {
-        if (version[i] !== minimumRailwayCli[i])
-            return version[i] > minimumRailwayCli[i];
+        if (version[i] !== minimum[i])
+            return version[i] > minimum[i];
     }
     return true;
 }
@@ -246,3 +249,92 @@ export function flySecretsInput(values) {
         .map(([key, value]) => `${key}=${value}`)
         .join("\n");
 }
+// Vercel: the platform only runs the app. Databases, Redis, storage, and email come from the env file.
+/** vercel@50.5.1 added `vercel api`, which deploy uses to create the project and set its variables. */
+export const minimumVercelCli = [50, 5, 1];
+/** Where Vercel builds: the app's folder, with the whole workspace uploaded. */
+export const vercelRootDirectory = "apps/web";
+/** The variables that hold the public URL: readable on Vercel ("plain"), so a later deploy can compare them. */
+export const appUrlKeys = ["APP_URL", "NEXT_PUBLIC_APP_URL"];
+/** A project in `vercel api /v9/projects/:name` output, or null. */
+export function parseVercelProject(output) {
+    try {
+        const value = JSON.parse(output);
+        if (typeof value.id !== "string" || typeof value.name !== "string")
+            return null;
+        return { id: value.id, name: value.name, rootDirectory: typeof value.rootDirectory === "string" ? value.rootDirectory : null };
+    }
+    catch {
+        return null;
+    }
+}
+/** The project's production variables from `vercel api /v10/projects/:id/env`: plain values as they are, the rest as "(set)". */
+export function parseVercelEnv(output) {
+    const values = {};
+    try {
+        const { envs } = JSON.parse(output);
+        for (const env of envs ?? []) {
+            const targets = Array.isArray(env.target) ? env.target : [env.target];
+            if (typeof env.key !== "string" || !targets.includes("production"))
+                continue;
+            values[env.key] = env.type === "plain" && typeof env.value === "string" ? env.value : "(set)";
+        }
+    }
+    catch {
+        // Unknown output: every variable counts as unset, and the upsert sets them again.
+    }
+    return values;
+}
+/** The body of `POST /v10/projects/:id/env?upsert=true`: production variables, encrypted except the public URL. */
+export function vercelEnvBody(values) {
+    return Object.entries(values).map(([key, value]) => ({
+        key,
+        value,
+        type: appUrlKeys.includes(key) ? "plain" : "encrypted",
+        target: ["production"],
+    }));
+}
+/**
+ * The public URL Vercel gave a production deployment, from `vercel api /v13/deployments/:url`: the
+ * shortest *.vercel.app alias that isn't the deployment's own URL or a Git branch's.
+ */
+export function vercelProductionUrl(output, deploymentUrl) {
+    const own = deploymentUrl.replace(/^https?:\/\//, "").replace(/\/.*$/, "").toLowerCase();
+    try {
+        const { alias } = JSON.parse(output);
+        const names = (Array.isArray(alias) ? alias : [])
+            .filter((name) => typeof name === "string")
+            .map((name) => name.toLowerCase())
+            .filter((name) => name.endsWith(".vercel.app") && name !== own && !name.includes("-git-"))
+            .sort((a, b) => a.length - b.length);
+        return names[0] ? `https://${names[0]}` : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The deployment URL `vercel deploy` prints on stdout (its last https URL). */
+export function parseVercelDeploymentUrl(output) {
+    const urls = output.match(/https:\/\/[a-z0-9.-]+\.vercel\.app\b/gi);
+    return urls?.at(-1)?.toLowerCase() ?? null;
+}
+/**
+ * .vercelignore for a project without one: the CLI uploads everything but a short list, which
+ * keeps .env.local out but not .env or .env.production. Uploading what Git would commit keeps
+ * secrets and build output out, as `try` does.
+ */
+export function vercelIgnoreSource(gitignore) {
+    const lines = gitignore.split(/\r?\n/).map((line) => line.trimEnd());
+    const required = [".env*", "!.env.example"].filter((line) => !lines.includes(line));
+    return [
+        "# What `vercel deploy` leaves out: what Git ignores, so secrets in .env files and build output",
+        "# stay on this machine. Vercel reads its variables from the project's settings.",
+        ...lines.filter((line, index) => line || index < lines.length - 1),
+        ...required,
+        "",
+    ].join("\n");
+}
+/** Whether a .vercelignore keeps .env files out of the upload. */
+export function ignoresEnvFiles(vercelignore) {
+    return vercelignore.split(/\r?\n/).some((line) => /^\/?(\*\*\/)?\.env(\*|\.\*)?\/?$/.test(line.trim()));
+}

package/dist/deploy-vercel.js

@@ -0,0 +1,218 @@
+// `deploy` for Vercel: the platform only runs the app, so the database, Redis, storage, and email
+// come from the env file. With Vercel's CLI and your login, it creates or reuses the project (built
+// from apps/web, with the whole workspace uploaded), sets the production variables, runs
+// `vercel deploy --prod`, and prints the public URL. The build checks the variables (check:env)
+// and runs the migrations before it builds.
+import { cancel, confirm, isCancel, log, note, outro, spinner } from "@clack/prompts";
+import { randomBytes } from "node:crypto";
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import process from "node:process";
+import { UsageError } from "./cli/args.js";
+import { bold, dim } from "./cli/ui.js";
+import { appUrlKeys, exampleKeys, externalDatabaseUrls, ignoresEnvFiles, isLocalUrl, meetsMinimumCli, minimumVercelCli, parseVercelDeploymentUrl, parseVercelEnv, parseVercelProject, planVariables, railwayCliVersion, serviceName, vercelEnvBody, vercelIgnoreSource, vercelProductionUrl, vercelRootDirectory, } from "./core/deploy.js";
+import { pathExists } from "./utils/fs.js";
+import { openUrl } from "./utils/open.js";
+import { spawnCommand } from "./utils/process.js";
+const vercelCliUrl = "https://vercel.com/docs/cli";
+const vercelPricingUrl = "https://vercel.com/pricing";
+const windows = process.platform === "win32";
+/** Runs Vercel's CLI in the project's root; npm's .cmd shims need a shell on Windows. */
+async function vercel(cli, args, cwd, options = {}) {
+    const [command, ...prefix] = cli.command;
+    const mode = options.mode ?? "capture";
+    const stdio = mode === "interactive" ? "inherit" : mode === "stream" ? ["pipe", "pipe", "inherit"] : ["pipe", "pipe", "pipe"];
+    return await new Promise((resolvePromise, reject) => {
+        const child = spawnCommand(command, [...prefix, ...args], { cwd, stdio: stdio }, windows);
+        let stdout = "";
+        let stderr = "";
+        child.stdout?.on("data", (chunk) => (stdout += chunk.toString()));
+        child.stderr?.on("data", (chunk) => (stderr += chunk.toString()));
+        child.once("error", reject);
+        child.once("close", (code) => {
+            if (code === 0)
+                resolvePromise(stdout.trim());
+            else
+                reject(new Error(`vercel ${args[0]} failed${stderr.trim() ? `: ${stderr.trim().split("\n").slice(-3).join(" ")}` : "."}`));
+        });
+        if (child.stdin) {
+            child.stdin.on("error", () => { });
+            child.stdin.end(options.input ?? "");
+        }
+    });
+}
+const attempt = async (run) => run().catch(() => null);
+async function vercelCli(cwd) {
+    for (const command of [["vercel"], ["npx", "--yes", "vercel@latest"]]) {
+        const cli = { command };
+        const version = railwayCliVersion((await attempt(() => vercel(cli, ["--version"], cwd))) ?? "");
+        if (version && meetsMinimumCli(version, minimumVercelCli))
+            return cli;
+    }
+    throw new UsageError(`deploy to Vercel needs Vercel's CLI ${minimumVercelCli.join(".")} or newer. Install it with \`npm install -g vercel\` (${vercelCliUrl}), then run deploy again.`);
+}
+/** The project `vercel link` recorded in .vercel/project.json, if any. */
+async function linkedProject(root) {
+    try {
+        const linked = JSON.parse(await readFile(join(root, ".vercel", "project.json"), "utf8"));
+        return typeof linked.projectId === "string" ? linked.projectId : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Writes .vercelignore when the project has none, so .env files never reach Vercel. */
+async function ensureVercelIgnore(root) {
+    const path = join(root, ".vercelignore");
+    if (await pathExists(path)) {
+        if (!ignoresEnvFiles(await readFile(path, "utf8"))) {
+            log.warn("Your .vercelignore doesn't leave out .env files, so `vercel deploy` uploads them. Add `.env*` and `!.env.example` to it.");
+        }
+        return false;
+    }
+    const gitignore = await readFile(join(root, ".gitignore"), "utf8").catch(() => "");
+    await writeFile(path, vercelIgnoreSource(gitignore));
+    return true;
+}
+/** Variables a serverless host must not get: STORAGE_DIRECTORY stores files on a disk Vercel doesn't keep. */
+const serverlessExcluded = ["STORAGE_DIRECTORY"];
+export async function deployToVercel(args, project, cli, fileValues) {
+    const root = project.root;
+    const skipped = serverlessExcluded.filter((key) => fileValues[key]);
+    if (skipped.length)
+        log.warn(`${skipped.join(", ")} stores files on the server's disk, which Vercel doesn't keep: not set. Files go to the storage bucket.`);
+    const envFile = Object.fromEntries(Object.entries(fileValues).filter(([key]) => !serverlessExcluded.includes(key)));
+    const keys = exampleKeys(await readFile(join(root, ".env.example"), "utf8").catch(() => "")).filter((key) => !serverlessExcluded.includes(key));
+    if (!(await pathExists(join(root, vercelRootDirectory, "vercel.json")))) {
+        throw new UsageError(`This project has no ${vercelRootDirectory}/vercel.json. Switch with \`${cli} add deploy vercel\`.`);
+    }
+    const name = serviceName(project.identity.packageName);
+    const external = externalDatabaseUrls(project.modules, envFile);
+    // A public URL of your own (a custom domain) wins; otherwise the one Vercel assigns.
+    const ownUrl = appUrlKeys.map((key) => envFile[key]).find((value) => value && !isLocalUrl(value));
+    const secret = () => randomBytes(32).toString("hex");
+    if (!external.DATABASE_URL) {
+        throw new UsageError("Vercel only runs the app, so the database comes from your provider (Supabase, Neon, ...): put DATABASE_URL in .env.production (its pooled URL), or pass --env-file, then run deploy again.");
+    }
+    if (args.dryRun) {
+        const preview = planVariables({ modules: project.modules, keys, url: ownUrl ?? `https://${name}.vercel.app`, existing: {}, envFile, secret: () => "<generated>", databases: {} });
+        const { NODE_ENV: _node, PORT: _port, ...values } = preview.set;
+        log.message([
+            `• Vercel project "${name}", built from ${vercelRootDirectory} with the whole workspace uploaded`,
+            `• Production variables: ${Object.keys(values).join(", ")}`,
+            ...(preview.unset.length ? [`• Not set: ${preview.unset.join(", ")}`] : []),
+            "• .vercelignore (when missing): what Git ignores, so .env files stay on this machine",
+            "• vercel deploy --prod: check:env, the migrations, then the build",
+        ].join("\n"));
+        outro("Dry run: nothing was created. Run again without --dry-run to deploy.");
+        return;
+    }
+    note([
+        "This deploys the project to Vercel, in your Vercel account:",
+        "",
+        `• A project "${name}" that builds ${vercelRootDirectory}. Vercel only runs the app: the database${project.modules.cache === "redis" ? ", Redis," : ""} and the other services come from the env file.`,
+        "• The production variables from the env file, the public URL, and a generated BETTER_AUTH_SECRET when the project uses Better Auth.",
+        "• vercel deploy --prod: the build checks the variables (check:env), runs the migrations against DATABASE_URL, then builds.",
+        "",
+        `Vercel bills usage on your plan (${vercelPricingUrl}). Running deploy again reuses the project.`,
+    ].join("\n"), "Deploy to Vercel");
+    if (!args.yes) {
+        if (!process.stdin.isTTY)
+            throw new UsageError("deploy creates a project in your Vercel account. Run it in a terminal to confirm, or pass --yes.");
+        const answer = await confirm({ message: "Deploy?", initialValue: true });
+        if (isCancel(answer) || !answer) {
+            cancel("Nothing was deployed.");
+            return;
+        }
+    }
+    const progress = spinner();
+    progress.start("Preparing Vercel's CLI");
+    const vc = await vercelCli(root);
+    if (!(await attempt(() => vercel(vc, ["whoami"], root)))) {
+        progress.stop("Signing in to Vercel");
+        if (!process.stdin.isTTY)
+            throw new UsageError("Sign in to Vercel first with `vercel login`, or set VERCEL_TOKEN.");
+        await vercel(vc, ["login"], root, { mode: "interactive" });
+        progress.start("Signed in");
+    }
+    progress.message("Finding or creating the Vercel project");
+    const linked = await linkedProject(root);
+    let found = parseVercelProject((await attempt(() => vercel(vc, ["api", `/v9/projects/${linked ?? name}`], root))) ?? "");
+    if (!found) {
+        const created = await vercel(vc, ["api", "/v10/projects", "-X", "POST", "--input", "-"], root, {
+            input: JSON.stringify({ name, rootDirectory: vercelRootDirectory }),
+        });
+        found = parseVercelProject(created);
+        if (!found)
+            throw new Error(`Vercel created no project "${name}". Create it in the dashboard with the Root Directory ${vercelRootDirectory}, then run deploy again.`);
+    }
+    else if (found.rootDirectory !== vercelRootDirectory) {
+        progress.message(`Setting the project's Root Directory to ${vercelRootDirectory}`);
+        await vercel(vc, ["api", `/v9/projects/${found.id}`, "-X", "PATCH", "--input", "-"], root, {
+            input: JSON.stringify({ rootDirectory: vercelRootDirectory }),
+        });
+    }
+    if (!linked)
+        await vercel(vc, ["link", "--yes", "--project", found.name], root);
+    const wroteIgnore = await ensureVercelIgnore(root);
+    progress.message("Setting the production variables");
+    const existing = parseVercelEnv((await attempt(() => vercel(vc, ["api", `/v10/projects/${found.id}/env`], root))) ?? "");
+    const keptUrl = appUrlKeys.map((key) => existing[key]).find((value) => value && value !== "(set)" && !isLocalUrl(value));
+    let url = ownUrl ?? keptUrl ?? `https://${found.name}.vercel.app`;
+    const plan = planVariables({ modules: project.modules, keys, url, existing, envFile, secret, databases: {} });
+    // Vercel sets NODE_ENV and the port itself.
+    const { NODE_ENV: _node, PORT: _port, ...values } = plan.set;
+    await vercel(vc, ["api", `/v10/projects/${found.id}/env?upsert=true`, "-X", "POST", "--input", "-"], root, {
+        input: JSON.stringify(vercelEnvBody(values)),
+    });
+    progress.stop(`Vercel is ready: the project "${found.name}"`);
+    if (wroteIgnore)
+        log.info("Commit .vercelignore: it keeps .env files and build output out of `vercel deploy`.");
+    if (plan.unset.length) {
+        log.warn(`Not set: ${plan.unset.join(", ")}. The build stops at check:env when one of them is required; the others only turn features off.`);
+        if (process.stdin.isTTY && !args.yes) {
+            const proceed = await confirm({ message: "Deploy anyway?", initialValue: true });
+            if (isCancel(proceed) || !proceed) {
+                cancel("Nothing was deployed. Add them to .env.production, then run deploy again: it reuses the project.");
+                return;
+            }
+        }
+    }
+    const deploy = async () => {
+        log.step("Deploying with vercel deploy --prod (build logs follow)");
+        try {
+            const output = await vercel(vc, ["deploy", "--prod", "--yes", "--logs"], root, { mode: "stream" });
+            const deployment = parseVercelDeploymentUrl(output);
+            if (!deployment)
+                throw new Error("no URL");
+            return deployment;
+        }
+        catch {
+            throw new Error("The deploy did not finish. The build log above says why (check:env names missing variables); `vercel inspect --logs <url>` shows it again. Fix the cause and run deploy again: it reuses the project.");
+        }
+    };
+    const deployment = await deploy();
+    const details = await attempt(() => vercel(vc, ["api", `/v13/deployments/${deployment.replace(/^https:\/\//, "")}`], root));
+    const assigned = vercelProductionUrl(details ?? "", deployment);
+    // Next.js compiles the public URL into the build: when Vercel picked another name, set it and build again.
+    if (!ownUrl && assigned && assigned !== url) {
+        log.info(`Vercel named the app ${assigned}. Setting it as the public URL and deploying again, since the build compiles it in.`);
+        url = assigned;
+        await vercel(vc, ["api", `/v10/projects/${found.id}/env?upsert=true`, "-X", "POST", "--input", "-"], root, {
+            input: JSON.stringify(vercelEnvBody(Object.fromEntries(appUrlKeys.map((key) => [key, url])))),
+        });
+        await deploy();
+    }
+    note([
+        `${bold("URL")}      ${url}`,
+        `${bold("Project")}  ${found.name}`,
+        ...(plan.unset.length ? ["", `${bold("Not set")}  ${plan.unset.join(", ")}`] : []),
+    ].join("\n"), "Deployed to Vercel");
+    if (args.open && process.stdin.isTTY && !args.yes && (await openUrl(url)))
+        log.info("Opened the app in your browser.");
+    outro([
+        `${dim("Logs")}      vercel logs ${url}`,
+        `${dim("Dashboard")} vercel open`,
+        `${dim("Again")}     ${cli} deploy   ${dim("(reuses the project; .env.production adds variables)")}`,
+    ].join("\n"));
+}

package/dist/deploy.js

@@ -14,6 +14,7 @@ import { bold, dim } from "./cli/ui.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 { deployToVercel } from "./deploy-vercel.js";
 import { cliCommand } from "./modify.js";
 import { resolvePnpm } from "./steps/install.js";
 import { pathExists } from "./utils/fs.js";
@@ -160,8 +161,10 @@ export async function deployProject(args) {
     const platform = project.modules.deploy ?? "docker";
     if (platform === "fly")
         return await deployToFly(args, project, cli, await readDeployEnv(args, project));
+    if (platform === "vercel")
+        return await deployToVercel(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}.`);
+        throw new UsageError(`deploy sets up Railway, Fly.io, and Vercel for now, and this project deploys with "${platform}". Switch with \`${cli} add deploy railway\` (or fly, or vercel), or follow ${deployDocsUrl} for ${platform}.`);
     }
     const service = serviceName(project.identity.packageName);
     const keys = exampleKeys(await readFile(join(project.root, ".env.example"), "utf8").catch(() => ""));

package/dist/index.js

@@ -237,7 +237,7 @@ export async function main(argv = process.argv.slice(2)) {
             await runDoctor(args);
         }
         else if (args.command.name === "deploy") {
-            intro("Deploy this project to Railway");
+            intro("Deploy this project");
             await deployProject(args);
         }
         else if (args.command.name === "try") {

package/package.json

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