@clubedge/create-clubedge-app 0.22.0 → 0.23.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 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).

package/README.md

@@ -199,14 +199,14 @@ pnpm clubedge deploy --env-file .env.production   # with your production provide
 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). Then `railway up` builds the Dockerfile, Railway runs the migrations before the release and checks `/api/health`, and the URL is printed. 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 `--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.22.0
+create-clubedge-app v0.23.0
         |
         v
 Clubedge Starter v0.16.1
@@ -217,7 +217,7 @@ The current relationship is:
 
 | CLI release | Default Starter release | Meaning |
 | --- | --- | --- |
-| `create-clubedge-app@0.22.0` | `clubedge-starter@v0.16.1` | 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`.
 
@@ -313,6 +313,7 @@ Each phase ends with a Starter release and a CLI release pinned to it. The full
 | 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/core/deploy.js

@@ -129,3 +129,48 @@ export function deploymentStatus(output, id, since) {
         : 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

@@ -4,31 +4,94 @@
 import { cancel, confirm, isCancel, log, note, outro, spinner } from "@clack/prompts";
 import { spawn } from "node:child_process";
 import { randomBytes } from "node:crypto";
-import { readFile } from "node:fs/promises";
-import { join, resolve } from "node:path";
+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, parseDeploymentId, parseEnvFile, parseRailwayDomain, parseVariables, planVariables, railwayDatabases, serviceName, serviceNames, } from "./core/deploy.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 { commandSucceeds } from "./utils/process.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";
-// Package manager shims (npx.cmd, railway.cmd) need a shell on Windows. Every argument passed
-// here is a plain word; values go through stdin, so the shell never sees them.
-const useShell = process.platform === "win32";
-/** The Railway CLI: the installed `railway`, or the npm package through npx. */
+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() {
-    if (await commandSucceeds("railway", ["--version"]))
-        return ["railway"];
-    return ["npx", "--yes", "@railway/cli"];
+    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;
+    const [command, ...prefix] = cli.command;
     return await new Promise((resolvePromise, reject) => {
         const child = spawn(command, [...prefix, ...args], {
-            shell: useShell,
+            shell: cli.shell,
+            env: { ...process.env, _: cli.executable },
             stdio: options.inherit ? "inherit" : ["pipe", "pipe", "pipe"],
         });
         let stdout = "";
@@ -58,6 +121,7 @@ async function agree(args, service, databases) {
         `• 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");
@@ -85,6 +149,7 @@ export async function deployProject(args) {
         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`,
@@ -146,7 +211,38 @@ export async function deployProject(args) {
             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();

package/package.json

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