create-apollo-monorepo 0.1.0 → 0.2.0

package/README.md

@@ -33,6 +33,34 @@ thamc-new/
 └── .gitignore
 ```
 
+## Routing modes
+
+### Single-origin (default)
+
+Both apps share one public origin (the frontend). The frontend's
+`next.config.ts` rewrites these paths to the backend so `/_next/*` doesn't
+collide:
+
+| Browser path                         | Goes to              |
+| ------------------------------------ | -------------------- |
+| `/`, your custom routes              | `apps/frontend`      |
+| `/admin/*`                           | `apps/backend`       |
+| `/api/auth/*`, `/api/v1/*`, `/api/admin/*`, `/api/email/*`, `/api/cron`, `/api/health`, `/api/mcp`, `/api/editing-presence/*` | `apps/backend` |
+| `/uploads/*`                         | `apps/backend` (media) |
+| `/cms-assets/*`                      | `apps/backend` chunks (via `APOLLO_ASSET_PREFIX`) |
+| `/monitoring`                        | `apps/backend` (Sentry tunnel, no-op without DSN) |
+
+Apollo CMS picks up `APOLLO_ASSET_PREFIX=/cms-assets` and serves its built JS
+under that namespace, sidestepping the `/_next/*` collision. The frontend
+**must not** define routes at `/admin`, `/api/auth`, `/api/v1`, etc.
+
+### Separate origins (fallback)
+
+Pass `--asset-prefix none` (or `off`/`false`/`disabled`) to skip the rewrite
+wiring. The backend runs at `http://localhost:3000` and the frontend at
+`http://localhost:3001`. Useful when you'd rather deploy them on separate
+subdomains (e.g. `cms.example.com` + `example.com`).
+
 ## Flags
 
 | Flag                       | Default                                 | Description                          |
@@ -41,8 +69,9 @@ thamc-new/
 | `--backend-url <url>`      | `https://github.com/5Lab-Group-Co-Ltd/apollo-cms.git` | Submodule git URL          |
 | `--backend-branch <name>`  | `main`                                  | Submodule branch to track            |
 | `-d, --db <url>`           | _(prompted)_                            | `DATABASE_URL` for backend           |
-| `-u, --url <url>`          | `http://localhost:3000`                 | `NEXT_PUBLIC_SITE_URL`               |
+| `-u, --url <url>`          | `:3001` single-origin / `:3000` separate | `NEXT_PUBLIC_SITE_URL`               |
 | `-l, --locale <code>`      | `en`                                    | `NEXT_PUBLIC_DEFAULT_LOCALE`         |
+| `--asset-prefix <path>`    | `/cms-assets`                           | Single-origin asset namespace; `none` to disable |
 | `--skip-install`           | off                                     | Don't run `pnpm install`             |
 | `--skip-submodule`         | off                                     | Don't add the git submodule          |
 | `-h, --help`               | —                                       | Show help                            |
@@ -55,6 +84,11 @@ pnpm backend:setup   # push schema + seed apollo-cms
 pnpm dev             # frontend :3001 + backend :3000 in parallel
 ```
 
+In single-origin mode open `http://localhost:3001/admin` (the frontend port);
+the rewrite proxies to the backend and Better Auth's cookies/origins line up
+because `NEXT_PUBLIC_SITE_URL` and the backend's `trustedProxyHeaders` are wired
+to the public origin.
+
 ## Updating the backend
 
 ```bash

package/index.mjs

@@ -54,11 +54,21 @@ ${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:3000)
+  -u, --url <url>              NEXT_PUBLIC_SITE_URL (default: http://localhost:3001 single-origin / 3000 separate)
   -l, --locale <code>          NEXT_PUBLIC_DEFAULT_LOCALE (default: en)
+      --asset-prefix <path>    Single-origin asset namespace (default: /cms-assets, or "none" to disable)
       --skip-install           Skip dependency installation
       --skip-submodule         Skip git submodule add (you'll add it later)
   -h, --help                   Show this help message
+
+${COLORS.bold}Single-origin model:${COLORS.reset}
+  The frontend is the public entry point. It rewrites these paths to the
+  backend so both apps live under one domain without /_next/* collisions:
+    /admin/*           → backend
+    /api/*             → backend (REST API + auth)
+    /uploads/*         → backend (media)
+    <asset-prefix>/*   → backend (Next.js chunks via APOLLO_ASSET_PREFIX)
+  Frontend MUST NOT define routes at /admin or /api/auth or /api/v1.
 `;
 
 // ─── Helpers ─────────────────────────────────────────────────────────────────
@@ -112,6 +122,7 @@ function parseArgs(argv) {
     db: null,
     url: null,
     locale: null,
+    assetPrefix: "/cms-assets",
     skipInstall: false,
     skipSubmodule: false,
     help: false,
@@ -146,6 +157,9 @@ function parseArgs(argv) {
       case "--locale":
         flags.locale = args[++i];
         break;
+      case "--asset-prefix":
+        flags.assetPrefix = args[++i];
+        break;
       case "--skip-install":
         flags.skipInstall = true;
         break;
@@ -181,6 +195,23 @@ function isValidLocale(code) {
   return /^[a-z]{2,5}$/i.test(code);
 }
 
+// Normalize an asset prefix:
+//  - empty string / "none" / "off" / "false"  → "" (single-origin disabled, fallback to separate origins)
+//  - "/foo"                                    → "/foo"
+//  - "foo"                                     → "/foo"
+//  - "/foo/"                                   → "/foo"
+function normalizeAssetPrefix(value) {
+  if (!value) return "";
+  const trimmed = String(value).trim();
+  if (trimmed === "" || /^(none|off|false|disabled)$/i.test(trimmed)) return "";
+  let p = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+  p = p.replace(/\/+$/, "");
+  if (!/^\/[a-z0-9._-]+(\/[a-z0-9._-]+)*$/i.test(p)) {
+    fatal(`Invalid --asset-prefix: ${value}\n  Use a path like /cms-assets, or "none" to disable single-origin.`);
+  }
+  return p;
+}
+
 // ─── Pre-flight ──────────────────────────────────────────────────────────────
 
 function preflight(flags) {
@@ -223,9 +254,12 @@ function createPrompt() {
   return { ask, close };
 }
 
-async function gatherEnv(flags) {
+async function gatherEnv(flags, { singleOrigin }) {
   let dbUrl = flags.db;
-  let siteUrl = flags.url ?? "http://localhost:3000";
+  // 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";
+  let siteUrl = flags.url ?? defaultSiteUrl;
   let locale = flags.locale ?? "en";
 
   if (flags.db && !isValidDbUrl(flags.db)) fatal("--db must start with postgresql:// or postgres://");
@@ -321,23 +355,53 @@ function writeRootGitignore(targetDir) {
   writeFileSync(resolve(targetDir, ".gitignore"), ignore);
 }
 
-function writeRootEnv(targetDir, { dbUrl, siteUrl, locale, authSecret }) {
+function writeRootEnv(targetDir, { dbUrl, siteUrl, locale, authSecret, assetPrefix, backendInternalUrl }) {
+  const header = assetPrefix
+    ? [
+        "# 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).",
+      ]
+    : [
+        "# Separate-origins monorepo dev env",
+        "# Backend runs at http://localhost:3000, frontend at http://localhost:3001.",
+        "# To switch to single-origin: set APOLLO_ASSET_PREFIX, BACKEND_INTERNAL_URL,",
+        "# NEXT_PUBLIC_APOLLO_ASSET_PREFIX, and add rewrites() to apps/frontend/next.config.ts.",
+      ];
+
   const lines = [
-    "# Shared dev env — backend reads these via apps/backend/.env.local symlink/copy",
+    ...header,
+    "",
+    "# ── Shared (consumed by both apps) ───────────────────────────────",
     `DATABASE_URL=${dbUrl}`,
     `APOLLO_SECRET=${authSecret}`,
-    `BETTER_AUTH_SECRET=${authSecret}`,
     `NEXT_PUBLIC_SITE_URL=${siteUrl}`,
     `NEXT_PUBLIC_DEFAULT_LOCALE=${locale}`,
     "",
-    "# Frontend",
-    `NEXT_PUBLIC_BACKEND_URL=${siteUrl}`,
-    "",
-  ].join("\n");
-  writeFileSync(resolve(targetDir, ".env.local"), lines);
+  ];
+
+  if (assetPrefix) {
+    lines.push(
+      "# ── Backend (apps/backend) ───────────────────────────────────────",
+      `APOLLO_ASSET_PREFIX=${assetPrefix}`,
+      "",
+      "# ── Frontend (apps/frontend) ─────────────────────────────────────",
+      `BACKEND_INTERNAL_URL=${backendInternalUrl}`,
+      `NEXT_PUBLIC_APOLLO_ASSET_PREFIX=${assetPrefix}`,
+      "",
+    );
+  } else {
+    lines.push(
+      "# ── Frontend (apps/frontend) ─────────────────────────────────────",
+      `NEXT_PUBLIC_BACKEND_URL=${siteUrl}`,
+      "",
+    );
+  }
+
+  writeFileSync(resolve(targetDir, ".env.local"), lines.join("\n"));
 }
 
-function writeFrontendApp(targetDir, frontendName, siteUrl) {
+function writeFrontendApp(targetDir, frontendName, siteUrl, assetPrefix, backendInternalUrl) {
   const dir = resolve(targetDir, FRONTEND_PATH);
   mkdirSync(dir, { recursive: true });
   mkdirSync(resolve(dir, "src/app"), { recursive: true });
@@ -397,15 +461,70 @@ function writeFrontendApp(targetDir, frontendName, siteUrl) {
     ) + "\n",
   );
 
-  writeFileSync(
-    resolve(dir, "next.config.ts"),
-    `import type { NextConfig } from "next";\n\nconst config: NextConfig = {\n  reactStrictMode: true,\n};\n\nexport default config;\n`,
-  );
+  // Frontend Next.js config:
+  //  - Single-origin mode (assetPrefix set): rewrite all backend paths.
+  //  - Separate-origins mode (assetPrefix empty): no rewrites; the two apps
+  //    are reachable on their own ports/subdomains.
+  const nextConfigContent = assetPrefix
+    ? `import type { NextConfig } from "next";
+
+const BACKEND = process.env.BACKEND_INTERNAL_URL ?? "http://localhost:3000";
+const ASSET_PREFIX = process.env.NEXT_PUBLIC_APOLLO_ASSET_PREFIX ?? "${assetPrefix}";
+
+const config: NextConfig = {
+  reactStrictMode: true,
+  async rewrites() {
+    return [
+      // Apollo CMS admin UI
+      { source: "/admin/:path*", destination: \`\${BACKEND}/admin/:path*\` },
+      // Apollo CMS APIs (REST + auth + cron + email + health + mcp + …)
+      { source: "/api/auth/:path*", destination: \`\${BACKEND}/api/auth/:path*\` },
+      { source: "/api/v1/:path*",   destination: \`\${BACKEND}/api/v1/:path*\` },
+      { source: "/api/cron",        destination: \`\${BACKEND}/api/cron\` },
+      { source: "/api/email/:path*", destination: \`\${BACKEND}/api/email/:path*\` },
+      { source: "/api/health",      destination: \`\${BACKEND}/api/health\` },
+      { source: "/api/mcp",         destination: \`\${BACKEND}/api/mcp\` },
+      { source: "/api/editing-presence/:path*", destination: \`\${BACKEND}/api/editing-presence/:path*\` },
+      { source: "/api/admin/:path*", destination: \`\${BACKEND}/api/admin/:path*\` },
+      // Media uploads
+      { source: "/uploads/:path*",  destination: \`\${BACKEND}/uploads/:path*\` },
+      // Sentry tunnel (no-op if SENTRY_DSN isn't set on the backend)
+      { source: "/monitoring",      destination: \`\${BACKEND}/monitoring\` },
+      // Backend's namespaced Next.js chunks (set via APOLLO_ASSET_PREFIX)
+      { source: \`\${ASSET_PREFIX}/:path*\`, destination: \`\${BACKEND}\${ASSET_PREFIX}/:path*\` },
+    ];
+  },
+};
 
-  writeFileSync(
-    resolve(dir, ".env.local.example"),
-    `NEXT_PUBLIC_BACKEND_URL=${siteUrl}\n`,
-  );
+export default config;
+`
+    : `import type { NextConfig } from "next";
+
+// Separate-origins mode: backend runs at http://localhost:3000, frontend here.
+// Switch to single-origin by setting APOLLO_ASSET_PREFIX in apps/backend/.env.local
+// and adding rewrites() — see this monorepo's README for the recipe.
+const config: NextConfig = {
+  reactStrictMode: true,
+};
+
+export default config;
+`;
+  writeFileSync(resolve(dir, "next.config.ts"), nextConfigContent);
+
+  const envLocalLines = assetPrefix
+    ? [
+        `# Internal backend URL (used by Next.js rewrites — not exposed to browser)`,
+        `BACKEND_INTERNAL_URL=${backendInternalUrl}`,
+        `# Mirror of backend's APOLLO_ASSET_PREFIX`,
+        `NEXT_PUBLIC_APOLLO_ASSET_PREFIX=${assetPrefix}`,
+        "",
+      ]
+    : [
+        `# Public URL of the backend (used by your client code)`,
+        `NEXT_PUBLIC_BACKEND_URL=${siteUrl}`,
+        "",
+      ];
+  writeFileSync(resolve(dir, ".env.local.example"), envLocalLines.join("\n"));
 
   writeFileSync(
     resolve(dir, "src/app/layout.tsx"),
@@ -414,7 +533,7 @@ function writeFrontendApp(targetDir, frontendName, siteUrl) {
 
   writeFileSync(
     resolve(dir, "src/app/page.tsx"),
-    `export default function Page() {\n  return (\n    <main style={{ padding: 40, fontFamily: "system-ui" }}>\n      <h1>Frontend</h1>\n      <p>Backend: <code>{process.env.NEXT_PUBLIC_BACKEND_URL}</code></p>\n    </main>\n  );\n}\n`,
+    `export default function Page() {\n  return (\n    <main style={{ padding: 40, fontFamily: "system-ui" }}>\n      <h1>Frontend</h1>\n      <p>\n        Admin: <a href="/admin">/admin</a>\n      </p>\n    </main>\n  );\n}\n`,
   );
 
   writeFileSync(
@@ -423,7 +542,54 @@ function writeFrontendApp(targetDir, frontendName, siteUrl) {
   );
 }
 
-function writeReadme(targetDir, dirName, frontendName) {
+function writeReadme(targetDir, dirName, frontendName, assetPrefix) {
+  const singleOrigin = !!assetPrefix;
+
+  const originSection = singleOrigin
+    ? `## Routing model — single origin
+
+Both apps share one public origin (the frontend). The frontend rewrites these
+paths to the backend so /_next/* doesn't collide:
+
+| Path                        | Goes to            |
+| --------------------------- | ------------------ |
+| \`/\` and other frontend routes | \`apps/frontend\`     |
+| \`/admin/*\`                  | \`apps/backend\`      |
+| \`/api/auth/*\`, \`/api/v1/*\`, \`/api/email/*\`, \`/api/cron\`, \`/api/health\`, \`/api/mcp\`, \`/api/admin/*\`, \`/api/editing-presence/*\` | \`apps/backend\` |
+| \`/uploads/*\`                | \`apps/backend\` (media) |
+| \`${assetPrefix}/*\`              | \`apps/backend\` (chunks via \`APOLLO_ASSET_PREFIX\`) |
+
+The frontend MUST NOT define routes at \`/admin\`, \`/api/auth\`, \`/api/v1\`, etc.
+If you need your own API, namespace it under \`/api/internal/*\` or similar.
+
+To **disable** single-origin and run the backend on its own subdomain,
+delete \`APOLLO_ASSET_PREFIX\` from \`apps/backend/.env.local\` and remove the
+\`rewrites()\` block from \`apps/frontend/next.config.ts\`.
+
+### Known limitations
+
+- The backend's \`/_next/image\` (Next.js Image optimization endpoint) is **not**
+  rewritten — only \`/_next/static\` moves under \`APOLLO_ASSET_PREFIX\`. If your
+  backend admin uses \`<Image>\` to render \`/uploads/*\` media, those will fall
+  back to the frontend's image optimizer and 404. Apollo CMS's stock admin uses
+  plain \`<img>\` for uploaded media so this rarely matters; if you customize the
+  admin and need optimized images, switch to separate-origins mode or set
+  \`unoptimized\` on those \`<Image>\` instances.
+`
+    : `## Routing model — separate origins
+
+The two apps run on separate origins. Default ports:
+
+- Backend (apps/backend): http://localhost:3000
+- Frontend (apps/frontend): http://localhost:3001
+
+\`NEXT_PUBLIC_SITE_URL\` should point at whichever origin you treat as the
+public CMS URL (typically the backend). To switch to **single-origin** later,
+re-run the installer with \`--asset-prefix /cms-assets\` or set
+\`APOLLO_ASSET_PREFIX\` in \`apps/backend/.env.local\` and add the matching
+\`rewrites()\` block to \`apps/frontend/next.config.ts\`.
+`;
+
   const readme = `# ${dirName}
 
 Monorepo with a custom frontend and Apollo CMS as a git submodule backend.
@@ -447,6 +613,7 @@ pnpm backend:setup       # push schema + seed apollo-cms
 pnpm dev                 # runs frontend (3001) + backend (3000) in parallel
 \`\`\`
 
+${originSection}
 ## Updating the backend
 
 Apollo CMS is tracked as a git submodule. Pull the latest:
@@ -490,9 +657,13 @@ async function main() {
 
   // ── Step 2: Gather env ──
   step(2, "Configuring environment");
-  const { dbUrl, siteUrl, locale } = await gatherEnv(flags);
+  const assetPrefix = normalizeAssetPrefix(flags.assetPrefix);
+  const singleOrigin = !!assetPrefix;
+  const { dbUrl, siteUrl, locale } = await gatherEnv(flags, { singleOrigin });
   const authSecret = randomBytes(48).toString("base64");
+  const backendInternalUrl = "http://localhost:3000";
   success(`Frontend pkg name: ${frontendName}`);
+  success(`Asset prefix: ${assetPrefix || "(disabled — separate origins)"}`);
 
   // ── Step 3: Scaffold root ──
   step(3, "Scaffolding monorepo root");
@@ -501,8 +672,8 @@ async function main() {
   writeRootPackageJson(targetDir, dirName);
   writePnpmWorkspace(targetDir);
   writeRootGitignore(targetDir);
-  writeRootEnv(targetDir, { dbUrl, siteUrl, locale, authSecret });
-  writeReadme(targetDir, dirName, frontendName);
+  writeRootEnv(targetDir, { dbUrl, siteUrl, locale, authSecret, assetPrefix, backendInternalUrl });
+  writeReadme(targetDir, dirName, frontendName, assetPrefix);
   success("package.json, pnpm-workspace.yaml, .gitignore, .env.local, README.md");
 
   // ── Step 4: git init ──
@@ -512,7 +683,7 @@ async function main() {
 
   // ── Step 5: Frontend skeleton ──
   step(5, "Creating frontend app");
-  writeFrontendApp(targetDir, frontendName, siteUrl);
+  writeFrontendApp(targetDir, frontendName, siteUrl, assetPrefix, backendInternalUrl);
   success(`apps/frontend (${frontendName})`);
 
   // ── Step 6: Backend submodule ──
@@ -537,15 +708,17 @@ async function main() {
     }
 
     // Mirror env to backend
-    const backendEnv = [
+    const backendEnvLines = [
       `DATABASE_URL=${dbUrl}`,
       `APOLLO_SECRET=${authSecret}`,
-      `BETTER_AUTH_SECRET=${authSecret}`,
       `NEXT_PUBLIC_SITE_URL=${siteUrl}`,
       `NEXT_PUBLIC_DEFAULT_LOCALE=${locale}`,
-      "",
-    ].join("\n");
-    writeFileSync(resolve(targetDir, BACKEND_PATH, ".env.local"), backendEnv);
+    ];
+    if (assetPrefix) {
+      backendEnvLines.push(`APOLLO_ASSET_PREFIX=${assetPrefix}`);
+    }
+    backendEnvLines.push("");
+    writeFileSync(resolve(targetDir, BACKEND_PATH, ".env.local"), backendEnvLines.join("\n"));
     success("apps/backend/.env.local");
   }
 

package/package.json

@@ -1,8 +1,10 @@
 {
   "name": "create-apollo-monorepo",
-  "version": "0.1.0",
-  "description": "Scaffold a monorepo with a frontend app and Apollo CMS as a git submodule backend",
-  "bin": "./index.mjs",
+  "version": "0.2.0",
+  "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"