create-apollo-monorepo 0.8.0 → 0.9.1

package/index.mjs

@@ -367,8 +367,31 @@ function writeRootPackageJson(targetDir, dirName) {
         "pnpm predev:setup && 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
+      // backend's required env vars are missing.
+      prebuild: "node scripts/check-env.mjs",
       build:
         "pnpm cms-plugins:build && pnpm --filter ./apps/backend exec bun run plugins:build && pnpm --filter ./apps/backend build && pnpm --filter ./apps/frontend build",
+      "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).
+      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.
+      "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",
+      // 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
+      // handles this via ecosystem.config.cjs), or use system cron / k8s
+      // CronJob to hit /api/cron with CRON_SECRET.
+      "start:cron": "pnpm --filter ./apps/backend exec bun scripts/dev-cron.ts",
       "cms-plugins:build":
         "pnpm --filter './apps/cms-plugins/*' --parallel --if-present build",
       "cms-plugins:dev":
@@ -376,7 +399,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",
@@ -1244,6 +1273,216 @@ console.log(\`Run: pnpm install && pnpm cms-plugins:build && pnpm dev:backend\`)
   writeFileSync(resolve(scriptsDir, "new-cms-plugin.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.
+function writeCheckEnvScript(targetDir) {
+  const scriptsDir = resolve(targetDir, "scripts");
+  mkdirSync(scriptsDir, { recursive: true });
+  const script = `#!/usr/bin/env node
+// Pre-build sanity check. Reads apps/backend/.env.local and verifies that
+// required vars are present and non-empty. Skipped when SKIP_ENV_CHECK=1.
+//
+// In CI/Vercel where envs come from the platform (not files), set
+// SKIP_ENV_CHECK=1 and rely on the platform's own validation.
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+if (process.env.SKIP_ENV_CHECK === "1") process.exit(0);
+
+const REQUIRED = ["DATABASE_URL", "APOLLO_SECRET", "NEXT_PUBLIC_DEFAULT_LOCALE"];
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const envPath = resolve(__dirname, "../apps/backend/.env.local");
+
+if (!existsSync(envPath)) {
+  // Allow build to proceed if env vars are coming from process.env directly.
+  const fromProcess = REQUIRED.every((k) => process.env[k]);
+  if (fromProcess) process.exit(0);
+  console.error(
+    \`✗ Missing apps/backend/.env.local and required vars not in process.env.\\n  Required: \${REQUIRED.join(", ")}\\n  Hint: re-run the installer or copy apps/backend/.env.local.example\`,
+  );
+  process.exit(1);
+}
+
+const env = Object.fromEntries(
+  readFileSync(envPath, "utf-8")
+    .split("\\n")
+    .filter((line) => line && !line.startsWith("#"))
+    .map((line) => {
+      const i = line.indexOf("=");
+      return i === -1 ? [line, ""] : [line.slice(0, i).trim(), line.slice(i + 1).trim()];
+    }),
+);
+
+const missing = REQUIRED.filter((k) => !env[k] && !process.env[k]);
+if (missing.length) {
+  console.error(\`✗ Missing required env vars: \${missing.join(", ")}\\n  Edit apps/backend/.env.local or set them in process.env.\`);
+  process.exit(1);
+}
+console.log("✓ env check passed");
+`;
+  writeFileSync(resolve(scriptsDir, "check-env.mjs"), script);
+}
+
+// PM2 ecosystem config — production process supervision for self-hosted deploys.
+// Includes FE, BE, optional proxy, and optional cron in fork mode (no clustering
+// since Next.js handles that internally and the proxy is single-threaded by design).
+function writePm2Config(targetDir, dirName, adminPrefix) {
+  const singleOrigin = !!adminPrefix;
+  const config = `// PM2 ecosystem config for ${dirName}.
+// 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 --only cron        # self-hosted cron fallback
+//   pm2 save && pm2 startup                           # persist across reboots
+
+module.exports = {
+  apps: [
+    {
+      name: "frontend",
+      cwd: "./apps/frontend",
+      script: "node_modules/next/dist/bin/next",
+      args: "start",
+      env: { NODE_ENV: "production", PORT: 3001 },
+      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: 3000 },
+      max_memory_restart: "1G",
+      autorestart: true,
+    },
+    {
+      name: "proxy",
+      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",
+        ${singleOrigin ? `ADMIN_PREFIX: "${adminPrefix}",` : ""}
+      },
+      max_memory_restart: "256M",
+      autorestart: true,
+    },
+    {
+      name: "cron",
+      cwd: "./apps/backend",
+      script: "scripts/dev-cron.ts",
+      interpreter: "bun",
+      env: { NODE_ENV: "production" },
+      autorestart: true,
+    },
+  ],
+};
+`;
+  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;
 
@@ -1372,14 +1611,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. |
 
@@ -1391,6 +1629,53 @@ Do **not** edit files inside \`apps/backend\`. Open issues / PRs in the
 Shared dev env lives in the root \`.env.local\`. The backend reads its own
 \`apps/backend/.env.local\` (already populated by the installer).
 
+## Deploy (self-hosted)
+
+Standard sequence on a VPS / Docker host / bare metal:
+
+\`\`\`bash
+pnpm install
+pnpm backend:upgrade   # db push + replay data migrations + seed (run ONCE per release)
+pnpm build             # builds plugins → backend → frontend
+pnpm start             # FE :3001 + BE :3000  — or:
+pnpm start:rp          # adds Node reverse proxy on :3030 (single origin)
+\`\`\`
+
+\`pnpm start\` does **not** run migrations on boot — that lets you restart
+processes without re-running \`drizzle-kit push\` every time. Always run
+\`pnpm backend:upgrade\` once per release before \`pnpm start\`.
+
+| Script              | What it does                                                        |
+| ------------------- | ------------------------------------------------------------------- |
+| \`pnpm build\`        | Full pipeline: cms-plugins → backend plugins → backend → frontend   |
+| \`pnpm start\`        | FE + BE (parallel \`next start\`)                                     |
+| \`pnpm start:rp\`     | FE + BE + reverse proxy on :3030                                    |
+| \`pnpm start:proxy\`  | Reverse proxy alone (already running FE/BE separately)              |
+| \`pnpm start:cron\`   | Self-hosted cron fallback — only if not using Vercel Cron / k8s     |
+
+### PM2 (recommended for VPS)
+
+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 save && pm2 startup                         # persist across reboots
+pm2 logs                                        # tail all processes
+pm2 reload all                                  # zero-downtime restart
+\`\`\`
+
+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).
+
+### Docker / k8s
+
+For containerized deploys:
+- Bake the build into the image (\`pnpm install && pnpm build\`)
+- Set entrypoint to \`pnpm start\` or \`pnpm start:rp\`
+- Run \`pnpm backend:upgrade\` as a separate init container / Job before app pods start
+- Use platform-native cron (k8s CronJob hitting \`/api/cron\` with \`CRON_SECRET\`) instead of \`pnpm start:cron\`
+
 ## Deploy on Vercel
 
 Two Vercel projects, one repo. Each project picks up its own Root Directory.
@@ -1505,12 +1790,15 @@ 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);
+  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`,
+    }, apps/proxy, ecosystem.config.cjs, scripts/check-env.mjs`,
   );
 
   // ── Step 4: git init ──

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-apollo-monorepo",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "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"