@clubedge/create-clubedge-app 0.21.0 → 0.23.0

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 All notable changes to `create-clubedge-app` are documented here.
 
+## 0.23.0
+
+- `deploy` moves Railway projects to `.railway/railway.ts`, Railway's configuration as code, which replaces `railway.json`: Railway stops reading `railway.json` on 2026-12-01 (#59).
+  - When the project has no Railway configuration file, it writes one with the project's own names: the migrations before each release and the `/api/health` check, as in `railway.json`. Variables stay as `deploy` set them.
+  - It adds Railway's TypeScript SDK (`railway`) as a dev dependency, and applies the file with `railway config apply` before each release. Commit `.railway/railway.ts`, `package.json`, and `pnpm-lock.yaml`.
+  - It needs Railway CLI 5.42.1 or newer: an installed `railway`, else one npx already downloaded, and only then a download.
+- Still on Starter `v0.16.1`.
+
+## 0.22.0
+
+- Add `deploy`: `pnpm clubedge deploy` does the first deploy of a project that uses `deploy railway`, with Railway's CLI and your Railway login (#55).
+  - It asks first, then creates or reuses the Railway project, Postgres (and Redis with `cache redis`), the app's service, and a `*.up.railway.app` domain.
+  - It sets the variables it can: the database references, `APP_URL` and `NEXT_PUBLIC_APP_URL`, `PORT`, and a generated `BETTER_AUTH_SECRET` that later runs keep. `--env-file .env.production` adds your provider keys; the ones still unset are listed.
+  - It follows the deployment until Railway's final status: the migrations run before the release and `/api/health` is checked. On a failure it names the logs commands. Running it again reuses everything.
+  - Railway only for now; `--dry-run` shows the plan.
+- Default to Starter `v0.16.1` (#57): both Dockerfiles install dependencies in the build stage, so `node_modules` is no longer copied between stages, which made builds slow and timed out a first build on Railway.
+- Release drafts list a Starter pin pull request once (#54).
+
 ## 0.21.0
 
 - Default to Starter `v0.16.0` (#52), which adds:

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.16.0
+pnpm dlx @clubedge/create-clubedge-app my-app --ref v0.16.1
 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.16.0 # or a specific tag, branch, or commit
+pnpm dlx @clubedge/create-clubedge-app upgrade --ref v0.16.1 # 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.
@@ -189,32 +189,44 @@ Inside a project, `pnpm clubedge try` uploads that project instead, to share wor
 
 When the app is ready, the CLI opens the preview in your browser (`--no-open` turns that off) and asks whether to share it: claiming the VM, a free Railway sign-up, is what makes the URL work for anyone. `--claim` opens the claim page without asking. `try --status` shows the last VM's preview, time left, and claim link; it connects only while the VM is running, so it never creates a new one. To open the app from another network yourself, forward it: `ssh -i <key> -N -L 3000:127.0.0.1:3000 railway.new`, then http://localhost:3000 (the CLI prints the exact command). The CLI asks before creating anything (`--yes` agrees), keeps its own SSH key in your config directory (`~/.config/clubedge`, or `%APPDATA%\clubedge` on Windows) apart from `~/.ssh`, and connects only to Railway's known host key. Railway's [terms](https://railway.com/legal/terms) apply, and Railway can change or pause its free VM.
 
+## Deploy to Railway
+
+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 --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.
+
 ## Version relationship
 
 Each CLI release is tested against one specific Starter release:
 
 ```text
-create-clubedge-app v0.21.0
+create-clubedge-app v0.23.0
         |
         v
-Clubedge Starter v0.16.0
-commit e233aa68ddc8c21df6cf2b01b9e26876d2e4aeca
+Clubedge Starter v0.16.1
+commit 72ff89e53a55a4e4a6262b364ce73be3b1c7a6b9
 ```
 
 The current relationship is:
 
 | CLI release | Default Starter release | Meaning |
 | --- | --- | --- |
-| `create-clubedge-app@0.21.0` | `clubedge-starter@v0.16.0` | The CLI's required, tested default |
+| `create-clubedge-app@0.23.0` | `clubedge-starter@v0.16.1` | 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.16.0` tag is expected to resolve to commit
-`e233aa68ddc8c21df6cf2b01b9e26876d2e4aeca`. The CLI verifies this before
+The `v0.16.1` tag is expected to resolve to commit
+`72ff89e53a55a4e4a6262b364ce73be3b1c7a6b9`. 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.16.0`. The CLI is then updated to use that release, all generated-project checks must pass, and a new CLI version is published. This keeps Starter and CLI releases independently versioned while preserving a tested compatibility relationship.
+When the Starter changes, its maintainers first publish a new versioned release, such as `v0.16.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.
 
 Every generated project records its CLI version, Starter repository, Starter ref, Starter commit, framework, and modules in `package.json` and `README.md`.
 
@@ -269,7 +281,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.16.0`, and publish the Starter release.
+4. Commit `main`, create a release tag such as `v0.16.1`, and publish the Starter release.
 
 ### CLI maintainers
 
@@ -300,6 +312,8 @@ Each phase ends with a Starter release and a CLI release pinned to it. The full
 | 0.19.0 | v0.15.0 | `pnpm clubedge try` uploads an existing project to the VM; the preview opens in the browser |
 | 0.20.0 | v0.15.0 | The Starter's version of each conflicted file in `.clubedge/incoming/`, several modules at once, sharing a `try` preview by claiming the VM, `try --status` |
 | 0.21.0 | v0.16.0 | Starter v0.16.0: upgrades delivered as pull requests, Node 24 actions; release tooling for maintainers |
+| 0.22.0 | v0.16.1 | `pnpm clubedge deploy`: a guided first deploy to Railway; faster Docker builds |
+| 0.23.0 | v0.16.1 | `deploy` moves Railway projects to `.railway/railway.ts` before Railway stops reading `railway.json` |
 | next | | Show the Starter's version of a conflicted file next to yours |
 
 ## Community

package/dist/cli/args.js

@@ -16,6 +16,7 @@ const OPTIONS = {
     open: { type: "boolean", default: true },
     claim: { type: "boolean", default: false },
     status: { type: "boolean", default: false },
+    "env-file": { type: "string" },
     help: { type: "boolean", short: "h", default: false },
     version: { type: "boolean", short: "v", default: false },
 };
@@ -89,6 +90,9 @@ export function parseCliArgs(argv) {
     if (!creates && command.name !== "upgrade" && values.ref !== undefined) {
         throw new UsageError("--ref only applies when creating or upgrading a project.");
     }
+    if (command.name !== "deploy" && values["env-file"] !== undefined) {
+        throw new UsageError("--env-file only applies to deploy.");
+    }
     if (command.name !== "try" && (values.claim || values.status)) {
         throw new UsageError("--claim and --status only apply to try.");
     }
@@ -120,6 +124,7 @@ export function parseCliArgs(argv) {
         open: values.open,
         claim: values.claim,
         status: values.status,
+        envFile: values["env-file"],
         help: values.help,
         version: values.version,
     };
@@ -156,6 +161,11 @@ function parseCommand(positionals) {
             throw new UsageError(`Usage: ${name}, run inside a project.`);
         return { name };
     }
+    if (name === "deploy") {
+        if (module !== undefined)
+            throw new UsageError("Usage: deploy [--env-file <path>], run inside a project.");
+        return { name };
+    }
     if (name === "try") {
         if (module !== undefined) {
             throw new UsageError("Usage: try [--framework <id>] [module flags] (a new project), or try inside a project to upload it.");

package/dist/cli/ui.js

@@ -92,9 +92,10 @@ Usage:
   pnpm dlx @clubedge/create-clubedge-app status                  (inside a project)
   pnpm dlx @clubedge/create-clubedge-app doctor                  (inside a project)
   pnpm dlx @clubedge/create-clubedge-app try [options]           (experimental)
+  pnpm dlx @clubedge/create-clubedge-app deploy [options]        (inside a project)
 
   Inside a project with the clubedge script, use pnpm clubedge add, remove,
-  upgrade, status, doctor, or try. Without a module or option, add and remove ask
+  upgrade, status, doctor, try, or deploy. Without a module or option, add and remove ask
   for them.
 
   add and remove change modules of an existing project, several at once as one
@@ -126,6 +127,7 @@ ${selectionHelp(manifest)}
   --no-open               try: do not open the preview 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: production values for the service, such as .env.production
   -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

@@ -0,0 +1,176 @@
+// What `deploy` sets up on Railway for a project, as pure functions: the service name, the
+// production variables, and reading the Railway CLI's output. src/deploy.ts runs the CLI.
+/** The port the production image listens on (the Starter's Dockerfile sets PORT=3000). */
+export const appPort = 3000;
+/** Railway's names for the databases `railway add --database` creates, used in references. */
+export const railwayDatabases = { postgres: "Postgres", redis: "Redis" };
+/** A Railway service name from the package name: lowercase letters, digits, and dashes. */
+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 names a project's .env.example lists, in order. */
+export function exampleKeys(example) {
+    const keys = example
+        .split(/\r?\n/)
+        .map((line) => /^([A-Z][A-Z0-9_]*)=/.exec(line.trim())?.[1])
+        .filter((key) => Boolean(key));
+    return [...new Set(keys)];
+}
+/** KEY=value lines of an env file; quotes around a value are removed, comments skipped. */
+export function parseEnvFile(text) {
+    const values = {};
+    for (const line of text.split(/\r?\n/)) {
+        const match = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(line);
+        if (!match)
+            continue;
+        const raw = match[2].trim();
+        // A quoted value keeps everything inside the quotes, and may still have a comment after them.
+        const quoted = /^(["'])(.*?)\1\s*(?:#.*)?$/.exec(raw);
+        values[match[1]] = quoted ? quoted[2] : raw.replace(/\s+#.*$/, "");
+    }
+    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.
+ */
+export function planVariables(input) {
+    const { modules, keys, url, existing, envFile, secret } = input;
+    const reference = (database, variable) => `\${{${database}.${variable}}}`;
+    const provided = {
+        NODE_ENV: "production",
+        PORT: String(appPort),
+        DATABASE_URL: reference(railwayDatabases.postgres, "DATABASE_URL"),
+        ...(modules.cache === "redis" ? { REDIS_URL: reference(railwayDatabases.redis, "REDIS_URL") } : {}),
+    };
+    // 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();
+    for (const [key, value] of Object.entries(envFile)) {
+        if (key === "DATABASE_URL" || key === "REDIS_URL" || value === "")
+            continue;
+        set[key] = value;
+    }
+    const unset = keys.filter((key) => set[key] === undefined && !existing[key]);
+    return { set, unset };
+}
+/** The public domain in `railway domain` output (JSON or text). */
+export function parseRailwayDomain(output) {
+    const domain = /([a-z0-9-]+(?:\.[a-z0-9-]+)*\.up\.railway\.app)/i.exec(output)?.[1];
+    return domain ? domain.toLowerCase() : null;
+}
+/** The service names in `railway status --json`, wherever the CLI puts them. */
+export function serviceNames(status) {
+    const names = new Set();
+    const visit = (value, inServices) => {
+        if (Array.isArray(value))
+            return value.forEach((item) => visit(item, inServices));
+        if (!value || typeof value !== "object")
+            return;
+        for (const [key, child] of Object.entries(value)) {
+            if (inServices && key === "name" && typeof child === "string")
+                names.add(child);
+            visit(child, inServices || key === "services");
+        }
+    };
+    visit(status, false);
+    return [...names];
+}
+/** `railway variable list --json`: a KEY -> value object, or an array of { name, value }. */
+export function parseVariables(output) {
+    try {
+        const value = JSON.parse(output);
+        if (Array.isArray(value)) {
+            return Object.fromEntries(value
+                .filter((item) => typeof item?.name === "string")
+                .map((item) => [item.name, String(item.value ?? "")]));
+        }
+        if (value && typeof value === "object") {
+            return Object.fromEntries(Object.entries(value).map(([key, child]) => [key, String(child ?? "")]));
+        }
+    }
+    catch {
+        // Not JSON: no variables known.
+    }
+    return {};
+}
+/** Deployment statuses Railway does not move on from. */
+export const finalStatuses = ["SUCCESS", "FAILED", "CRASHED", "REMOVED", "SKIPPED"];
+/** The deployment `railway up` started, from the dashboard link it prints (`...?id=<uuid>`). */
+export function parseDeploymentId(output) {
+    return /[?&]id=([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})/i.exec(output)?.[1] ?? null;
+}
+/**
+ * A deployment's status from `railway deployment list --json` (newest first): the one with `id`,
+ * or else the newest created at or after `since`. Null while Railway does not list it yet.
+ */
+export function deploymentStatus(output, id, since) {
+    let list;
+    try {
+        list = JSON.parse(output);
+    }
+    catch {
+        return null;
+    }
+    if (!Array.isArray(list))
+        return null;
+    const deployments = list.filter((item) => typeof item?.id === "string" && typeof item?.status === "string");
+    const found = id
+        ? deployments.find((deployment) => deployment.id === id)
+        : deployments.find((deployment) => deployment.createdAt && new Date(deployment.createdAt).getTime() >= since.getTime() - 5_000);
+    return found ? { id: found.id, status: found.status } : null;
+}
+/** The oldest Railway CLI that applies `.railway/railway.ts`: its IaC engine ships in the CLI. */
+export const minimumRailwayCli = [5, 42, 1];
+/** The version in `railway --version` output, such as "railway 5.67.1". */
+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) {
+    for (let i = 0; i < 3; i++) {
+        if (version[i] !== minimumRailwayCli[i])
+            return version[i] > minimumRailwayCli[i];
+    }
+    return true;
+}
+export const railwayIacPath = ".railway/railway.ts";
+/**
+ * The project's Railway configuration as code (`.railway/railway.ts`), which replaces railway.json:
+ * Railway stops reading railway.json on 2026-12-01. Railway builds the root Dockerfile by itself,
+ * the variables stay managed by `deploy` and the dashboard, and the region is Railway's default.
+ */
+export function railwayIacSource(service) {
+    const name = JSON.stringify(service);
+    return `// Railway's configuration for this project, applied with \`railway config apply\` (pnpm clubedge
+// deploy does it before each release). It replaces railway.json, which Railway stops reading on
+// 2026-12-01. Railway builds the root Dockerfile; variables are set with \`railway variable set\`.
+import { defineRailway, project, service } from "railway/iac";
+
+// This repository manages only its own resources in the Railway project.
+export const partial = ${name};
+
+export default defineRailway(() => {
+  const app = service(${name}, {
+    // Migrations run before each release; a failed migration stops it.
+    preDeploy: "node /app/migrate.mjs",
+    healthcheck: "/api/health",
+    healthcheckTimeout: 60,
+  });
+
+  return project(${name}, {
+    variables: { managed: false },
+    resources: [app],
+  });
+});
+`;
+}

package/dist/deploy.js

@@ -0,0 +1,282 @@
+// `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.
+import { cancel, confirm, isCancel, log, note, outro, spinner } from "@clack/prompts";
+import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+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 { readProject } from "./core/project.js";
+import { cliCommand } from "./modify.js";
+import { resolvePnpm } from "./steps/install.js";
+import { pathExists } from "./utils/fs.js";
+import { run } from "./utils/process.js";
+const railwayTermsUrl = "https://railway.com/legal/terms";
+const deployDocsUrl = "https://starter.clubedge.live/docs/starter/deploy";
+const windows = process.platform === "win32";
+const binaryName = windows ? "railway.exe" : "railway";
+async function cliVersion(command, shell) {
+    return await new Promise((resolveVersion) => {
+        const [file, ...args] = command;
+        const child = spawn(file, [...args, "--version"], { shell, stdio: ["ignore", "pipe", "ignore"] });
+        let out = "";
+        child.stdout?.on("data", (chunk) => (out += chunk.toString()));
+        child.once("error", () => resolveVersion(null));
+        child.once("close", (code) => resolveVersion(code === 0 ? railwayCliVersion(out) : null));
+    });
+}
+/** The railway.exe behind `railway` on PATH (npm installs a railway.cmd shim next to its package). */
+async function installedBinary() {
+    if (!windows)
+        return (await cliVersion(["railway"], false)) ? "railway" : null;
+    const found = await new Promise((resolveWhere) => {
+        const child = spawn("where", ["railway"], { stdio: ["ignore", "pipe", "ignore"] });
+        let out = "";
+        child.stdout?.on("data", (chunk) => (out += chunk.toString()));
+        child.once("error", () => resolveWhere(""));
+        child.once("close", () => resolveWhere(out));
+    });
+    for (const line of found.split(/\r?\n/).map((entry) => entry.trim()).filter(Boolean)) {
+        if (line.toLowerCase().endsWith(".exe"))
+            return line;
+        const shimmed = join(dirname(line), "node_modules", "@railway", "cli", "bin", binaryName);
+        if (await pathExists(shimmed))
+            return shimmed;
+    }
+    return null;
+}
+/** Railway CLI binaries npx already downloaded, newest first: no download on a slow connection. */
+async function cachedBinaries() {
+    const cache = process.env.npm_config_cache ||
+        (windows && process.env.LOCALAPPDATA ? join(process.env.LOCALAPPDATA, "npm-cache") : join(homedir(), ".npm"));
+    const found = [];
+    for (const entry of await readdir(join(cache, "_npx")).catch(() => [])) {
+        const path = join(cache, "_npx", entry, "node_modules", "@railway", "cli", "bin", binaryName);
+        const stats = await stat(path).catch(() => null);
+        if (stats?.isFile())
+            found.push({ path, time: stats.mtimeMs });
+    }
+    return found.sort((a, b) => b.time - a.time).map((entry) => entry.path);
+}
+/**
+ * A Railway CLI new enough for `.railway/railway.ts`: the installed one, then one npx already
+ * downloaded, and only then a download through npx.
+ */
+async function railwayCli() {
+    const usable = async (binary) => {
+        const version = await cliVersion([binary], false);
+        return version !== null && meetsMinimumCli(version);
+    };
+    const installed = await installedBinary();
+    if (installed && (await usable(installed)))
+        return { command: [installed], executable: installed, shell: false };
+    for (const binary of await cachedBinaries()) {
+        if (await usable(binary))
+            return { command: [binary], executable: binary, shell: false };
+    }
+    await cliVersion(["npx", "--yes", "@railway/cli@latest"], windows);
+    for (const binary of await cachedBinaries()) {
+        if (await usable(binary))
+            return { command: [binary], executable: binary, shell: false };
+    }
+    throw new UsageError(`deploy needs Railway CLI ${minimumRailwayCli.join(".")} or newer. Install it with \`npm install -g @railway/cli\`, then run deploy again.`);
+}
+async function railway(cli, args, options = {}) {
+    const [command, ...prefix] = cli.command;
+    return await new Promise((resolvePromise, reject) => {
+        const child = spawn(command, [...prefix, ...args], {
+            shell: cli.shell,
+            env: { ...process.env, _: cli.executable },
+            stdio: options.inherit ? "inherit" : ["pipe", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout?.on("data", (chunk) => (stdout += chunk.toString()));
+        child.stderr?.on("data", (chunk) => (stderr += chunk.toString()));
+        child.once("error", reject);
+        // close, not exit: it fires once stdout and stderr are fully read, so JSON output is never cut off.
+        child.once("close", (code) => {
+            if (code === 0)
+                resolvePromise(stdout.trim());
+            else
+                reject(new Error(`railway ${args[0]} failed${stderr.trim() ? `: ${stderr.trim().split("\n").slice(-3).join(" ")}` : "."}`));
+        });
+        if (child.stdin) {
+            // A command that exits before reading its input must not crash the CLI with EPIPE.
+            child.stdin.on("error", () => { });
+            child.stdin.end(options.input ?? "");
+        }
+    });
+}
+const attempt = async (run) => run().catch(() => null);
+async function agree(args, service, databases) {
+    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.",
+        "• 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.`,
+        "",
+        `Railway bills usage on your plan. Running deploy again reuses all of it. Railway's terms: ${railwayTermsUrl}`,
+    ].join("\n"), "Deploy to Railway");
+    if (args.yes)
+        return true;
+    if (!process.stdin.isTTY)
+        throw new UsageError("deploy creates resources in your Railway account. Run it in a terminal to confirm, or pass --yes.");
+    const answer = await confirm({ message: "Deploy?", initialValue: true });
+    return !isCancel(answer) && answer;
+}
+export async function deployProject(args) {
+    const project = await readProject(process.cwd());
+    const cli = await cliCommand(project);
+    const platform = project.modules.deploy ?? "docker";
+    if (platform !== "railway") {
+        throw new UsageError(`deploy sets up Railway for now, and this project deploys with "${platform}". Switch with \`${cli} add deploy railway\`, 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 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}"`,
+            `• 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(", ")}`,
+            ...(preview.unset.length ? [`• Not set: ${preview.unset.join(", ")}`] : []),
+            `• railway up: build, migrations, health check`,
+        ].join("\n"));
+        outro("Dry run: nothing was created. Run again without --dry-run to deploy.");
+        return;
+    }
+    if (!(await agree(args, service, databases))) {
+        cancel("Nothing was deployed.");
+        return;
+    }
+    const progress = spinner();
+    progress.start("Preparing the Railway CLI");
+    const rw = await railwayCli();
+    // The project's directory, so Railway links it there.
+    process.chdir(project.root);
+    if (!(await attempt(() => railway(rw, ["whoami"])))) {
+        progress.stop("Signing in to Railway");
+        if (!process.stdin.isTTY)
+            throw new UsageError("Sign in to Railway first with `railway login`, or set RAILWAY_API_TOKEN.");
+        await railway(rw, ["login"], { inherit: true });
+        progress.start("Signed in");
+    }
+    progress.message("Finding or creating the Railway project");
+    let status = await attempt(() => railway(rw, ["status", "--json"]));
+    if (!status) {
+        await railway(rw, ["init", "--name", service, "--json"]);
+        status = await attempt(() => railway(rw, ["status", "--json"]));
+    }
+    let existing = [];
+    try {
+        existing = serviceNames(JSON.parse(status ?? "{}"));
+    }
+    catch {
+        // Unknown status format: create what is missing, as for a new project.
+    }
+    for (const database of databases) {
+        if (existing.includes(railwayDatabases[database]))
+            continue;
+        progress.message(`Adding ${railwayDatabases[database]}`);
+        await railway(rw, ["add", "--database", database]);
+    }
+    if (!existing.includes(service)) {
+        progress.message(`Adding the service "${service}"`);
+        await railway(rw, ["add", "--service", service]);
+    }
+    progress.message("Creating the public domain");
+    const listed = await attempt(() => railway(rw, ["domain", "list", "--service", service]));
+    const domain = parseRailwayDomain(listed ?? "") ??
+        parseRailwayDomain(await railway(rw, ["domain", "--service", service, "--port", String(appPort), "--json"]));
+    if (!domain)
+        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 });
+    for (const [key, value] of Object.entries(plan.set)) {
+        if (current[key] === value)
+            continue;
+        await railway(rw, ["variable", "set", key, "--stdin", "--service", service, "--skip-deploys"], { input: value });
+    }
+    // The service's settings as code: .railway/railway.ts replaces railway.json, which Railway stops
+    // reading on 2026-12-01. It needs Railway's TypeScript SDK, and applies before each release.
+    const iacFiles = [railwayIacPath, ".railway/railway.py", ".railway/railway.go"];
+    const changed = [];
+    let hasIac = false;
+    for (const file of iacFiles)
+        if (await pathExists(join(project.root, file)))
+            hasIac = true;
+    if (!hasIac) {
+        await mkdir(join(project.root, ".railway"), { recursive: true });
+        await writeFile(join(project.root, railwayIacPath), railwayIacSource(service));
+        changed.push(railwayIacPath);
+    }
+    if (await pathExists(join(project.root, railwayIacPath))) {
+        const manifest = JSON.parse(await readFile(join(project.root, "package.json"), "utf8"));
+        if (!manifest.devDependencies?.railway && !manifest.dependencies?.railway) {
+            const pnpm = await resolvePnpm();
+            if (!pnpm)
+                throw new UsageError("pnpm was not found. Enable it with `corepack enable`, then run deploy again.");
+            progress.stop("Adding Railway's TypeScript SDK (railway), which .railway/railway.ts imports");
+            const [command, ...prefix] = pnpm;
+            await run(command, [...prefix, "add", "--save-dev", "--workspace-root", "railway"], project.root);
+            changed.push("package.json", "pnpm-lock.yaml");
+            progress.start("Applying .railway/railway.ts");
+        }
+    }
+    progress.message(`Applying ${railwayIacPath}`);
+    await railway(rw, ["config", "apply", "--yes"]);
+    progress.stop(`Railway is ready: ${url}`);
+    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).`);
+    }
+    // Start the deploy detached, then follow its status: `railway up` can return before the build
+    // ends, and only Railway's final status says whether the release went live.
+    const deploying = spinner();
+    deploying.start("Uploading the project");
+    const started = new Date();
+    const upload = await railway(rw, ["up", "--service", service, "--detach"]);
+    const id = parseDeploymentId(upload);
+    let deployment = "QUEUED";
+    const deadline = Date.now() + 45 * 60_000;
+    while (!finalStatuses.includes(deployment)) {
+        if (Date.now() > deadline)
+            break;
+        const elapsed = Math.round((Date.now() - started.getTime()) / 1000);
+        deploying.message(`Railway: ${deployment.toLowerCase()} (${Math.floor(elapsed / 60)}m ${elapsed % 60}s; the first build takes several minutes)`);
+        await new Promise((wait) => setTimeout(wait, 10_000));
+        const list = await attempt(() => railway(rw, ["deployment", "list", "--service", service, "--json"]));
+        deployment = deploymentStatus(list ?? "", id, started)?.status ?? deployment;
+    }
+    if (deployment !== "SUCCESS") {
+        deploying.stop(`The deploy ended as ${deployment}`);
+        throw new Error([
+            `Railway's deploy ended as ${deployment}. Read why with \`railway logs --build --service ${service}\` (the build) or \`railway logs --service ${service}\` (the app and its health check).`,
+            "A build that ran out of time (DeadlineExceeded) usually passes on a second try. Otherwise fix the cause and run deploy again: it reuses what exists.",
+        ].join("\n"));
+    }
+    deploying.stop("Deployed: the migrations ran and /api/health answered");
+    note([
+        `${bold("URL")}      ${url}`,
+        `${bold("Service")}  ${service}`,
+        ...(plan.unset.length ? ["", `${bold("Not set")}  ${plan.unset.join(", ")}`, dim("Set the ones your modules use: railway variable set KEY --stdin, or the dashboard.")] : []),
+    ].join("\n"), "Deployed to Railway");
+    outro([
+        `${dim("Logs")}      railway logs --service ${service}`,
+        `${dim("Dashboard")} railway open`,
+        `${dim("Again")}     ${cli} deploy   ${dim("(reuses the project; --env-file to add variables)")}`,
+    ].join("\n"));
+}

package/dist/index.js

@@ -11,6 +11,7 @@ import { readBundledTemplate, resolveTemplateSource } from "./core/source.js";
 import { cliUrl, cliVersion, siteUrl, starterPin } from "./package-info.js";
 import { runDoctor, showStatus } from "./inspect.js";
 import { changeProject } from "./modify.js";
+import { deployProject } from "./deploy.js";
 import { tryOnRailway } from "./try.js";
 import { initializeGit } from "./steps/git.js";
 import { detectLauncher, installDependencies, resolvePnpm } from "./steps/install.js";
@@ -235,6 +236,10 @@ export async function main(argv = process.argv.slice(2)) {
             intro("Check this project's setup");
             await runDoctor(args);
         }
+        else if (args.command.name === "deploy") {
+            intro("Deploy this project to Railway");
+            await deployProject(args);
+        }
         else if (args.command.name === "try") {
             intro("Try a project on a free Railway VM");
             await tryOnRailway(args);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/create-clubedge-app",
-  "version": "0.21.0",
+  "version": "0.23.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.16.0",
-    "starterCommit": "e233aa68ddc8c21df6cf2b01b9e26876d2e4aeca"
+    "starterRef": "v0.16.1",
+    "starterCommit": "72ff89e53a55a4e4a6262b364ce73be3b1c7a6b9"
   },
   "license": "Apache-2.0",
   "repository": {

package/template/Dockerfile

@@ -8,13 +8,13 @@ FROM base AS pruner
 COPY . .
 RUN pnpm dlx turbo@^2.5.0 prune @clubedge/web --docker
 
-FROM base AS deps
-COPY --from=pruner /app/out/json/ .
-RUN pnpm install --frozen-lockfile
-
+# Install in the stage that builds: copying node_modules from a separate install stage (many
+# small files) took minutes on some builders, and timed out a Railway build. The manifests come
+# first, so the install layer is still cached until a dependency changes.
 FROM base AS builder
 ENV NEXT_TELEMETRY_DISABLED=1
-COPY --from=deps /app/ .
+COPY --from=pruner /app/out/json/ .
+RUN pnpm install --frozen-lockfile
 COPY --from=pruner /app/out/full/ .
 COPY tsconfig.base.json ./
 RUN pnpm build

package/template/apps/start/Dockerfile

@@ -16,12 +16,12 @@ ARG APP_PACKAGE
 COPY . .
 RUN pnpm dlx turbo@^2.5.0 prune ${APP_PACKAGE} --docker
 
-FROM base AS deps
+# Install in the stage that builds: copying node_modules from a separate install stage (many
+# small files) took minutes on some builders, and timed out a Railway build. The manifests come
+# first, so the install layer is still cached until a dependency changes.
+FROM base AS builder
 COPY --from=pruner /app/out/json/ .
 RUN pnpm install --frozen-lockfile
-
-FROM base AS builder
-COPY --from=deps /app/ .
 COPY --from=pruner /app/out/full/ .
 COPY tsconfig.base.json ./
 RUN pnpm build

package/template/apps/start/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/start",
-  "version": "0.16.0",
+  "version": "0.16.1",
   "private": true,
   "license": "Apache-2.0",
   "type": "module",

package/template/apps/web/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/web",
-  "version": "0.16.0",
+  "version": "0.16.1",
   "private": true,
   "license": "Apache-2.0",
   "scripts": {

package/template/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clubedge-starter-v1",
-  "version": "0.16.0",
+  "version": "0.16.1",
   "private": true,
   "license": "Apache-2.0",
   "packageManager": "pnpm@10.9.0",

package/template/packages/auth/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/auth",
-  "version": "0.16.0",
+  "version": "0.16.1",
   "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.16.0",
+  "version": "0.16.1",
   "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.16.0",
+  "version": "0.16.1",
   "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.16.0",
+  "version": "0.16.1",
   "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.16.0",
+  "version": "0.16.1",
   "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.16.0",
+  "version": "0.16.1",
   "private": true,
   "license": "Apache-2.0",
   "type": "module",

package/template/packages/db/package.json

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

package/template/packages/email/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/email",
-  "version": "0.16.0",
+  "version": "0.16.1",
   "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.16.0",
+  "version": "0.16.1",
   "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.16.0",
+  "version": "0.16.1",
   "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.16.0",
+  "version": "0.16.1",
   "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.16.0",
+  "version": "0.16.1",
   "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.16.0",
+  "version": "0.16.1",
   "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.16.0",
+  "version": "0.16.1",
   "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.16.0",
+  "version": "0.16.1",
   "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.16.0",
+  "version": "0.16.1",
   "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.16.0",
+  "version": "0.16.1",
   "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.16.0",
+  "version": "0.16.1",
   "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.16.0",
+  "version": "0.16.1",
   "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.16.0",
+  "version": "0.16.1",
   "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.16.0",
+  "version": "0.16.1",
   "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.16.0",
+  "version": "0.16.1",
   "private": true,
   "license": "Apache-2.0",
   "type": "module",

package/template.lock.json

@@ -1,7 +1,7 @@
 {
   "repository": "Clubedge/clubedge-starter",
-  "ref": "v0.16.0",
-  "commit": "e233aa68ddc8c21df6cf2b01b9e26876d2e4aeca",
+  "ref": "v0.16.1",
+  "commit": "72ff89e53a55a4e4a6262b364ce73be3b1c7a6b9",
   "files": [
     ".dockerignore",
     ".env.example",