@clubedge/create-clubedge-app 0.34.0 → 0.35.0

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to `create-clubedge-app` are documented here.
 
+## 0.35.0
+
+- **Deploy a frontend and its separate API** (#103):
+  - `--deploy docker` generates a Compose setup with the Vite frontend and API as separate services. The frontend is public; the API stays on the internal network, and the generated configuration includes each service's port and health check.
+  - `--deploy railway` provisions the frontend and API services, wires the frontend to the private API URL, configures service variables, and runs database migrations before releasing the API.
+  - Deployment capabilities now live in each stack's descriptor, including supported platforms, ports, and health checks. See [docs/stack-packs.md](docs/stack-packs.md).
+- **Default to Starter `v0.24.0`** (#105), which brings all four auth providers to React + Vite with either Hono or FastAPI:
+  - Supabase, Better Auth, Firebase, and Appwrite each have frontend flows and API-side token or session verification.
+  - Generated-project and auth-flow CI covers every provider with both APIs; Docker and Railway deploy configuration is checked for both combinations.
+  - FastAPI now has a committed `uv.lock` for reproducible Python installs. Pull request previews can also deploy the Vite frontend and API as separate Render services.
+
 ## 0.34.0
 
 - **A FastAPI API**: default to Starter `v0.23.0` (#101). `--framework vite --api fastapi` creates the React + Vite frontend with an API in Python, managed with [uv](https://docs.astral.sh/uv/):

package/README.md

@@ -4,7 +4,7 @@
 
 # create-clubedge-app
 
-**Create a production-ready Next.js or TanStack Start app with one command, and keep it up to date.**
+**Create a production-ready React app with one command: Next.js, TanStack Start, or Vite with a separate API.**
 
 Pick only the modules you need: auth, storage, email, payments, jobs, observability, deployment.<br>
 Add, remove, or upgrade them later without losing your own changes.
@@ -53,7 +53,7 @@ The default Starter release ships inside the CLI package, so GitHub is only cont
 
 ## Choosing a framework
 
-The Starter ships the same application for two React frameworks. Next.js is the default; pick TanStack Start with `--framework`, or choose interactively:
+For full-stack apps, the Starter ships the same application for Next.js and TanStack Start. Next.js is the default; pick TanStack Start with `--framework`, or choose interactively:
 
 ```sh
 pnpm dlx @clubedge/create-clubedge-app my-app --framework tanstack-start
@@ -84,7 +84,9 @@ A Python API needs uv; the CLI installs its dependencies with it after `pnpm ins
 
 They meet at one HTTP contract, `packages/contract/openapi.yaml`: the frontend calls the API only through the client generated from it, and every API passes the same conformance suite. `pnpm dev` starts both, and the frontend forwards `/api` to the API. A full-stack framework (`next`, `tanstack-start`) has its own server, so it takes no `--api`.
 
-This is a first version: on these stacks the modules are `none` (cache: memory, deploy: Docker), and `deploy` doesn't set them up yet; SETUP.md in the project describes running both images. See [docs/stack-packs.md](docs/stack-packs.md) for how stacks are described.
+With `--auth supabase`, the Vite app owns the browser session and attaches its access token to contract requests. Hono or FastAPI verifies that token with Supabase Auth and returns the contract's shared user shape. Configure `VITE_SUPABASE_URL`, `VITE_SUPABASE_PUBLISHABLE_KEY`, `SUPABASE_URL`, and `SUPABASE_PUBLISHABLE_KEY` in the generated env examples; no Supabase service-role key goes to the browser.
+
+The decoupled stacks support Supabase Auth, Better Auth, Firebase, Appwrite, or `none`, plus memory cache and Docker or Railway deployment. With Docker, `pnpm clubedge deploy` writes a `compose.yaml` that builds the frontend and API as separate services; copy `.env.example` to `.env.production`, fill in its values, and run `docker compose --env-file .env.production up --build -d`. With Railway, deploy provisions a public frontend and a private API, wires the frontend proxy to the API, and runs migrations before releasing the API. See [docs/stack-packs.md](docs/stack-packs.md) for how stacks and deployment facts are described.
 
 ## Choosing modules
 
@@ -92,7 +94,7 @@ Authentication, file storage, caching, email, payments, background jobs, observa
 
 | Flag        | Options                                    | Default    |
 | ----------- | ------------------------------------------ | ---------- |
-| `--auth`    | `supabase`, `better-auth`, `none`          | `supabase` |
+| `--auth`    | `supabase`, `better-auth`, `firebase`, `appwrite`, `none` | `supabase` |
 | `--storage` | `s3`, `supabase` (needs Supabase Auth), `none` | `s3`   |
 | `--cache`   | `redis` (falls back to memory without `REDIS_URL`), `memory` | `redis` |
 | `--email`   | `smtp` (any provider, or a local inbox), `resend`, `none` | `smtp` |
@@ -150,7 +152,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.23.0
+pnpm dlx @clubedge/create-clubedge-app my-app --ref v0.24.0
 pnpm dlx @clubedge/create-clubedge-app my-app --ref <commit-sha>
 
 # Test local Starter changes before releasing them
@@ -169,7 +171,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.23.0 # or a specific tag, branch, or commit
+pnpm dlx @clubedge/create-clubedge-app upgrade --ref v0.24.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.
@@ -245,7 +247,7 @@ pnpm clubedge deploy --env-file .env.staging      # with another file of product
 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 the env file (`.env.production` when there is one, or `--env-file`) come on top. With a `DATABASE_URL` or `REDIS_URL` in it (Supabase, Neon, Upstash), `deploy` creates no Railway database for it and the app uses yours; URLs to `localhost` are ignored, and a later run without the file keeps the URL the service has. The variables `.env.example` lists that nothing sets are reported, for the modules that need them (storage, email, payments). The service's settings (the migrations before each release, the `/api/health` check) go in `.railway/railway.ts`, Railway's configuration as code, which replaces `railway.json` (Railway stops reading it on 2026-12-01): `deploy` writes it when the project has none, adds Railway's TypeScript SDK (`railway`) as a dev dependency, and applies it with `railway config apply`; commit them. Then `railway up` builds the Dockerfile, and `deploy` waits for Railway's final status before printing the URL. It needs Railway CLI 5.42.1 or newer: an installed `railway`, else one npx already downloaded, else it downloads one. Running `deploy` again reuses everything, so it also adds variables and ships a new release. Railway bills usage on your plan.
+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 and the databases selected by the modules. Full-stack projects get one public app service. A Vite project gets two services: the frontend has the public `*.up.railway.app` domain, and the API stays private; the frontend's Caddy proxy connects to it over Railway's private network. API variables, including `FRONTEND_URL`, go on the API service; `VITE_*` values go on the frontend service for its build. The API's migration command runs before the API release, and the frontend and API deployments are both awaited. Database variables are references to Railway's Postgres and Redis by default. Values from `.env.production` (or `--env-file`) take precedence; external database URLs stay external, and localhost URLs are ignored. `.railway/railway.ts` describes the selected service topology and health checks; `deploy` applies it and adds Railway's TypeScript SDK (`railway`) as a dev dependency. Commit the generated file and package changes. It needs Railway CLI 5.42.1 or newer. Running `deploy` again reuses the services, so it also adds variables and ships new releases. Railway bills usage on your plan.
 
 ### Deploy to Fly.io (experimental)
 
@@ -280,27 +282,27 @@ Projects created with `--infra neon` also have `.github/workflows/preview.yml`,
 Each CLI release is tested against one specific Starter release:
 
 ```text
-create-clubedge-app v0.34.0
+create-clubedge-app v0.35.0
         |
         v
-Clubedge Starter v0.23.0
-commit 0183d091b7bffac92cd0073f12b5329e96fc183f
+Clubedge Starter v0.24.0
+commit 3aaca476bf5ff1db9b5fc4080f7a8a8006436998
 ```
 
 The current relationship is:
 
 | CLI release | Default Starter release | Meaning |
 | --- | --- | --- |
-| `create-clubedge-app@0.34.0` | `clubedge-starter@v0.23.0` | The CLI's required, tested default |
+| `create-clubedge-app@0.35.0` | `clubedge-starter@v0.24.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.23.0` tag is expected to resolve to commit
-`0183d091b7bffac92cd0073f12b5329e96fc183f`. The CLI verifies this before
+The `v0.24.0` tag is expected to resolve to commit
+`3aaca476bf5ff1db9b5fc4080f7a8a8006436998`. 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.23.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.24.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`.
 
@@ -355,7 +357,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.23.0`, and publish the Starter release.
+4. Commit `main`, create a release tag such as `v0.24.0`, and publish the Starter release.
 
 ### CLI maintainers
 
@@ -400,6 +402,7 @@ Each phase ends with a Starter release and a CLI release pinned to it. The full
 | 0.32.0 | v0.21.0 | Pluggable authentication: `--auth firebase` and `--auth appwrite` next to Supabase and Better Auth, and a conformance suite every provider passes |
 | 0.33.0 | v0.22.0 | Starter v0.22.0: stack packs (template schema 4), and a React + Vite frontend with a separate Hono API (`--framework vite --api hono`) |
 | 0.34.0 | v0.23.0 | Starter v0.23.0: a FastAPI API in Python (`--framework vite --api fastapi`), generated with no CLI change |
+| 0.35.0 | v0.24.0 | Deploy frontend and API stack packs; Default to Starter v0.24.0 |
 | next | | Show the Starter's version of a conflicted file next to yours |
 
 ## Community

package/dist/core/customize.js

@@ -37,6 +37,7 @@ export function customizeRootManifest(source, { packageName }, provenance, docke
         ...(provenance.starterCommit ? { starterCommit: provenance.starterCommit } : {}),
         ...recordStacks(provenance.stacks ?? {}),
         ...(provenance.modules ? { modules: provenance.modules } : {}),
+        ...(provenance.services && Object.keys(provenance.services).length ? { services: provenance.services } : {}),
     };
     for (const script of ["docker:build", "docker:start"]) {
         if (typeof manifest.scripts?.[script] === "string") {

package/dist/core/deploy.js

@@ -10,6 +10,24 @@ export function serviceName(packageName) {
     const name = packageName.replace(/^@[^/]+\//, "").toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "");
     return name || "web";
 }
+/** A Docker Compose production topology rendered from the selected stack service descriptors. */
+export function dockerComposeSource(services) {
+    const api = Object.values(services).find((service) => service.role === "api");
+    const rows = Object.entries(services).map(([slot, service]) => {
+        const name = service.id;
+        const frontend = service.role === "frontend";
+        const buildArgs = frontend
+            ? `\n      args:\n        VITE_SUPABASE_URL: \${VITE_SUPABASE_URL:-}\n        VITE_SUPABASE_PUBLISHABLE_KEY: \${VITE_SUPABASE_PUBLISHABLE_KEY:-}`
+            : "";
+        const env = frontend && api
+            ? `\n    environment:\n      API_URL: http://${api.id}:${api.port}`
+            : `\n    env_file:\n      - path: .env.production\n        required: false`;
+        const ports = frontend ? `\n    ports:\n      - "${service.port}:${service.port}"` : `\n    expose:\n      - "${service.port}"`;
+        const depends = frontend && api ? `\n    depends_on:\n      - ${api.id}` : "";
+        return `  ${name}:\n    build:\n      context: .\n      dockerfile: ${service.dockerfile}${buildArgs}${env}${ports}${depends}`;
+    });
+    return `# Generated from Clubedge stack descriptors. Build and start every app service together.\nservices:\n${rows.join("\n")}\n`;
+}
 /** The variable each database's URL goes in. */
 export const databaseVariables = { postgres: "DATABASE_URL", redis: "REDIS_URL" };
 /** A URL to this machine: from a development env file, unreachable from the deployed app. */
@@ -75,11 +93,11 @@ export function parseEnvFile(text) {
  * Everything else the example lists is reported as unset; values the service already has count as set.
  */
 export function planVariables(input) {
-    const { modules, keys, url, envFile, secret, attached = [] } = input;
+    const { modules, keys, url, envFile, secret, attached = [], port = appPort } = input;
     const existing = { ...input.existing, ...Object.fromEntries(attached.map((key) => [key, "(attached)"])) };
     const external = externalDatabaseUrls(modules, envFile);
     const databases = input.databases ?? railwayReferences(databasesFor(modules, Object.keys(external)));
-    const provided = { NODE_ENV: "production", PORT: String(appPort), ...databases };
+    const provided = { NODE_ENV: "production", PORT: String(port), ...databases };
     // The public URL under both names: TanStack Start reads APP_URL, Next.js NEXT_PUBLIC_APP_URL.
     const set = { ...provided, APP_URL: url, NEXT_PUBLIC_APP_URL: url };
     if (modules.auth === "better-auth" && !existing.BETTER_AUTH_SECRET)
@@ -223,7 +241,44 @@ export const railwayIacPath = ".railway/railway.ts";
  * 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) {
+export function railwayIacSource(service, services) {
+    if (services && Object.keys(services).length > 1) {
+        const identifier = (slot) => slot.replace(/[^a-zA-Z0-9_$]/g, "_");
+        const apiEntry = Object.entries(services).find(([, item]) => item.role === "api");
+        const api = apiEntry?.[1];
+        const apiIdentifier = apiEntry ? identifier(apiEntry[0]) : null;
+        const ordered = Object.entries(services).sort(([, a], [, b]) => Number(a.role === "frontend") - Number(b.role === "frontend"));
+        const resources = ordered.map(([slot, item]) => {
+            const name = serviceName(`${service}-${item.id}`);
+            const dockerfilePath = item.dockerfile;
+            const healthcheck = item.healthPath;
+            const migration = item.role === "api" ? 'preDeploy: "node /app/migrate.mjs",' : "";
+            const env = item.role === "frontend" && api && apiIdentifier
+                ? `env: { API_URL: \`http://\${${apiIdentifier}.env.RAILWAY_PRIVATE_DOMAIN}:${api.port}\` },`
+                : "";
+            return `  const ${identifier(slot)} = service(${JSON.stringify(name)}, {
+    build: { builder: "DOCKERFILE", dockerfilePath: ${JSON.stringify(dockerfilePath)} },
+    ${migration}
+    ${env}
+    healthcheck: ${JSON.stringify(healthcheck)},
+    healthcheckTimeout: 60,
+  });`;
+        });
+        const resourceNames = Object.keys(services).map(identifier).join(", ");
+        return `// Generated from the selected stack packs; each app runs as its own Railway service.
+import { defineRailway, project, service } from "railway/iac";
+
+export const partial = ${JSON.stringify(service)};
+
+export default defineRailway(() => {
+${resources.join("\n\n")}
+  return project(${JSON.stringify(service)}, {
+    variables: { managed: false },
+    resources: [${resourceNames}],
+  });
+});
+`;
+    }
     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

package/dist/core/manifest-packs.js

@@ -155,6 +155,7 @@ function parseStack(directory, descriptor, slots, modules) {
         implemented[moduleId] = Object.keys(module.options).filter((option) => options.has(option));
     }
     const toolchain = data.toolchain === undefined ? undefined : parseToolchain(file, data.toolchain);
+    const deployment = data.deployment === undefined ? undefined : parseDeployment(file, data.deployment);
     return {
         id,
         stack: {
@@ -166,10 +167,30 @@ function parseStack(directory, descriptor, slots, modules) {
             dockerfile: resolve(read.requireString(data, "dockerfile"), "dockerfile"),
             modules: implemented,
             ...(toolchain ? { toolchain } : {}),
+            ...(deployment ? { deployment } : {}),
         },
         files,
     };
 }
+function parseDeployment(file, value) {
+    const read = fields(file, "deployment.");
+    if (!isRecord(value))
+        read.fail("deployment must be an object.");
+    const deployment = value;
+    const port = deployment.port;
+    if (typeof port !== "number" || !Number.isInteger(port) || port < 1 || port > 65535) {
+        read.fail("deployment.port must be an integer from 1 to 65535.");
+    }
+    const platforms = read.optionalStringArray(deployment, "platforms");
+    if (!platforms.length)
+        read.fail("deployment.platforms must list at least one platform.");
+    return {
+        id: read.requireId(read.requireString(deployment, "id"), "deployment service"),
+        port: port,
+        healthPath: read.requireString(deployment, "healthPath"),
+        platforms,
+    };
+}
 function parseToolchain(file, value) {
     const read = fields(file, "toolchain.");
     if (!isRecord(value))

package/dist/core/plan.js

@@ -262,6 +262,14 @@ export function createPlan(input) {
         option,
         optionName: manifest.modules[id].options[option].name,
     }));
+    const services = Object.fromEntries(selected.flatMap(({ slotId, slot, stack }) => stack.deployment
+        ? [[slotId, {
+                    ...stack.deployment,
+                    role: stack.role,
+                    app: slot.path,
+                    dockerfile: slot.dockerfile,
+                }]]
+        : []));
     const provenance = {
         cliVersion: input.cliVersion,
         starterRepository: source.repository,
@@ -279,6 +287,7 @@ export function createPlan(input) {
                 moduleSummary: modules.map(({ name, optionName }) => `${name}: ${optionName}`),
             }
             : {}),
+        ...(Object.keys(services).length ? { services } : {}),
     };
     const place = placement(selected, others);
     const envTargets = Object.values(manifest.slots).map((slot) => slot.env.target);

package/dist/core/project.js

@@ -31,6 +31,7 @@ export async function readProject(directory) {
                     starterCommit: origin.starterCommit,
                     stacks: recordedStacks(origin),
                     modules: origin.modules,
+                    services: origin.services && typeof origin.services === "object" ? origin.services : {},
                 };
             }
         }

package/dist/deploy.js

@@ -9,10 +9,10 @@ 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 { FRAMEWORK_SLOT } from "./core/manifest.js";
 import { UsageError } from "./cli/args.js";
 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 { FRAMEWORK_SLOT } from "./core/manifest.js";
+import { appPort, databaseVariables, dockerComposeSource, 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 { neonDatabaseState } from "./core/neon.js";
 import { readProject } from "./core/project.js";
 import { savedDatabaseForUrl } from "./neon.js";
@@ -173,17 +173,207 @@ async function agree(args, service, databases, external) {
     const answer = await confirm({ message: "Deploy?", initialValue: true });
     return !isCancel(answer) && answer;
 }
+async function deployRailwayServices(args, project, cli, envFile) {
+    const selected = Object.entries(project.services);
+    const frontend = selected.find(([, item]) => item.role === "frontend");
+    const api = selected.find(([, item]) => item.role === "api");
+    if (!frontend || !api || selected.length !== 2) {
+        throw new UsageError("Railway deployment currently supports one frontend and one API service in a decoupled project.");
+    }
+    const unsupported = selected.filter(([, service]) => !service.platforms.includes("railway"));
+    if (unsupported.length) {
+        throw new UsageError(`The selected stacks do not declare Railway deployment support for ${unsupported.map(([slot]) => slot).join(", ")}.`);
+    }
+    const [frontendSlot, frontendStack] = frontend;
+    const [apiSlot, apiStack] = api;
+    const baseName = serviceName(project.identity.packageName);
+    const names = {
+        frontend: serviceName(`${baseName}-${frontendStack.id}`),
+        api: serviceName(`${baseName}-${apiStack.id}`),
+    };
+    const keys = exampleKeys(await readFile(join(project.root, ".env.example"), "utf8").catch(() => ""));
+    const external = Object.keys(externalDatabaseUrls(project.modules, envFile));
+    const requestedDatabases = databasesFor(project.modules, external);
+    const serviceSummary = `${frontendSlot} (${frontendStack.dockerfile}) and ${apiSlot} (${apiStack.dockerfile})`;
+    if (args.dryRun) {
+        log.message([
+            `Railway will create two services: ${names.frontend} (public, port ${frontendStack.port}) and ${names.api} (private, port ${apiStack.port}).`,
+            `The frontend proxies /api to ${names.api} over Railway's private network.`,
+            ...(requestedDatabases.length ? [`Databases: ${requestedDatabases.map((db) => railwayDatabases[db]).join(", ")}.`] : []),
+            `Dockerfiles: ${frontendStack.dockerfile}, ${apiStack.dockerfile}. API migrations run before its release.`,
+            `Variables from .env.production are applied to their corresponding services; ${railwayIacPath} records both service configurations.`,
+        ].join("\n"));
+        outro("Dry run: nothing was created. Run again without --dry-run to deploy.");
+        return;
+    }
+    note(`This creates or updates Railway services ${names.frontend} and ${names.api}; publishes only the frontend, connects the services over Railway's private network, and runs migrations before the API release. Railway bills usage on your plan.`, "Deploy frontend and API to Railway");
+    if (!args.yes) {
+        if (!process.stdin.isTTY)
+            throw new UsageError("deploy creates Railway resources. Run it in a terminal to confirm, or pass --yes.");
+        const answer = await confirm({ message: "Deploy?", initialValue: true });
+        if (isCancel(answer) || !answer)
+            return cancel("Nothing was deployed.");
+    }
+    const progress = spinner();
+    progress.start("Preparing the Railway CLI");
+    const rw = await railwayCli();
+    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", baseName, "--json"]);
+        status = await attempt(() => railway(rw, ["status", "--json"]));
+    }
+    let existing = [];
+    try {
+        existing = serviceNames(JSON.parse(status ?? "{}"));
+    }
+    catch { /* unknown status: add missing services */ }
+    const listedApiVars = await attempt(() => railway(rw, ["variable", "list", "--service", names.api, "--json"]));
+    if (listedApiVars === null && existing.includes(names.api)) {
+        throw new Error(`Railway didn't list the variables of the API service "${names.api}", so deploy changed nothing. Run deploy again; if it keeps failing, check \`railway variable list --service ${names.api}\`.`);
+    }
+    const apiVars = parseVariables(listedApiVars ?? "");
+    const kept = databasesFor(project.modules, external)
+        .filter((database) => apiVars[databaseVariables[database]] && !existing.includes(railwayDatabases[database]))
+        .map((database) => databaseVariables[database]);
+    const databases = databasesFor(project.modules, [...external, ...kept]);
+    for (const database of databases) {
+        const name = railwayDatabases[database];
+        if (!existing.includes(name))
+            await railway(rw, ["add", "--database", database]);
+    }
+    for (const name of Object.values(names)) {
+        if (!existing.includes(name))
+            await railway(rw, ["add", "--service", name]);
+    }
+    const listed = await attempt(() => railway(rw, ["domain", "list", "--service", names.frontend]));
+    const domain = parseRailwayDomain(listed ?? "") ?? parseRailwayDomain(await railway(rw, ["domain", "--service", names.frontend, "--port", String(frontendStack.port), "--json"]));
+    if (!domain)
+        throw new Error("Railway created no frontend domain. Create one in its settings, then run deploy again.");
+    const url = `https://${domain}`;
+    const apiEnv = Object.fromEntries(Object.entries(envFile).filter(([key]) => !key.startsWith("VITE_")));
+    const apiPlan = planVariables({
+        modules: project.modules,
+        keys: keys.filter((key) => !key.startsWith("VITE_")),
+        url,
+        existing: apiVars,
+        envFile: apiEnv,
+        secret: () => randomBytes(32).toString("hex"),
+        databases: railwayReferences(databases),
+        port: apiStack.port,
+    });
+    apiPlan.set.FRONTEND_URL = url;
+    if (apiPlan.unset.length) {
+        log.warn(`Not set on the API service: ${apiPlan.unset.join(", ")}. Pass --env-file to supply values before deployment.`);
+        if (process.stdin.isTTY && !args.yes) {
+            const proceed = await confirm({ message: "Deploy anyway?", initialValue: true });
+            if (isCancel(proceed) || !proceed)
+                return cancel("Nothing was uploaded. Set the variables, then run deploy again.");
+        }
+    }
+    for (const [key, value] of Object.entries(apiPlan.set)) {
+        if (apiVars[key] !== value)
+            await railway(rw, ["variable", "set", key, "--stdin", "--service", names.api, "--skip-deploys"], { input: value });
+    }
+    const webVars = parseVariables(await attempt(() => railway(rw, ["variable", "list", "--service", names.frontend, "--json"])) ?? "");
+    const missingWebBuildVars = keys.filter((key) => key.startsWith("VITE_") && !envFile[key] && !webVars[key]);
+    if (missingWebBuildVars.length) {
+        log.warn(`Not set on the frontend service: ${missingWebBuildVars.join(", ")}. Pass --env-file to provide them.`);
+        if (process.stdin.isTTY && !args.yes) {
+            const proceed = await confirm({ message: "Deploy anyway?", initialValue: true });
+            if (isCancel(proceed) || !proceed)
+                return cancel("Nothing was uploaded. Set the variables, then run deploy again.");
+        }
+    }
+    const webSet = { PORT: String(frontendStack.port), ...Object.fromEntries(Object.entries(envFile).filter(([key, value]) => key.startsWith("VITE_") && value)) };
+    for (const [key, value] of Object.entries(webSet)) {
+        if (webVars[key] !== value)
+            await railway(rw, ["variable", "set", key, "--stdin", "--service", names.frontend, "--skip-deploys"], { input: value });
+    }
+    await mkdir(join(project.root, ".railway"), { recursive: true });
+    const iacFile = join(project.root, railwayIacPath);
+    const existingIac = await readFile(iacFile, "utf8").catch(() => "");
+    if (existingIac && !existingIac.includes("The Railway service is named after the package") && !existingIac.includes("Generated from the selected stack packs")) {
+        throw new UsageError(`${railwayIacPath} contains custom configuration. Review it and merge the generated two-service configuration before deploying.`);
+    }
+    await writeFile(iacFile, railwayIacSource(baseName, project.services));
+    const packageJson = JSON.parse(await readFile(join(project.root, "package.json"), "utf8"));
+    if (!packageJson.devDependencies?.railway && !packageJson.dependencies?.railway) {
+        const pnpm = await resolvePnpm();
+        if (!pnpm)
+            throw new UsageError("pnpm was not found. Enable it with `corepack enable`, then run deploy again.");
+        const [command, ...prefix] = pnpm;
+        await run(command, [...prefix, "add", "--save-dev", "--workspace-root", "railway"], project.root);
+    }
+    progress.message("Applying the two-service Railway configuration");
+    await railway(rw, ["config", "apply", "--yes"]);
+    const deployments = [];
+    for (const name of [names.api, names.frontend]) {
+        progress.message(`Uploading ${name}`);
+        const started = new Date();
+        deployments.push({ name, id: parseDeploymentId(await railway(rw, ["up", "--service", name, "--detach"])), started });
+    }
+    for (const item of deployments) {
+        let state = "QUEUED";
+        const deadline = Date.now() + 45 * 60_000;
+        while (!finalStatuses.includes(state) && Date.now() < deadline) {
+            progress.message(`Railway ${item.name}: ${state.toLowerCase()}`);
+            await new Promise((wait) => setTimeout(wait, 10_000));
+            const list = await attempt(() => railway(rw, ["deployment", "list", "--service", item.name, "--json"]));
+            state = deploymentStatus(list ?? "", item.id, item.started)?.status ?? state;
+        }
+        if (state !== "SUCCESS")
+            throw new Error(`Railway's ${item.name} deployment ended as ${state}. Read its build and runtime logs with railway logs --service ${item.name}.`);
+    }
+    progress.stop("Both Railway services are healthy");
+    note(`${bold("Frontend")} ${url}\n${bold("Services")} ${names.frontend} and ${names.api}\n${bold("API")}      private to Railway`, "Deployed to Railway");
+    outro(`${dim("Frontend logs")} railway logs --service ${names.frontend}\n${dim("API logs")}      railway logs --service ${names.api}\n${dim("Again")}          ${cli} deploy`);
+    log.info(`Configured: ${serviceSummary}.`);
+}
 export async function deployProject(args) {
     const project = await readProject(process.cwd());
     const cli = await cliCommand(project);
     const platform = project.modules.deploy ?? "docker";
-    // A frontend and its API are two services; deploy sets up one app so far.
-    const separateApps = Object.keys(project.stacks).filter((slot) => slot !== FRAMEWORK_SLOT);
-    if (separateApps.length) {
-        throw new UsageError(`deploy sets up one app, and this project has a frontend and ${separateApps.join(", ")}. Build each app's Dockerfile (Dockerfile and apps/${separateApps[0]}/Dockerfile) and run them on any container host; SETUP.md describes it.`);
+    const separateApps = Object.entries(project.services).filter(([, service]) => service.role !== "fullstack");
+    const decoupledSlots = Object.keys(project.stacks).filter((slot) => slot !== FRAMEWORK_SLOT);
+    if (decoupledSlots.length && separateApps.length < 2) {
+        throw new UsageError(`This project has a frontend and ${decoupledSlots.join(", ")}, but does not record deployment services for them. Upgrade it to a Starter release whose stacks declare deployment, or build each app's Dockerfile and run them on any container host.`);
     }
     if (args.preview)
         return await deployPreview(args, project, cli, await readDeployEnv(args, project));
+    if (separateApps.length > 1 && platform === "railway") {
+        return await deployRailwayServices(args, project, cli, await readDeployEnv(args, project));
+    }
+    if (separateApps.length > 1 && platform === "docker") {
+        const unsupported = separateApps.filter(([, service]) => !service.platforms.includes("docker"));
+        if (unsupported.length) {
+            throw new UsageError(`The selected stacks do not declare Docker deployment support for ${unsupported.map(([slot]) => slot).join(", ")}.`);
+        }
+        const compose = dockerComposeSource(Object.fromEntries(separateApps));
+        if (args.dryRun) {
+            log.message(`Docker Compose will start ${separateApps.map(([slot, service]) => `${slot} (${service.dockerfile}, port ${service.port})`).join(" and ")}; the frontend proxies /api to the API over the Compose network.`);
+            outro("Dry run: nothing was written. Run deploy to generate compose.yaml.");
+            return;
+        }
+        const path = join(project.root, "compose.yaml");
+        if (await pathExists(path))
+            throw new UsageError("compose.yaml already exists. Review it and remove it before generating the stack configuration again.");
+        await writeFile(path, compose);
+        note(`Generated compose.yaml for ${separateApps.map(([slot]) => slot).join(" and ")}.`, "Docker Compose deployment");
+        outro(`Copy .env.example to .env.production and set its values, then run from the project root:\n  docker compose --env-file .env.production up --build -d\n\nThe frontend is published on its declared port; the API stays on the private Compose network.`);
+        return;
+    }
+    if (separateApps.length > 1) {
+        throw new UsageError(`The ${platform} deploy adapter does not yet support the selected ${separateApps.map(([slot]) => slot).join(" + ")} services. Select Docker Compose with \`${cli} add deploy docker\`, or deploy each Dockerfile separately.`);
+    }
     if (platform === "fly")
         return await deployToFly(args, project, cli, await readDeployEnv(args, project));
     if (platform === "vercel")

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@clubedge/create-clubedge-app",
-  "version": "0.34.0",
-  "description": "Create a Next.js or TanStack Start application from the Clubedge Starter reference implementation.",
+  "version": "0.35.0",
+  "description": "Create a React app with Next.js, TanStack Start, or Vite and a separate API from the Clubedge Starter.",
   "type": "module",
   "packageManager": "pnpm@10.9.0",
   "bin": {
@@ -22,8 +22,8 @@
   },
   "clubedge": {
     "starterRepository": "Clubedge/clubedge-starter",
-    "starterRef": "v0.23.0",
-    "starterCommit": "0183d091b7bffac92cd0073f12b5329e96fc183f"
+    "starterRef": "v0.24.0",
+    "starterCommit": "3aaca476bf5ff1db9b5fc4080f7a8a8006436998"
   },
   "license": "Apache-2.0",
   "repository": {

package/template/.github/workflows/ci.yml

@@ -21,6 +21,7 @@ jobs:
     # clubedge:end
     env:
       DATABASE_URL: postgresql://postgres:postgres@127.0.0.1:5432/postgres
+      UV_LOCKED: "1"
       REDIS_URL: redis://127.0.0.1:6379 # clubedge:only jobs=bullmq
       FIREBASE_AUTH_EMULATOR_HOST: 127.0.0.1:9099 # clubedge:only auth=firebase
       FIREBASE_PROJECT_ID: demo-clubedge # clubedge:only auth=firebase

package/template/.github/workflows/preview.yml

@@ -57,6 +57,37 @@ jobs:
           project_id: ${{ vars.NEON_PROJECT_ID }}
           compare_branch: ${{ env.NEON_BRANCH }}
           api_key: ${{ secrets.NEON_API_KEY }}
+      - name: Identify the app stack for the preview comment
+        id: stack
+        shell: bash
+        run: |
+          set -euo pipefail
+          if [ -f apps/web/package.json ]; then
+            framework=$(node -e 'const p=require("./apps/web/package.json"); const d={...p.dependencies,...p.devDependencies}; console.log(d.vite ? "React + Vite" : d["@tanstack/react-start"] ? "TanStack Start" : "Next.js")')
+          else
+            framework="Next.js"
+          fi
+          api=""
+          if [ "$framework" = "React + Vite" ]; then
+            if [ -f apps/api/pyproject.toml ] || { [ -f apps/api-fastapi/pyproject.toml ] && [ ! -f apps/api/package.json ]; }; then
+              api=" + FastAPI (Python)"
+            elif [ -f apps/api/package.json ]; then
+              api=" + Hono (TypeScript)"
+            fi
+          fi
+          auth=""
+          if [ -f clubedge/modules/auth.json ]; then
+            auth=$(node -e 'console.log(JSON.parse(require("fs").readFileSync("clubedge/modules/auth.json", "utf8")).default)')
+            case "$auth" in
+              supabase) auth=" + Supabase Auth" ;;
+              better-auth) auth=" + Better Auth" ;;
+              firebase) auth=" + Firebase Auth" ;;
+              appwrite) auth=" + Appwrite Auth" ;;
+              none) auth="" ;;
+              *) auth=" + $auth auth" ;;
+            esac
+          fi
+          echo "label=${framework}${api}${auth}" >> "$GITHUB_OUTPUT"
       # clubedge:if deploy=vercel
       # A Vercel preview deployment with the project's Preview variables, except the database,
       # which is the pull request's branch.
@@ -124,6 +155,7 @@ jobs:
           GH_TOKEN: ${{ github.token }}
           PR: ${{ github.event.number }}
           HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          STACK_LABEL: ${{ steps.stack.outputs.label }}
           # Empty without their deploy step.
           VERCEL_URL: ${{ steps.vercel.outputs.url }}
           RAILWAY_URL: ${{ steps.railway.outputs.url }}
@@ -132,11 +164,12 @@ jobs:
           marker="<!-- clubedge-preview -->"
           body="$marker
           **Preview** for ${HEAD_SHA:0:7}
+          - Stack: $STACK_LABEL
           - Database: Neon branch \`$NEON_BRANCH\`, with this pull request's migrations"
           if [ -n "$VERCEL_URL" ]; then body="$body
-          - App on Vercel: $VERCEL_URL"; fi
+          - Vercel app ($STACK_LABEL): $VERCEL_URL"; fi
           if [ -n "$RAILWAY_URL" ]; then body="$body
-          - App on Railway: $RAILWAY_URL"; fi
+          - Railway app ($STACK_LABEL): $RAILWAY_URL"; fi
           id=$(gh api "repos/$GITHUB_REPOSITORY/issues/$PR/comments" --paginate \
             --jq ".[] | select(.body | startswith(\"$marker\")) | .id" | head -n 1)
           if [ -n "$id" ]; then