create-apollo-monorepo 0.9.0 → 0.9.2

package/README.md

@@ -6,15 +6,15 @@ mounted as a **git submodule** backend (read-only — pull updates only).
 ## Usage
 
 ```bash
-npx create-apollo-monorepo thamc-new
+npx create-apollo-monorepo my-site
 ```
 
 With flags:
 
 ```bash
-npx create-apollo-monorepo thamc-new \
-  --frontend-name "@thamc/frontend" \
-  --db "postgresql://user:pass@localhost:5432/thamc" \
+npx create-apollo-monorepo my-site \
+  --frontend-name "@my-site/frontend" \
+  --db "postgresql://user:pass@localhost:5432/my-site" \
   --url "http://localhost:3000" \
   --locale th
 ```
@@ -22,9 +22,9 @@ npx create-apollo-monorepo thamc-new \
 ## Result
 
 ```
-thamc-new/
+my-site/
 ├── apps/
-│   ├── frontend/          ← @thamc/frontend (Next.js skeleton)
+│   ├── frontend/          ← @my-site/frontend (Next.js skeleton)
 │   └── backend/           ← git submodule → apollo-cms
 ├── package.json           ← root workspace
 ├── pnpm-workspace.yaml
@@ -89,7 +89,7 @@ subdomains (e.g. `cms.example.com` + `example.com`).
 ## After install
 
 ```bash
-cd thamc-new
+cd my-site
 pnpm backend:setup   # push schema + seed apollo-cms
 pnpm dev             # frontend :3001 + backend :3000 in parallel
 ```

package/index.mjs

@@ -29,6 +29,13 @@ const FRONTEND_PATH = "apps/frontend";
 const PROXY_PATH = "apps/proxy";
 const MIN_NODE_MAJOR = 20;
 
+// Default dev ports. Kept in sync with scripts/with-env.mjs and the proxy
+// template. .env.local is the runtime source of truth — these are the
+// installer-side fallbacks for computing initial URL defaults.
+const DEFAULT_PROXY_PORT = 3030;
+const DEFAULT_FRONTEND_PORT = 3001;
+const DEFAULT_BACKEND_PORT = 3002;
+
 const COLORS = {
   reset: "\x1b[0m",
   bold: "\x1b[1m",
@@ -46,9 +53,9 @@ ${COLORS.bold}Usage:${COLORS.reset}
   npx create-apollo-monorepo <directory> [flags]
 
 ${COLORS.bold}Examples:${COLORS.reset}
-  npx create-apollo-monorepo thamc-new
-  npx create-apollo-monorepo thamc-new --frontend-name "@thamc/frontend"
-  npx create-apollo-monorepo thamc-new --backend-branch develop --skip-install
+  npx create-apollo-monorepo my-site
+  npx create-apollo-monorepo my-site --frontend-name "@my-site/frontend"
+  npx create-apollo-monorepo my-site --backend-branch develop --skip-install
 
 ${COLORS.bold}Flags:${COLORS.reset}
       --frontend-name <name>   Frontend package name (default: "@<dir>/frontend")
@@ -283,7 +290,14 @@ async function gatherEnv(flags, { singleOrigin }) {
   let dbUrl = flags.db;
   // In single-origin mode the frontend is the public entry → default :3001.
   // In separate-origins mode the backend is the public CMS URL → default :3000.
-  const defaultSiteUrl = singleOrigin ? "http://localhost:3001" : "http://localhost:3000";
+  // Public origin = frontend in single-origin mode (frontend rewrites /admin/*,
+  // /api/*, /uploads/* to the backend), backend in separate-origins mode.
+  // For `pnpm dev:rp` switch this to http://localhost:${PROXY_PORT} in .env.local.
+  // Derived from the PORT constants so changing a default updates both the
+  // .env.local seed and the prompt's suggested value.
+  const defaultSiteUrl = singleOrigin
+    ? `http://localhost:${DEFAULT_FRONTEND_PORT}`
+    : `http://localhost:${DEFAULT_BACKEND_PORT}`;
   let siteUrl = flags.url ?? defaultSiteUrl;
   let locale = flags.locale ?? "en";
 
