create-apollo-monorepo 0.9.2 → 0.9.4

package/index.mjs

@@ -16,7 +16,7 @@
 
 import { execSync } from "node:child_process";
 import { randomBytes } from "node:crypto";
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, writeFileSync, symlinkSync, rmSync } from "node:fs";
 import { resolve, basename } from "node:path";
 import { createInterface } from "node:readline";
 
@@ -27,7 +27,7 @@ const BACKEND_BRANCH = "main";
 const BACKEND_PATH = "apps/backend";
 const FRONTEND_PATH = "apps/frontend";
 const PROXY_PATH = "apps/proxy";
-const MIN_NODE_MAJOR = 20;
+const MIN_NODE_MAJOR = 22;
 
 // 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
@@ -62,7 +62,9 @@ ${COLORS.bold}Flags:${COLORS.reset}
       --backend-url <url>      Backend git URL (default: ${BACKEND_REPO_URL})
       --backend-branch <name>  Backend branch to track (default: ${BACKEND_BRANCH})
   -d, --db <url>               DATABASE_URL for backend
-  -u, --url <url>              NEXT_PUBLIC_SITE_URL (default: http://localhost:3001 single-origin / 3000 separate)
+  -u, --url <url>              NEXT_PUBLIC_SITE_URL (optional — left blank so the CMS
+                               respects the incoming request origin. Set this only when
+                               you need a fixed origin for background jobs / cron / emails.)
   -l, --locale <code>          NEXT_PUBLIC_DEFAULT_LOCALE (default: en)
       --admin-prefix <path>    Backend prefix in single-origin mode — sets Next.js
                                assetPrefix on the backend AND the path the frontend
@@ -124,6 +126,26 @@ function commandExists(cmd) {
 
 // ─── Arg Parsing ─────────────────────────────────────────────────────────────
 
+// Flag dispatch table. Each entry: aliases → either { key } (takes a value)
+// or { key, value } (boolean flag). `--asset-prefix` is a legacy alias.
+const FLAG_TABLE = {
+  "-h": { key: "help", value: true },
+  "--help": { key: "help", value: true },
+  "--skip-install": { key: "skipInstall", value: true },
+  "--skip-submodule": { key: "skipSubmodule", value: true },
+  "--frontend-name": { key: "frontendName" },
+  "--backend-url": { key: "backendUrl" },
+  "--backend-branch": { key: "backendBranch" },
+  "-d": { key: "db" },
+  "--db": { key: "db" },
+  "-u": { key: "url" },
+  "--url": { key: "url" },
+  "-l": { key: "locale" },
+  "--locale": { key: "locale" },
+  "--admin-prefix": { key: "adminPrefix" },
+  "--asset-prefix": { key: "adminPrefix" },
+};
+
 function parseArgs(argv) {
   const args = argv.slice(2);
   const flags = {
@@ -140,55 +162,16 @@ function parseArgs(argv) {
     help: false,
   };
 
-  let i = 0;
-  while (i < args.length) {
+  for (let i = 0; i < args.length; i++) {
     const arg = args[i];
-    switch (arg) {
-      case "-h":
-      case "--help":
-        flags.help = true;
-        break;
-      case "--frontend-name":
-        flags.frontendName = args[++i];
-        break;
-      case "--backend-url":
-        flags.backendUrl = args[++i];
-        break;
-      case "--backend-branch":
-        flags.backendBranch = args[++i];
-        break;
-      case "-d":
-      case "--db":
-        flags.db = args[++i];
-        break;
-      case "-u":
-      case "--url":
-        flags.url = args[++i];
-        break;
-      case "-l":
-      case "--locale":
-        flags.locale = args[++i];
-        break;
-      case "--admin-prefix":
-      case "--asset-prefix": // legacy alias
-        flags.adminPrefix = args[++i];
-        break;
-      case "--skip-install":
-        flags.skipInstall = true;
-        break;
-      case "--skip-submodule":
-        flags.skipSubmodule = true;
-        break;
-      default:
-        if (arg.startsWith("-")) {
-          fatal(`Unknown flag: ${arg}\nRun with --help for usage.`);
-        }
-        if (flags.directory) {
-          fatal(`Unexpected argument: ${arg}\nOnly one directory name is allowed.`);
-        }
-        flags.directory = arg;
+    const spec = FLAG_TABLE[arg];
+    if (spec) {
+      flags[spec.key] = "value" in spec ? spec.value : args[++i];
+      continue;
     }
-    i++;
+    if (arg.startsWith("-")) fatal(`Unknown flag: ${arg}\nRun with --help for usage.`);
+    if (flags.directory) fatal(`Unexpected argument: ${arg}\nOnly one directory name is allowed.`);
+    flags.directory = arg;
   }
 
   return flags;
@@ -243,29 +226,22 @@ function preflight(flags) {
   }
   success(`Node.js ${process.versions.node}`);
 
-  if (!commandExists("git")) {
-    fatal("git is required but not found.\n  Install: https://git-scm.com/");
-  }
-  success("git found");
-
-  if (!commandExists("pnpm")) {
-    warn("pnpm not found — install with: npm i -g pnpm  (required for workspaces)");
-  } else {
-    success("pnpm found");
-  }
-
   // bun is required at runtime by apps/backend (apollo-cms): db:push, db:seed,
   // dev:cron, plugins:build, the upgrade pipeline, and pre-commit hooks all
   // shell out to `bun`. The scaffold itself works without bun, but `pnpm dev`,
   // `pnpm backend:setup`, and `pnpm backend:upgrade` will fail without it.
-  if (!commandExists("bun")) {
-    warn(
-      "bun not found — required by apps/backend for db:push, db:seed, dev:cron,\n" +
+  const TOOLS = [
+    { cmd: "git",  required: true,  missing: "git is required but not found.\n  Install: https://git-scm.com/" },
+    { cmd: "pnpm", required: false, missing: "pnpm not found — install with: npm i -g pnpm  (required for workspaces)" },
+    { cmd: "bun",  required: false, missing:
+        "bun not found — required by apps/backend for db:push, db:seed, dev:cron,\n" +
         "       plugins:build, and the upgrade pipeline.\n" +
-        "       Install: curl -fsSL https://bun.sh/install | bash  (or: brew install bun)",
-    );
-  } else {
-    success("bun found");
+        "       Install: curl -fsSL https://bun.sh/install | bash  (or: brew install bun)" },
+  ];
+  for (const t of TOOLS) {
+    if (commandExists(t.cmd)) success(`${t.cmd} found`);
+    else if (t.required) fatal(t.missing);
+    else warn(t.missing);
   }
 
   const targetDir = resolve(flags.directory);
@@ -288,24 +264,21 @@ function createPrompt() {
 
 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.
-  // 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;
+  // NEXT_PUBLIC_SITE_URL is intentionally NOT prompted. Apollo CMS resolves
+  // the public origin in this priority order: NEXT_PUBLIC_SITE_URL >
+  // incoming request origin. Leaving it blank lets the runtime respect the
+  // actual request origin (works for localhost, preview URLs, prod domains,
+  // and reverse proxies without any reconfiguration). Override with --url
+  // only when you need a fixed origin for background jobs (cron / triggered
+  // emails) that run outside a request scope.
+  let siteUrl = flags.url ?? "";
   let locale = flags.locale ?? "en";
 
   if (flags.db && !isValidDbUrl(flags.db)) fatal("--db must start with postgresql:// or postgres://");
   if (flags.url && !isValidUrl(flags.url)) fatal("--url must start with http:// or https://");
   if (flags.locale && !isValidLocale(flags.locale)) fatal("--locale must be a 2-5 character code (e.g., en, th)");
 
-  const needsPrompt = !dbUrl || !flags.url || !flags.locale;
+  const needsPrompt = !dbUrl || !flags.locale;
   if (!needsPrompt) return { dbUrl, siteUrl, locale };
 
   const { ask, close } = createPrompt();
@@ -321,16 +294,6 @@ async function gatherEnv(flags, { singleOrigin }) {
     }
   }
 
-  if (!flags.url) {
-    const ans = await ask(
-      `\n    ${COLORS.bold}NEXT_PUBLIC_SITE_URL${COLORS.reset} ${COLORS.dim}[${siteUrl}]${COLORS.reset}\n    > `,
-    );
-    if (ans) {
-      if (isValidUrl(ans)) siteUrl = ans;
-      else warn(`Invalid URL, using default: ${siteUrl}`);
-    }
-  }
-
   if (!flags.locale) {
     const ans = await ask(
       `\n    ${COLORS.bold}Default locale${COLORS.reset} ${COLORS.dim}[${locale}]${COLORS.reset}\n    > `,
@@ -435,33 +398,7 @@ function writeRootPackageJson(targetDir, dirName) {
     devDependencies: {
       concurrently: "^9.0.0",
     },
-    engines: { node: ">=20", pnpm: ">=9" },
-    pnpm: {
-      // apollo-cms transitively pulls multiple esbuild versions (0.18, 0.25, 0.27).
-      // pnpm's binary symlink can pick the wrong platform binary for esbuild's
-      // postinstall version check, failing with "Expected X.Y.Z but got A.B.C".
-      // Allow listed packages to run their build/postinstall scripts; the rest
-      // are skipped (pnpm 10 default is empty allow-list).
-      onlyBuiltDependencies: [
-        "@parcel/watcher",
-        "@rolldown/binding-darwin-arm64",
-        "@rolldown/binding-linux-arm64-gnu",
-        "@rolldown/binding-linux-x64-gnu",
-        "@sentry/cli",
-        "@swc/core",
-        "@swc/core-darwin-arm64",
-        "@swc/core-darwin-x64",
-        "@swc/core-linux-arm64-gnu",
-        "@swc/core-linux-x64-gnu",
-        "better-sqlite3",
-        "core-js",
-        "core-js-pure",
-        "esbuild",
-        "msw",
-        "sharp",
-        "unrs-resolver",
-      ],
-    },
+    engines: { node: ">=22", pnpm: ">=10" },
   };
   writeFileSync(resolve(targetDir, "package.json"), JSON.stringify(pkg, null, 2) + "\n");
 
@@ -475,17 +412,77 @@ function writeRootPackageJson(targetDir, dirName) {
       "strict-peer-dependencies=false",
       "public-hoist-pattern[]=*esbuild*",
       "public-hoist-pattern[]=*types*",
+      // Next.js 16's instrumentation hook (used by Sentry / OpenTelemetry
+      // shipped via apollo-cms) loads require-in-the-middle / import-in-the-middle
+      // at runtime via a bare require. Under pnpm's strict node_modules these
+      // sit deep inside .pnpm/ and the resolver can't see them — Next then
+      // crashes on boot with "Failed to load external module require-in-the-middle".
+      // Hoisting them (plus their `shimmer` dep) to the root node_modules fixes it.
+      "public-hoist-pattern[]=*require-in-the-middle*",
+      "public-hoist-pattern[]=*import-in-the-middle*",
+      "public-hoist-pattern[]=*shimmer*",
       "shell-emulator=true",
       "",
     ].join("\n"),
   );
 }
 
+// Link an app's .env.local to the monorepo root .env.local so the root file
+// stays the single source of truth. Next.js only reads .env.local from its
+// own CWD, so this symlink lets `cd apps/<app> && next dev|build` see the
+// shared config. Falls back to a regular copy (with a warning) on platforms
+// where symlink creation requires elevation (Windows non-admin).
+function linkRootEnvLocal(targetDir, appRelPath, fallbackLines) {
+  const envPath = resolve(targetDir, appRelPath, ".env.local");
+  // appRelPath is `apps/<name>` (2 segments deep) → `../../.env.local`.
+  const depth = appRelPath.split("/").filter(Boolean).length;
+  const linkTarget = "../".repeat(depth) + ".env.local";
+  if (existsSync(envPath)) rmSync(envPath);
+  try {
+    symlinkSync(linkTarget, envPath);
+    success(`${appRelPath}/.env.local → ${linkTarget} (symlink)`);
+  } catch {
+    writeFileSync(envPath, [...fallbackLines, ""].join("\n"));
+    warn(
+      `symlink failed — wrote a copy at ${appRelPath}/.env.local (keep it in sync with the root file manually).`,
+    );
+  }
+}
+
 function writePnpmWorkspace(targetDir) {
-  writeFileSync(
-    resolve(targetDir, "pnpm-workspace.yaml"),
-    "packages:\n  - 'apps/*'\n  - 'apps/cms-plugins/*'\n",
-  );
+  // pnpm 10 reads `onlyBuiltDependencies` from pnpm-workspace.yaml (the
+  // package.json#pnpm location is deprecated for workspaces). apollo-cms
+  // transitively pulls multiple esbuild versions (0.18, 0.25, 0.27); pnpm's
+  // binary symlink can pick the wrong platform binary for esbuild's
+  // postinstall version check, failing with "Expected X.Y.Z but got A.B.C".
+  // Allow listed packages to run their build/postinstall scripts; the rest
+  // are skipped (pnpm 10 default is empty allow-list).
+  const yaml = [
+    "packages:",
+    "  - 'apps/*'",
+    "  - 'apps/cms-plugins/*'",
+    "",
+    "onlyBuiltDependencies:",
+    "  - '@parcel/watcher'",
+    "  - '@rolldown/binding-darwin-arm64'",
+    "  - '@rolldown/binding-linux-arm64-gnu'",
+    "  - '@rolldown/binding-linux-x64-gnu'",
+    "  - '@sentry/cli'",
+    "  - '@swc/core'",
+    "  - '@swc/core-darwin-arm64'",
+    "  - '@swc/core-darwin-x64'",
+    "  - '@swc/core-linux-arm64-gnu'",
+    "  - '@swc/core-linux-x64-gnu'",
+    "  - 'better-sqlite3'",
+    "  - 'core-js'",
+    "  - 'core-js-pure'",
+    "  - 'esbuild'",
+    "  - 'msw'",
+    "  - 'sharp'",
+    "  - 'unrs-resolver'",
+    "",
+  ].join("\n");
+  writeFileSync(resolve(targetDir, "pnpm-workspace.yaml"), yaml);
 }
 
 // Single-origin nginx reference. Only emitted when adminPrefix is set, since
@@ -812,7 +809,7 @@ function parseTarget(input) {
     scripts: {
       start: "node server.mjs",
     },
-    engines: { node: ">=20" },
+    engines: { node: ">=22" },
   };
   writeFileSync(resolve(dir, "package.json"), JSON.stringify(pkg, null, 2) + "\n");
 
@@ -899,7 +896,7 @@ function writeRootGitignore(targetDir) {
   writeFileSync(resolve(targetDir, ".gitignore"), ignore);
 }
 
-function writeRootEnv(targetDir, { dbUrl, siteUrl, locale, authSecret, cronSecret, adminPrefix, backendInternalUrl }) {
+function writeRootEnv(targetDir, { dbUrl, siteUrl, locale, authSecret, cronSecret, adminPrefix, backendInternalUrl, pm2Namespace }) {
   const header = adminPrefix
     ? [
         "# Single-origin monorepo dev env",
@@ -932,42 +929,49 @@ function writeRootEnv(targetDir, { dbUrl, siteUrl, locale, authSecret, cronSecre
     `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).",
+    "# Public origin. Leave blank so the CMS respects the incoming request",
+    "# origin (works for localhost, preview URLs, and prod domains automatically).",
+    "# Set this ONLY when background jobs (cron / triggered emails) need a fixed",
+    "# origin outside a request scope — e.g. NEXT_PUBLIC_SITE_URL=https://cms.example.com",
     `NEXT_PUBLIC_SITE_URL=${siteUrl}`,
     `NEXT_PUBLIC_DEFAULT_LOCALE=${locale}`,
     "",
   ];
 
+  lines.push("# ── Backend (apps/backend) ───────────────────────────────────────");
   if (adminPrefix) {
     lines.push(
-      "# ── Backend (apps/backend) ───────────────────────────────────────",
       "# Single-origin admin/asset prefix. The frontend rewrites this path",
       "# to the backend, so backend chunks (served at <prefix>/_next/static)",
       "# and admin pages share one rewrite.",
       `APOLLO_ASSET_PREFIX=${adminPrefix}`,
-      "# Project-specific plugins — keeps the apollo-cms submodule clean.",
-      `APOLLO_EXTRA_PLUGINS_DIR=../cms-plugins`,
-      "",
-      "# ── Frontend (apps/frontend) ─────────────────────────────────────",
+    );
+  }
+  lines.push(
+    "# Project-specific plugins — keeps the apollo-cms submodule clean.",
+    `APOLLO_EXTRA_PLUGINS_DIR=../cms-plugins`,
+    "# PM2 namespace — groups this project's processes so you can",
+    "# `pm2 stop <namespace>` / `pm2 restart <namespace>` independently of",
+    "# other projects on the same host. Consumed by ecosystem.config.cjs.",
+    `PM2_NAMESPACE=${pm2Namespace}`,
+    "",
+    "# ── Frontend (apps/frontend) ─────────────────────────────────────",
+  );
+  if (adminPrefix) {
+    lines.push(
       "# 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}`,
-      "",
     );
   } else {
     lines.push(
-      "# ── Backend (apps/backend) ───────────────────────────────────────",
-      "# Project-specific plugins — keeps the apollo-cms submodule clean.",
-      `APOLLO_EXTRA_PLUGINS_DIR=../cms-plugins`,
-      "",
-      "# ── Frontend (apps/frontend) ─────────────────────────────────────",
-      `NEXT_PUBLIC_BACKEND_URL=${siteUrl}`,
-      "",
+      "# Where the frontend reaches the backend in separate-origins mode.",
+      "# Defaults to the backend's dev port; override in prod to the real CMS host.",
+      `NEXT_PUBLIC_BACKEND_URL=${siteUrl || `http://localhost:${DEFAULT_BACKEND_PORT}`}`,
     );
   }
+  lines.push("");
 
   writeFileSync(resolve(targetDir, ".env.local"), lines.join("\n"));
 }
@@ -1101,7 +1105,7 @@ export default config;
       ]
     : [
         `# Public URL of the backend (used by your client code)`,
-        `NEXT_PUBLIC_BACKEND_URL=${siteUrl}`,
+        `NEXT_PUBLIC_BACKEND_URL=${siteUrl || `http://localhost:${DEFAULT_BACKEND_PORT}`}`,
         "",
       ];
   writeFileSync(resolve(dir, ".env.local.example"), envLocalLines.join("\n"));
@@ -1488,55 +1492,111 @@ console.log("✓ env check passed");
 // since Next.js handles that internally and the proxy is single-threaded by design).
 function writePm2Config(targetDir, dirName, adminPrefix) {
   const singleOrigin = !!adminPrefix;
+  // The proxy `env` block conditionally includes ADMIN_PREFIX in single-origin
+  // mode. Built outside the template so we don't emit a stray comma or blank line.
+  const proxyEnv = [
+    "NODE_ENV: 'production',",
+    "PROXY_PORT,",
+    "FRONTEND_PORT,",
+    "BACKEND_PORT,",
+    ...(singleOrigin ? [`ADMIN_PREFIX: '${adminPrefix}',`] : []),
+  ].map((l) => "        " + l).join("\n");
+
   const config = `// PM2 ecosystem config for ${dirName}.
+//
+// Loads .env.local at the top so PM2 picks up PROXY_PORT / FRONTEND_PORT /
+// BACKEND_PORT / PM2_NAMESPACE without a shell wrapper. The .env.local file
+// is the single source of truth — edit ports there, not here.
+//
 // Usage:
 //   pnpm install
 //   pnpm backend:upgrade
 //   pnpm build
-//   pm2 start ecosystem.config.cjs                    # FE + BE
-//   pm2 start ecosystem.config.cjs --only proxy       # add reverse proxy
+//   pm2 start ecosystem.config.cjs                    # FE + BE + proxy + cron
+//   pm2 start ecosystem.config.cjs --only proxy       # only the reverse proxy
 //   pm2 start ecosystem.config.cjs --only cron        # self-hosted cron fallback
+//   pm2 stop  \${PM2_NAMESPACE}                         # stop everything in this project
 //   pm2 save && pm2 startup                           # persist across reboots
 
+const fs = require('fs');
+const path = require('path');
+
+// Inline .env.local parser. Kept tiny (no dotenv dep) so the ecosystem file
+// stays runnable before \`pnpm install\` finishes.
+const envPath = path.resolve(__dirname, '.env.local');
+if (fs.existsSync(envPath)) {
+  for (const line of fs.readFileSync(envPath, 'utf8').split('\\n')) {
+    const m = line.match(/^\\s*([A-Z0-9_]+)\\s*=\\s*(.*?)\\s*$/i);
+    if (!m) continue;
+    const k = m[1];
+    let v = m[2];
+    if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) v = v.slice(1, -1);
+    if (process.env[k] === undefined) process.env[k] = v;
+  }
+}
+
+const NAMESPACE     = process.env.PM2_NAMESPACE || '${dirName}';
+const FRONTEND_PORT = Number(process.env.FRONTEND_PORT) || 3001;
+const BACKEND_PORT  = Number(process.env.BACKEND_PORT)  || 3002;
+const PROXY_PORT    = Number(process.env.PROXY_PORT)    || 3030;
+
+// Backend's internal URL (loopback). Cron MUST target this, never the proxy or
+// frontend — going through the FE just adds a failure mode (HTML error → JSON
+// parse blowup in dev-cron.ts).
+const BACKEND_INTERNAL_URL = process.env.BACKEND_INTERNAL_URL || \`http://127.0.0.1:\${BACKEND_PORT}\`;
+
 module.exports = {
   apps: [
     {
-      name: "frontend",
-      cwd: "./apps/frontend",
-      script: "node_modules/next/dist/bin/next",
-      args: "start",
-      env: { NODE_ENV: "production", PORT: Number(process.env.FRONTEND_PORT) || 3001 },
-      max_memory_restart: "1G",
+      name: \`frontend:\${FRONTEND_PORT}\`,
+      namespace: NAMESPACE,
+      cwd: './apps/frontend',
+      script: 'node_modules/next/dist/bin/next',
+      args: 'start',
+      env: {
+        NODE_ENV: 'production',
+        PORT: FRONTEND_PORT,
+        // Next.js rewrites read this at request time. Without it the FE
+        // falls back to http://localhost:3000 and every /admin, /api, and
+        // /uploads request returns ECONNREFUSED.
+        BACKEND_INTERNAL_URL,
+      },
+      max_memory_restart: '1G',
       autorestart: true,
     },
     {
-      name: "backend",
-      cwd: "./apps/backend",
-      script: "node_modules/next/dist/bin/next",
-      args: "start",
-      env: { NODE_ENV: "production", PORT: Number(process.env.BACKEND_PORT) || 3002 },
-      max_memory_restart: "1G",
+      name: \`backend:\${BACKEND_PORT}\`,
+      namespace: NAMESPACE,
+      cwd: './apps/backend',
+      script: 'node_modules/next/dist/bin/next',
+      args: 'start',
+      env: { NODE_ENV: 'production', PORT: BACKEND_PORT },
+      max_memory_restart: '1G',
       autorestart: true,
     },
     {
-      name: "proxy",
-      script: "./apps/proxy/server.mjs",
+      name: \`proxy:\${PROXY_PORT}\`,
+      namespace: NAMESPACE,
+      script: './apps/proxy/server.mjs',
       env: {
-        NODE_ENV: "production",
-        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}",` : ""}
+${proxyEnv}
       },
-      max_memory_restart: "256M",
+      max_memory_restart: '256M',
       autorestart: true,
     },
     {
-      name: "cron",
-      cwd: "./apps/backend",
-      script: "scripts/dev-cron.ts",
-      interpreter: "bun",
-      env: { NODE_ENV: "production" },
+      name: 'cron',
+      namespace: NAMESPACE,
+      cwd: './apps/backend',
+      script: 'scripts/dev-cron.ts',
+      interpreter: 'bun',
+      env: {
+        NODE_ENV: 'production',
+        // dev-cron.ts derives its target from NEXT_PUBLIC_SITE_URL. Override
+        // it to the backend loopback so cron skips the FE/proxy entirely.
+        NEXT_PUBLIC_SITE_URL: BACKEND_INTERNAL_URL,
+        CRON_SECRET: process.env.CRON_SECRET,
+      },
       autorestart: true,
     },
   ],
@@ -1815,12 +1875,18 @@ The installer scaffolds \`ecosystem.config.cjs\`. To supervise everything:
 
 \`\`\`bash
 pm2 start ecosystem.config.cjs                  # FE + BE + proxy + cron (all four)
-pm2 start ecosystem.config.cjs --only frontend,backend   # just the two apps
+pm2 start ecosystem.config.cjs --only proxy     # only the reverse proxy
 pm2 save && pm2 startup                         # persist across reboots
-pm2 logs                                        # tail all processes
-pm2 reload all                                  # zero-downtime restart
+pm2 logs \${PM2_NAMESPACE:-${dirName}}             # tail just this project's logs
+pm2 reload \${PM2_NAMESPACE:-${dirName}}            # zero-downtime restart (namespace-scoped)
+pm2 stop   \${PM2_NAMESPACE:-${dirName}}            # stop only this project
 \`\`\`
 
+All four processes are grouped under the \`PM2_NAMESPACE\` set in \`.env.local\`
+(defaults to \`${dirName}\`), so namespace commands target only this project
+even when other PM2 apps share the host. Process names embed the bound port
+(\`frontend:3001\`, \`backend:3002\`, \`proxy:3030\`) for quick \`pm2 ls\` triage.
+
 The proxy and cron processes can be omitted with \`--only\` if you front the
 apps with nginx/Caddy or use platform cron (system cron, k8s CronJob).
 
@@ -1944,7 +2010,7 @@ async function main() {
   writeRootPackageJson(targetDir, dirName);
   writePnpmWorkspace(targetDir);
   writeRootGitignore(targetDir);
-  writeRootEnv(targetDir, { dbUrl, siteUrl, locale, authSecret, cronSecret, adminPrefix, backendInternalUrl });
+  writeRootEnv(targetDir, { dbUrl, siteUrl, locale, authSecret, cronSecret, adminPrefix, backendInternalUrl, pm2Namespace: dirName });
   writeReadme(targetDir, dirName, frontendName, adminPrefix);
   writeClaudeMd(targetDir, adminPrefix);
   if (adminPrefix) writeNginxSample(targetDir, adminPrefix);
@@ -1995,23 +2061,27 @@ async function main() {
       );
     }
 
-    // Mirror env to backend
-    const backendEnvLines = [
+    const backendFallback = [
       `DATABASE_URL=${dbUrl}`,
       `APOLLO_SECRET=${authSecret}`,
       `CRON_SECRET=${cronSecret}`,
       `NEXT_PUBLIC_SITE_URL=${siteUrl}`,
       `NEXT_PUBLIC_DEFAULT_LOCALE=${locale}`,
       `APOLLO_EXTRA_PLUGINS_DIR=../cms-plugins`,
+      `PM2_NAMESPACE=${dirName}`,
     ];
-    if (adminPrefix) {
-      backendEnvLines.push(`APOLLO_ASSET_PREFIX=${adminPrefix}`);
-    }
-    backendEnvLines.push("");
-    writeFileSync(resolve(targetDir, BACKEND_PATH, ".env.local"), backendEnvLines.join("\n"));
-    success("apps/backend/.env.local");
+    if (adminPrefix) backendFallback.push(`APOLLO_ASSET_PREFIX=${adminPrefix}`);
+    linkRootEnvLocal(targetDir, BACKEND_PATH, backendFallback);
   }
 
+  // Frontend gets the same treatment — Next.js running in apps/frontend
+  // can't see the root file otherwise, and next.config.ts references
+  // BACKEND_INTERNAL_URL for the rewrites destination.
+  const frontendFallback = adminPrefix
+    ? [`BACKEND_INTERNAL_URL=${backendInternalUrl}`]
+    : [`NEXT_PUBLIC_BACKEND_URL=${siteUrl || `http://localhost:${DEFAULT_BACKEND_PORT}`}`];
+  linkRootEnvLocal(targetDir, FRONTEND_PATH, frontendFallback);
+
   // ── Step 7: Install ──
   if (flags.skipInstall) {
     step(7, "Skipping dependency installation (--skip-install)");

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "create-apollo-monorepo",
-  "version": "0.9.2",
+  "version": "0.9.4",
   "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"
   },
   "type": "module",
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "keywords": [
     "apollo",