@@ -355,16 +369,17 @@ function writeRootPackageJson(targetDir, dirName) {
       // rebuild and the backend's plugin loader picks up the fresh
       // dist/server.mjs on next request.
       dev:
-        "pnpm predev:setup && concurrently -k -n FE,BE,PL -c blue,magenta,yellow \"pnpm --filter ./apps/frontend dev\" \"pnpm --filter ./apps/backend exec next dev\" \"pnpm cms-plugins:dev\"",
+        "pnpm predev:setup && concurrently -k -n FE,BE,PL -c blue,magenta,yellow \"pnpm dev:frontend\" \"pnpm dev:backend\" \"pnpm cms-plugins:dev\"",
       // Optional single-origin dev: same as `pnpm dev` but adds a Node.js
-      // reverse proxy on :3030 that fronts FE :3001 + BE :3000. Use it when
-      // you want one URL, shared cookies, and no CORS — without nginx.
+      // reverse proxy on :3030 (PROXY_PORT) that fronts FE :3001 (FRONTEND_PORT)
+      // + BE :3002 (BACKEND_PORT). Ports come from .env.local; override there.
       "dev:rp":
-        "pnpm predev:setup && concurrently -k -n FE,BE,PL,PX -c blue,magenta,yellow,cyan \"pnpm --filter ./apps/frontend dev\" \"pnpm --filter ./apps/backend exec next dev\" \"pnpm cms-plugins:dev\" \"pnpm dev:proxy\"",
-      "dev:proxy": "node apps/proxy/server.mjs",
-      "dev:frontend": "pnpm --filter ./apps/frontend dev",
+        "pnpm predev:setup && concurrently -k -n FE,BE,PL,PX -c blue,magenta,yellow,cyan \"pnpm dev:frontend\" \"pnpm dev:backend\" \"pnpm cms-plugins:dev\" \"pnpm dev:proxy\"",
+      "dev:proxy": "node scripts/with-env.mjs node apps/proxy/server.mjs",
+      "dev:frontend":
+        "node scripts/with-env.mjs --port=FRONTEND_PORT pnpm --filter ./apps/frontend exec next dev",
       "dev:backend":
-        "pnpm predev:setup && pnpm --filter ./apps/backend exec next dev",
+        "pnpm predev:setup && node scripts/with-env.mjs --port=BACKEND_PORT pnpm --filter ./apps/backend exec next dev",
       "dev:cron": "pnpm --filter ./apps/backend exec bun scripts/dev-cron.ts",
       // Build pipeline: cms-plugins → apollo-cms's own plugins → backend → frontend.
       // `prebuild` runs first (npm/pnpm convention) and fails fast if the
@@ -375,17 +390,19 @@ function writeRootPackageJson(targetDir, dirName) {
       "build:backend":
         "pnpm cms-plugins:build && pnpm --filter ./apps/backend exec bun run plugins:build && pnpm --filter ./apps/backend build",
       "build:frontend": "pnpm --filter ./apps/frontend build",
-      // Production start. Runs FE :3001 + BE :3000 in parallel via
-      // \`next start\`. Run \`pnpm backend:upgrade\` BEFORE this — start does
-      // NOT run migrations on boot (zero-downtime restart safety).
+      // Production start. Runs FE :FRONTEND_PORT + BE :BACKEND_PORT (defaults
+      // 3001 + 3002 from .env.local). Run \`pnpm backend:upgrade\` BEFORE this —
+      // start does NOT run migrations on boot (zero-downtime restart safety).
       start:
-        "concurrently -k -n FE,BE -c blue,magenta \"pnpm --filter ./apps/frontend start\" \"pnpm --filter ./apps/backend exec next start\"",
-      // Single-origin production: FE + BE + Node reverse proxy on :3030.
+        "concurrently -k -n FE,BE -c blue,magenta \"pnpm start:frontend\" \"pnpm start:backend\"",
+      // Single-origin production: FE + BE + Node reverse proxy on :PROXY_PORT.
       "start:rp":
-        "concurrently -k -n FE,BE,PX -c blue,magenta,cyan \"pnpm --filter ./apps/frontend start\" \"pnpm --filter ./apps/backend exec next start\" \"pnpm start:proxy\"",
-      "start:proxy": "NODE_ENV=production node apps/proxy/server.mjs",
-      "start:frontend": "pnpm --filter ./apps/frontend start",
-      "start:backend": "pnpm --filter ./apps/backend exec next start",
+        "concurrently -k -n FE,BE,PX -c blue,magenta,cyan \"pnpm start:frontend\" \"pnpm start:backend\" \"pnpm start:proxy\"",
+      "start:proxy": "NODE_ENV=production node scripts/with-env.mjs node apps/proxy/server.mjs",
+      "start:frontend":
+        "node scripts/with-env.mjs --port=FRONTEND_PORT pnpm --filter ./apps/frontend exec next start",
+      "start:backend":
+        "node scripts/with-env.mjs --port=BACKEND_PORT pnpm --filter ./apps/backend exec next start",
       // Self-hosted scheduler fallback. Vercel deploys use Vercel Cron via
       // apps/backend/vercel.json — skip this on Vercel. For Docker / VPS
       // you can either run \`pnpm start:cron\` alongside \`pnpm start\` (PM2
@@ -399,7 +416,13 @@ function writeRootPackageJson(targetDir, dirName) {
       "cms-plugin:new": "node scripts/new-cms-plugin.mjs",
       lint: "pnpm -r lint",
       typecheck: "pnpm -r typecheck",
-      "backend:update": "git submodule update --remote --merge apps/backend",
+      // Stash any local changes inside the submodule so the fast-forward
+      // merge can't conflict, then update, then run `pnpm install` at the
+      // root so workspace deps pick up any package.json changes pulled in
+      // from the new apollo-cms commit. The stash is restored if it was
+      // created; otherwise this is a no-op.
+      "backend:update":
+        "node -e \"const {execSync:e}=require('child_process');const r=s=>e(s,{stdio:'inherit'});const has=e('git -C apps/backend status --porcelain',{encoding:'utf8'}).trim().length>0;if(has)r('git -C apps/backend stash push -u -m backend-update-auto');r('git submodule update --remote --merge apps/backend');r('pnpm install');if(has){try{r('git -C apps/backend stash pop');}catch(_){console.error('[backend:update] stash pop had conflicts — resolve manually with: git -C apps/backend stash list');}}\"",
       // `pnpm setup` is pnpm's CLI bootstrap built-in — must use `run` to
       // forward to the workspace's setup script (apollo-cms's db:push + db:seed).
       "backend:setup": "pnpm --filter ./apps/backend run setup",
@@ -539,10 +562,43 @@ function writeProxyApp(targetDir, dirName, adminPrefix) {
 
 import http from "node:http";
 import net from "node:net";
+import { readFileSync, existsSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// Load root .env.local so the proxy honors PROXY_PORT/FRONTEND_PORT/BACKEND_PORT
+// alongside the frontend & backend. Process env still wins (12-factor friendly).
+(function loadRootEnv() {
+  try {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const envPath = resolve(here, "../../.env.local");
+    if (!existsSync(envPath)) return;
+    for (const raw of readFileSync(envPath, "utf8").split(/\\r?\\n/)) {
+      const line = raw.trim();
+      if (!line || line.startsWith("#")) continue;
+      const eq = line.indexOf("=");
+      if (eq < 0) continue;
+      const key = line.slice(0, eq).trim();
+      if (!/^[A-Z_][A-Z0-9_]*$/i.test(key)) continue;
+      if (process.env[key] !== undefined) continue;
+      let val = line.slice(eq + 1).trim();
+      if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+        val = val.slice(1, -1);
+      }
+      process.env[key] = val;
+    }
+  } catch {
+    // Best-effort. The proxy still runs on its hardcoded fallbacks.
+  }
+})();
 
-const PORT = Number(process.env.PORT ?? 3030);
-const BACKEND = parseTarget(process.env.BACKEND ?? "http://127.0.0.1:3000");
-const FRONTEND = parseTarget(process.env.FRONTEND ?? "http://127.0.0.1:3001");
+// Backward-compatible: PROXY_PORT/FRONTEND_PORT/BACKEND_PORT are the new names;
+// PORT/FRONTEND/BACKEND are still honored if explicitly set in process.env.
+const PORT = Number(process.env.PROXY_PORT ?? process.env.PORT ?? 3030);
+const BACKEND_HOST = process.env.BACKEND ?? \`http://127.0.0.1:\${process.env.BACKEND_PORT ?? 3002}\`;
+const FRONTEND_HOST = process.env.FRONTEND ?? \`http://127.0.0.1:\${process.env.FRONTEND_PORT ?? 3001}\`;
+const BACKEND = parseTarget(BACKEND_HOST);
+const FRONTEND = parseTarget(FRONTEND_HOST);
 
 const ADMIN_PREFIX = process.env.ADMIN_PREFIX ?? "${prefix}";
 // Pipe-separated list of /api/<segment> paths that route to the backend.
@@ -824,6 +880,10 @@ The Node proxy is intended for dev and small self-hosted deploys.
 }
 
 function writeRootGitignore(targetDir) {
+  // NOTE: .env.local is intentionally NOT ignored — it holds shared dev port
+  // defaults (PROXY_PORT/FRONTEND_PORT/BACKEND_PORT) and other non-secret
+  // workspace knobs that should travel with the repo. Keep real secrets in
+  // .env (ignored) or apps/backend/.env.local (ignored by the submodule).
   const ignore = [
     "node_modules",
     ".pnpm-store",
@@ -832,8 +892,6 @@ function writeRootGitignore(targetDir) {
     "dist",
     "build",
     ".env",
-    ".env.local",
-    ".env*.local",
     "*.log",
     ".DS_Store",
     "",
@@ -845,12 +903,12 @@ function writeRootEnv(targetDir, { dbUrl, siteUrl, locale, authSecret, cronSecre
   const header = adminPrefix
     ? [
         "# Single-origin monorepo dev env",
-        "# Public origin = frontend (apps/frontend on :3001). Frontend rewrites /admin/*,",
-        "# /api/*, /uploads/*, and the asset prefix to the backend (apps/backend on :3000).",
+        `# Public origin = frontend (apps/frontend on :${DEFAULT_FRONTEND_PORT}). Frontend rewrites /admin/*,`,
+        `# /api/*, /uploads/*, and the asset prefix to the backend (apps/backend on :${DEFAULT_BACKEND_PORT}).`,
       ]
     : [
         "# Separate-origins monorepo dev env",
-        "# Backend runs at http://localhost:3000, frontend at http://localhost:3001.",
+        `# Backend runs at http://localhost:${DEFAULT_BACKEND_PORT}, frontend at http://localhost:${DEFAULT_FRONTEND_PORT}.`,
         "# To switch to single-origin: set APOLLO_ASSET_PREFIX (default: /admin) and",
         "# BACKEND_INTERNAL_URL, then add rewrites() to apps/frontend/next.config.ts.",
       ];
@@ -858,10 +916,25 @@ function writeRootEnv(targetDir, { dbUrl, siteUrl, locale, authSecret, cronSecre
   const lines = [
     ...header,
     "",
+    "# ── Dev server ports ─────────────────────────────────────────────",
+    "# Single source of truth for local ports. Consumed by:",
+    "#   • apps/proxy/server.mjs  (PROXY_PORT, FRONTEND_PORT, BACKEND_PORT)",
+    "#   • scripts/with-env.mjs   (maps FRONTEND_PORT/BACKEND_PORT → PORT",
+    "#                             when launching apps/frontend & apps/backend,",
+    "#                             and derives NEXT_PUBLIC_SITE_URL /",
+    "#                             BACKEND_INTERNAL_URL when those are unset)",
+    "# Override any of these; the proxy/frontend/backend will follow.",
+    `PROXY_PORT=${DEFAULT_PROXY_PORT}`,
+    `FRONTEND_PORT=${DEFAULT_FRONTEND_PORT}`,
+    `BACKEND_PORT=${DEFAULT_BACKEND_PORT}`,
+    "",
     "# ── Shared (consumed by both apps) ───────────────────────────────",
     `DATABASE_URL=${dbUrl}`,
     `APOLLO_SECRET=${authSecret}`,
     `CRON_SECRET=${cronSecret}`,
+    "# Public origin. In dev, leave blank to auto-derive from FRONTEND_PORT",
+    "# (single-origin) or BACKEND_PORT (separate-origins) via scripts/with-env.mjs.",
+    "# In prod set to the real domain (e.g. https://cms.example.com).",
     `NEXT_PUBLIC_SITE_URL=${siteUrl}`,
     `NEXT_PUBLIC_DEFAULT_LOCALE=${locale}`,
     "",
@@ -878,6 +951,9 @@ function writeRootEnv(targetDir, { dbUrl, siteUrl, locale, authSecret, cronSecre
       `APOLLO_EXTRA_PLUGINS_DIR=../cms-plugins`,
       "",
       "# ── Frontend (apps/frontend) ─────────────────────────────────────",
+      "# Where the frontend's rewrites point internally. In dev, leave blank",
+      "# to auto-derive http://127.0.0.1:${BACKEND_PORT} via scripts/with-env.mjs.",
+      "# In prod set to a private hostname (e.g. http://backend.internal:3000).",
       `BACKEND_INTERNAL_URL=${backendInternalUrl}`,
       "",
     );
@@ -907,9 +983,12 @@ function writeFrontendApp(targetDir, frontendName, siteUrl, adminPrefix, backend
     version: "0.0.0",
     private: true,
     scripts: {
-      dev: "next dev -p 3001",
+      // No -p flag: Next.js reads PORT from env. The repo-root scripts use
+      // scripts/with-env.mjs --port=FRONTEND_PORT to inject the right value
+      // from .env.local (default 3001).
+      dev: "next dev",
       build: "next build",
-      start: "next start -p 3001",
+      start: "next start",
       lint: "next lint",
       typecheck: "tsc --noEmit",
     },
@@ -1039,7 +1118,8 @@ export default config;
 
   writeFileSync(
     resolve(dir, ".gitignore"),
-    ["node_modules", ".next", "dist", ".env.local", ""].join("\n"),
+    // .env.local is intentionally committed — it only contains dev port hints.
+    ["node_modules", ".next", "dist", ""].join("\n"),
   );
 
   // Vercel project config for the frontend. Skip cron + region pinning is
@@ -1267,6 +1347,88 @@ console.log(\`Run: pnpm install && pnpm cms-plugins:build && pnpm dev:backend\`)
   writeFileSync(resolve(scriptsDir, "new-cms-plugin.mjs"), script);
 }
 
+// Small launcher that loads root .env.local, applies port defaults
+// (PROXY_PORT=3030 / FRONTEND_PORT=3001 / BACKEND_PORT=3002), optionally maps
+// one of them onto PORT (Next.js reads PORT), and execs the rest of argv.
+//
+// Usage:
+//   node scripts/with-env.mjs [--port=VAR_NAME] <command> [args...]
+function writeWithEnvScript(targetDir) {
+  const scriptsDir = resolve(targetDir, "scripts");
+  mkdirSync(scriptsDir, { recursive: true });
+  const script = `#!/usr/bin/env node
+// Loads <repo-root>/.env.local so frontend / backend / proxy all share one
+// source of truth for ports. Process env still wins.
+//
+// Usage:
+//   node scripts/with-env.mjs [--port=VAR_NAME] <command> [args...]
+// --port=FRONTEND_PORT copies process.env.FRONTEND_PORT onto PORT before exec,
+// so \`next dev\` and \`next start\` pick up the right port without --port flags.
+
+import { existsSync, readFileSync } from "node:fs";
+import { spawn } from "node:child_process";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const envPath = resolve(here, "../.env.local");
+
+if (existsSync(envPath)) {
+  for (const raw of readFileSync(envPath, "utf8").split(/\\r?\\n/)) {
+    const line = raw.trim();
+    if (!line || line.startsWith("#")) continue;
+    const eq = line.indexOf("=");
+    if (eq < 0) continue;
+    const k = line.slice(0, eq).trim();
+    if (!/^[A-Z_][A-Z0-9_]*$/i.test(k)) continue;
+    if (process.env[k] !== undefined) continue;
+    let v = line.slice(eq + 1).trim();
+    if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) {
+      v = v.slice(1, -1);
+    }
+    process.env[k] = v;
+  }
+}
+
+// Fallbacks — keep in sync with apps/proxy/server.mjs and PM2 config.
+process.env.PROXY_PORT ||= "3030";
+process.env.FRONTEND_PORT ||= "3001";
+process.env.BACKEND_PORT ||= "3002";
+
+// Derive URL vars from PORTs when unset. Dev-friendly: edit a port and
+// everything follows. Prod-friendly: set these explicitly to real hostnames
+// (e.g. https://cms.example.com, http://backend.internal:3000) and the
+// derivation is bypassed.
+//
+// NEXT_PUBLIC_SITE_URL is the public origin — defaults to the frontend port
+// (frontend rewrites /admin, /api, /uploads to the backend). For \`pnpm dev:rp\`
+// set it to http://localhost:\${PROXY_PORT} so Better Auth / OAuth callbacks
+// land on the unified origin.
+process.env.NEXT_PUBLIC_SITE_URL ||= \`http://localhost:\${process.env.FRONTEND_PORT}\`;
+process.env.BACKEND_INTERNAL_URL ||= \`http://127.0.0.1:\${process.env.BACKEND_PORT}\`;
+
+const args = process.argv.slice(2);
+if (args[0]?.startsWith("--port=")) {
+  const name = args.shift().slice(7);
+  if (process.env[name]) process.env.PORT = process.env[name];
+}
+
+if (!args.length) {
+  console.error("Usage: node scripts/with-env.mjs [--port=VAR] <command> [args...]");
+  process.exit(2);
+}
+
+const [cmd, ...rest] = args;
+const child = spawn(cmd, rest, {
+  stdio: "inherit",
+  env: process.env,
+  shell: process.platform === "win32",
+});
+child.on("exit", (code, sig) => process.exit(sig ? 1 : code ?? 0));
+`;
+  writeFileSync(resolve(scriptsDir, "with-env.mjs"), script);
+}
+
 // Pre-build env check. Fails the build before \`next build\` runs if backend
 // required vars are missing, so users don't sit through a 30s build only to
 // hit a runtime error on first request.
@@ -1343,7 +1505,7 @@ module.exports = {
       cwd: "./apps/frontend",
       script: "node_modules/next/dist/bin/next",
       args: "start",
-      env: { NODE_ENV: "production", PORT: 3001 },
+      env: { NODE_ENV: "production", PORT: Number(process.env.FRONTEND_PORT) || 3001 },
       max_memory_restart: "1G",
       autorestart: true,
     },
@@ -1352,7 +1514,7 @@ module.exports = {
       cwd: "./apps/backend",
       script: "node_modules/next/dist/bin/next",
       args: "start",
-      env: { NODE_ENV: "production", PORT: 3000 },
+      env: { NODE_ENV: "production", PORT: Number(process.env.BACKEND_PORT) || 3002 },
       max_memory_restart: "1G",
       autorestart: true,
     },
@@ -1361,9 +1523,9 @@ module.exports = {
       script: "./apps/proxy/server.mjs",
       env: {
         NODE_ENV: "production",
-        PORT: 3030,
-        BACKEND: "http://127.0.0.1:3000",
-        FRONTEND: "http://127.0.0.1:3001",
+        PROXY_PORT: Number(process.env.PROXY_PORT) || 3030,
+        FRONTEND_PORT: Number(process.env.FRONTEND_PORT) || 3001,
+        BACKEND_PORT: Number(process.env.BACKEND_PORT) || 3002,
         ${singleOrigin ? `ADMIN_PREFIX: "${adminPrefix}",` : ""}
       },
       max_memory_restart: "256M",
@@ -1383,6 +1545,100 @@ module.exports = {
   writeFileSync(resolve(targetDir, "ecosystem.config.cjs"), config);
 }
 
+function writeClaudeMd(targetDir, adminPrefix) {
+  const singleOrigin = !!adminPrefix;
+  const prefix = adminPrefix || "/admin";
+  const singleOriginSection = singleOrigin
+    ? `## Single-origin routing
+
+Frontend is the public entry point. It rewrites these paths to the backend (do **not** create matching routes in the frontend):
+
+- \`/admin/*\`, \`/uploads/*\`
+- \`/api/auth/*\`, \`/api/v1/*\`, \`/api/email/*\`, \`/api/cron\`, \`/api/health\`, \`/api/mcp\`, \`/api/admin/*\`, \`/api/editing-presence/*\`
+- \`/_next/static\` under \`APOLLO_ASSET_PREFIX=${prefix}\` (backend chunks)
+
+Custom frontend APIs must be namespaced (e.g. \`/api/internal/*\`).
+
+To disable single-origin: remove \`APOLLO_ASSET_PREFIX\` from \`apps/backend/.env.local\` and delete the \`rewrites()\` block in \`apps/frontend/next.config.ts\`.
+
+Known gotcha: backend's \`/_next/image\` is not rewritten — custom admin code using \`<Image>\` on \`/uploads/*\` will 404. Use plain \`<img>\` or \`unoptimized\`.
+`
+    : `## Routing model — separate origins
+
+Frontend and backend run on independent origins. No rewrites; talk to the backend over its public URL.
+`;
+
+  const content = `# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Repo shape
+
+pnpm workspace monorepo. Three workspaces under \`apps/\`:
+
+- \`apps/frontend\` — public Next.js site${singleOrigin ? " (the public origin in single-origin mode)" : ""}.
+- \`apps/backend\` — **git submodule** pointing at \`apollo-cms\`. Treat as read-only; do not edit files in here. Open PRs upstream.
+- \`apps/cms-plugins/<slug>\` — project-specific Apollo CMS plugins. Loaded by the backend via \`APOLLO_EXTRA_PLUGINS_DIR=../cms-plugins\`. Each plugin is built with esbuild to \`dist/server.mjs\` before the backend builds.
+- \`apps/proxy/server.mjs\` — zero-dep Node reverse proxy used for single-origin dev and self-hosted deploys.
+
+Built-in plugins in \`apps/backend/plugins/\` always win on slug collisions with \`apps/cms-plugins/\`.
+
+${singleOriginSection}
+## Common commands
+
+\`\`\`bash
+pnpm install
+pnpm backend:setup          # first-time: db:push + db:seed
+pnpm backend:upgrade        # release-time: db:push + replay src/upgrades/0.1.*.ts + seed
+pnpm backend:update         # fast-forward the apollo-cms submodule
+
+pnpm dev                    # FE + BE + plugin watcher (parallel)
+pnpm dev:rp                 # same + reverse proxy on :3030 (single origin, shared cookies)
+pnpm dev:frontend           # FE only
+pnpm dev:backend            # BE only (runs predev:setup to build plugins first)
+
+pnpm build                  # cms-plugins → backend plugins → backend → frontend
+pnpm build:backend
+pnpm build:frontend
+
+pnpm start                  # FE + BE
+pnpm start:rp               # FE + BE + proxy
+
+pnpm lint                   # recursive
+pnpm typecheck              # recursive
+
+pnpm cms-plugin:new <slug>  # scaffold a new plugin from example-plugin
+\`\`\`
+
+\`pnpm dev\` and \`pnpm build\` both run \`cms-plugins:build\` first (via \`predev:setup\` / build script chain) — plugins must compile to \`dist/server.mjs\` before the backend resolves them in production. In dev under Bun the loader also accepts \`index.ts\` directly.
+
+Release flow on a server: \`pnpm install && pnpm backend:upgrade && pnpm build && pm2 reload all\`. \`pnpm start\` does **not** run migrations.
+
+## Ports
+
+Configured in \`ecosystem.config.cjs\` (PM2) and consumed by \`apps/proxy/server.mjs\` via env:
+
+| Service  | Port |
+| -------- | ---- |
+| proxy    | 3030 |
+| backend  | 3000 |
+| frontend | 3001 |
+
+Proxy reads \`PORT\`, \`BACKEND\`, \`FRONTEND\`, \`ADMIN_PREFIX\` from env. When using the proxy locally, set \`NEXT_PUBLIC_SITE_URL=http://localhost:3030\` so Better Auth / OAuth callbacks land on the unified origin.
+
+## Deploy
+
+- Self-hosted: build on a runner, rsync to the server, then \`pm2 startOrReload ecosystem.config.cjs --update-env\`. If the backend submodule is private, the deploy runner needs a token with read access.
+- Vercel: two projects per repo (\`apps/backend\` and \`apps/frontend\` root dirs). Backend's Build Command must copy \`apps/cms-plugins/*/dist\` into \`apps/backend/plugins/\` before \`next build\` because Turbopack rejects \`outputFileTracingIncludes\` globs above the project root. "Include all submodules" must be ON in both projects.
+
+## Submodule discipline
+
+- Do not edit files under \`apps/backend\` — they belong to the upstream \`apollo-cms\` repo.
+- After \`pnpm backend:update\`, run \`pnpm install\` (in case package.json changed) then \`pnpm backend:upgrade\` (replays data migrations that \`backend:setup\` skips).
+`;
+  writeFileSync(resolve(targetDir, "CLAUDE.md"), content);
+}
+
 function writeReadme(targetDir, dirName, frontendName, adminPrefix) {
   const singleOrigin = !!adminPrefix;
 
@@ -1511,14 +1767,13 @@ folder + \`plugin.json#name\`.
 Apollo CMS is tracked as a git submodule. Full upgrade flow:
 
 \`\`\`bash
-pnpm backend:update    # fast-forward apps/backend to the latest apollo-cms commit
-pnpm install           # in case the submodule changed package.json
+pnpm backend:update    # auto-stash, fast-forward apps/backend, run pnpm install
 pnpm backend:upgrade   # drizzle push + replay version migrations + seed
 \`\`\`
 
 | Script | What it does |
 | --- | --- |
-| \`pnpm backend:update\`  | \`git submodule update --remote --merge apps/backend\` — code only |
+| \`pnpm backend:update\`  | Auto-stashes local submodule changes, fast-forwards \`apps/backend\`, runs \`pnpm install\` so new backend deps are picked up, then restores the stash. |
 | \`pnpm backend:setup\`   | First-time bootstrap: \`db:push\` + \`db:seed\` only |
 | \`pnpm backend:upgrade\` | Full pipeline: \`db:push\` + replay \`src/upgrades/0.1.*.ts\` data migrations + \`db:seed\`. **Use this** after \`backend:update\` — \`backend:setup\` skips the data-migration phase. |
 
@@ -1659,7 +1914,7 @@ async function main() {
 
   if (!flags.directory) {
     log(HELP_TEXT);
-    fatal("Please provide a directory name.\n  Example: npx create-apollo-monorepo thamc-new");
+    fatal("Please provide a directory name.\n  Example: npx create-apollo-monorepo my-site");
   }
 
   log(`\n${COLORS.bold}${COLORS.cyan}  Apollo CMS Monorepo Installer${COLORS.reset}\n`);
@@ -1678,7 +1933,7 @@ async function main() {
   // Required by apollo-cms's /api/cron route and scripts/dev-cron.ts in dev.
   // Without it the dev cron loop hits 403 "CRON_SECRET not configured".
   const cronSecret = randomBytes(24).toString("hex");
-  const backendInternalUrl = "http://localhost:3000";
+  const backendInternalUrl = `http://localhost:${DEFAULT_BACKEND_PORT}`;
   success(`Frontend pkg name: ${frontendName}`);
   success(`Admin prefix: ${adminPrefix || "(disabled — separate origins)"}`);
 
@@ -1691,14 +1946,16 @@ async function main() {
   writeRootGitignore(targetDir);
   writeRootEnv(targetDir, { dbUrl, siteUrl, locale, authSecret, cronSecret, adminPrefix, backendInternalUrl });
   writeReadme(targetDir, dirName, frontendName, adminPrefix);
+  writeClaudeMd(targetDir, adminPrefix);
   if (adminPrefix) writeNginxSample(targetDir, adminPrefix);
   writeProxyApp(targetDir, dirName, adminPrefix);
   writeCheckEnvScript(targetDir);
+  writeWithEnvScript(targetDir);
   writePm2Config(targetDir, dirName, adminPrefix);
   success(
-    `package.json, pnpm-workspace.yaml, .gitignore, .env.local, README.md${
+    `package.json, pnpm-workspace.yaml, .gitignore, .env.local, README.md, CLAUDE.md${
       adminPrefix ? ", nginx.conf.sample" : ""
-    }, apps/proxy, ecosystem.config.cjs, scripts/check-env.mjs`,
+    }, apps/proxy, ecosystem.config.cjs, scripts/check-env.mjs, scripts/with-env.mjs`,
   );
 
   // ── Step 4: git init ──

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-apollo-monorepo",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "Scaffold a monorepo with a frontend app and Apollo CMS as a git submodule backend (single-origin via Next.js rewrites + assetPrefix)",
   "bin": {
     "create-apollo-monorepo": "index.mjs"
@@ -21,7 +21,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/5Lab-Group-Co-Ltd/apollo-cms.git",
+    "url": "git+https://github.com/5Lab-Group-Co-Ltd/apollo-cms.git",
     "directory": "installer-monorepo"
   },
   "license": "MIT"