create-apollo-monorepo 0.2.0 → 0.5.0

package/index.mjs

@@ -56,7 +56,12 @@ ${COLORS.bold}Flags:${COLORS.reset}
   -d, --db <url>               DATABASE_URL for backend
   -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)
+      --admin-prefix <path>    Backend prefix in single-origin mode — sets Next.js
+                               adminPrefix on the backend AND the path the frontend
+                               rewrites to it. Defaults to /admin so backend chunks
+                               sit alongside admin pages under one rewrite.
+                               Pass "none" to disable single-origin (separate origins).
+                               Alias: --asset-prefix
       --skip-install           Skip dependency installation
       --skip-submodule         Skip git submodule add (you'll add it later)
   -h, --help                   Show this help message
@@ -122,7 +127,7 @@ function parseArgs(argv) {
     db: null,
     url: null,
     locale: null,
-    assetPrefix: "/cms-assets",
+    adminPrefix: "/admin",
     skipInstall: false,
     skipSubmodule: false,
     help: false,
@@ -157,8 +162,9 @@ function parseArgs(argv) {
       case "--locale":
         flags.locale = args[++i];
         break;
-      case "--asset-prefix":
-        flags.assetPrefix = args[++i];
+      case "--admin-prefix":
+      case "--asset-prefix": // legacy alias
+        flags.adminPrefix = args[++i];
         break;
       case "--skip-install":
         flags.skipInstall = true;
@@ -195,19 +201,24 @@ function isValidLocale(code) {
   return /^[a-z]{2,5}$/i.test(code);
 }
 
-// Normalize an asset prefix:
+// Normalize the admin/asset prefix:
 //  - empty string / "none" / "off" / "false"  → "" (single-origin disabled, fallback to separate origins)
 //  - "/foo"                                    → "/foo"
 //  - "foo"                                     → "/foo"
 //  - "/foo/"                                   → "/foo"
-function normalizeAssetPrefix(value) {
+//
+// The same value drives both Next.js `adminPrefix` on the backend AND the
+// path the frontend rewrites at. Defaulting to "/admin" makes backend chunks
+// sit under the admin path so a single `/admin/:path*` rewrite covers
+// everything (admin pages + their JS chunks).
+function normalizeAdminPrefix(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.`);
+    fatal(`Invalid --admin-prefix: ${value}\n  Use a path like /admin, or "none" to disable single-origin.`);
   }
   return p;
 }
@@ -315,25 +326,70 @@ function writeRootPackageJson(targetDir, dirName) {
     private: true,
     description: `${dirName} monorepo (frontend + apollo-cms backend submodule)`,
     scripts: {
-      dev: "pnpm -r --parallel dev",
+      dev: "pnpm cms-plugins:build && pnpm -r --parallel dev",
       "dev:frontend": "pnpm --filter ./apps/frontend dev",
-      "dev:backend": "pnpm --filter ./apps/backend dev",
-      build: "pnpm -r build",
+      "dev:backend": "pnpm cms-plugins:build && pnpm --filter ./apps/backend dev",
+      // cms-plugins must compile to dist/ before the backend boots, otherwise
+      // the loader falls back to index.ts which only works under Bun and
+      // emits a warning. Build them sequentially: cms-plugins → backend → frontend.
+      build:
+        "pnpm cms-plugins:build && pnpm --filter ./apps/backend build && pnpm --filter ./apps/frontend build",
+      "cms-plugins:build":
+        "pnpm --filter './apps/cms-plugins/*' --parallel --if-present build",
+      "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",
       "backend:setup": "pnpm --filter ./apps/backend setup",
     },
     engines: { node: ">=20", pnpm: ">=9" },
-    packageManager: "pnpm@9.0.0",
+    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: [
+        "@swc/core",
+        "@swc/core-darwin-arm64",
+        "@swc/core-darwin-x64",
+        "@swc/core-linux-arm64-gnu",
+        "@swc/core-linux-x64-gnu",
+        "esbuild",
+        "msw",
+        "sharp",
+        "unrs-resolver",
+        "@rolldown/binding-darwin-arm64",
+        "@rolldown/binding-linux-x64-gnu",
+        "@rolldown/binding-linux-arm64-gnu",
+        "better-sqlite3",
+        "core-js",
+        "core-js-pure",
+      ],
+    },
   };
   writeFileSync(resolve(targetDir, "package.json"), JSON.stringify(pkg, null, 2) + "\n");
+
+  // .npmrc — keep peer-deps lenient and hoist esbuild's platform binaries so
+  // its postinstall version check resolves the correct one across nested
+  // dependency trees.
+  writeFileSync(
+    resolve(targetDir, ".npmrc"),
+    [
+      "auto-install-peers=true",
+      "strict-peer-dependencies=false",
+      "public-hoist-pattern[]=*esbuild*",
+      "public-hoist-pattern[]=*types*",
+      "shell-emulator=true",
+      "",
+    ].join("\n"),
+  );
 }
 
 function writePnpmWorkspace(targetDir) {
   writeFileSync(
     resolve(targetDir, "pnpm-workspace.yaml"),
-    "packages:\n  - 'apps/*'\n",
+    "packages:\n  - 'apps/*'\n  - 'apps/cms-plugins/*'\n",
   );
 }
 
@@ -355,8 +411,8 @@ function writeRootGitignore(targetDir) {
   writeFileSync(resolve(targetDir, ".gitignore"), ignore);
 }
 
-function writeRootEnv(targetDir, { dbUrl, siteUrl, locale, authSecret, assetPrefix, backendInternalUrl }) {
-  const header = assetPrefix
+function writeRootEnv(targetDir, { dbUrl, siteUrl, locale, authSecret, cronSecret, adminPrefix, backendInternalUrl }) {
+  const header = adminPrefix
     ? [
         "# Single-origin monorepo dev env",
         "# Public origin = frontend (apps/frontend on :3001). Frontend rewrites /admin/*,",
@@ -365,8 +421,8 @@ function writeRootEnv(targetDir, { dbUrl, siteUrl, locale, authSecret, assetPref
     : [
         "# 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.",
+        "# To switch to single-origin: set APOLLO_ASSET_PREFIX (default: /admin) and",
+        "# BACKEND_INTERNAL_URL, then add rewrites() to apps/frontend/next.config.ts.",
       ];
 
   const lines = [
@@ -375,23 +431,32 @@ function writeRootEnv(targetDir, { dbUrl, siteUrl, locale, authSecret, assetPref
     "# ── Shared (consumed by both apps) ───────────────────────────────",
     `DATABASE_URL=${dbUrl}`,
     `APOLLO_SECRET=${authSecret}`,
+    `CRON_SECRET=${cronSecret}`,
     `NEXT_PUBLIC_SITE_URL=${siteUrl}`,
     `NEXT_PUBLIC_DEFAULT_LOCALE=${locale}`,
     "",
   ];
 
-  if (assetPrefix) {
+  if (adminPrefix) {
     lines.push(
       "# ── Backend (apps/backend) ───────────────────────────────────────",
-      `APOLLO_ASSET_PREFIX=${assetPrefix}`,
+      "# 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) ─────────────────────────────────────",
       `BACKEND_INTERNAL_URL=${backendInternalUrl}`,
-      `NEXT_PUBLIC_APOLLO_ASSET_PREFIX=${assetPrefix}`,
       "",
     );
   } 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}`,
       "",
@@ -401,7 +466,7 @@ function writeRootEnv(targetDir, { dbUrl, siteUrl, locale, authSecret, assetPref
   writeFileSync(resolve(targetDir, ".env.local"), lines.join("\n"));
 }
 
-function writeFrontendApp(targetDir, frontendName, siteUrl, assetPrefix, backendInternalUrl) {
+function writeFrontendApp(targetDir, frontendName, siteUrl, adminPrefix, backendInternalUrl) {
   const dir = resolve(targetDir, FRONTEND_PATH);
   mkdirSync(dir, { recursive: true });
   mkdirSync(resolve(dir, "src/app"), { recursive: true });
@@ -462,20 +527,30 @@ function writeFrontendApp(targetDir, frontendName, siteUrl, assetPrefix, backend
   );
 
   // Frontend Next.js config:
-  //  - Single-origin mode (assetPrefix set): rewrite all backend paths.
-  //  - Separate-origins mode (assetPrefix empty): no rewrites; the two apps
+  //  - Single-origin mode (adminPrefix set): rewrite backend paths to apps/backend.
+  //    The chosen prefix is baked into the file at scaffold time — no
+  //    NEXT_PUBLIC_* env mirror, just `BACKEND_INTERNAL_URL` for the proxy target.
+  //  - Separate-origins mode (adminPrefix empty): no rewrites; the two apps
   //    are reachable on their own ports/subdomains.
-  const nextConfigContent = assetPrefix
+  //
+  // When adminPrefix === "/admin" the explicit admin rewrite already covers
+  // backend chunks served under /admin/_next/static (via APOLLO_ASSET_PREFIX
+  // on the backend), so no separate prefix rewrite is emitted. For any other
+  // prefix the script also emits a rewrite for the assets path.
+  const isDefaultAdmin = adminPrefix === "/admin";
+  const extraPrefixRewrite = adminPrefix && !isDefaultAdmin
+    ? `      // Backend's namespaced Next.js chunks (set via APOLLO_ASSET_PREFIX)\n      { source: "${adminPrefix}/:path*", destination: \`\${BACKEND}${adminPrefix}/:path*\` },\n`
+    : "";
+  const nextConfigContent = adminPrefix
     ? `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
+      // Apollo CMS admin UI (and its chunks when APOLLO_ASSET_PREFIX is /admin)
       { 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*\` },
@@ -490,9 +565,7 @@ const config: NextConfig = {
       { 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*\` },
-    ];
+${extraPrefixRewrite}    ];
   },
 };
 
@@ -511,12 +584,10 @@ export default config;
 `;
   writeFileSync(resolve(dir, "next.config.ts"), nextConfigContent);
 
-  const envLocalLines = assetPrefix
+  const envLocalLines = adminPrefix
     ? [
         `# 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}`,
         "",
       ]
     : [
@@ -540,10 +611,218 @@ export default config;
     resolve(dir, ".gitignore"),
     ["node_modules", ".next", "dist", ".env.local", ""].join("\n"),
   );
+
+  // Vercel project config for the frontend. Skip cron + region pinning is
+  // optional; configure Root Directory + "Include all submodules" in the
+  // Vercel UI when linking the project.
+  const vercelJson = {
+    $schema: "https://openapi.vercel.sh/vercel.json",
+    regions: ["sin1"],
+  };
+  writeFileSync(resolve(dir, "vercel.json"), JSON.stringify(vercelJson, null, 2) + "\n");
+
+  writeFileSync(
+    resolve(dir, ".vercelignore"),
+    ["node_modules", ".next", ".env.local", ""].join("\n"),
+  );
 }
 
-function writeReadme(targetDir, dirName, frontendName, assetPrefix) {
-  const singleOrigin = !!assetPrefix;
+// ─── Custom plugins scaffold ─────────────────────────────────────────────────
+
+function writeExampleCmsPlugin(targetDir, dirName) {
+  const slug = "example-plugin";
+  const pkgName = `@${dirName}/cms-${slug}`;
+  const pluginDir = resolve(targetDir, "apps/cms-plugins", slug);
+  mkdirSync(pluginDir, { recursive: true });
+
+  const manifest = {
+    name: slug,
+    version: "0.1.0",
+    title: "Example Plugin",
+    description: "Project-specific plugin scaffold for the monorepo",
+    author: "you",
+  };
+  writeFileSync(resolve(pluginDir, "plugin.json"), JSON.stringify(manifest, null, 2) + "\n");
+
+  const pkg = {
+    name: pkgName,
+    version: "0.1.0",
+    private: true,
+    type: "module",
+    exports: {
+      "./server": "./dist/server.mjs",
+    },
+    scripts: {
+      build: "node ./build.mjs",
+    },
+    devDependencies: {
+      esbuild: "^0.24.0",
+    },
+  };
+  writeFileSync(resolve(pluginDir, "package.json"), JSON.stringify(pkg, null, 2) + "\n");
+
+  // Tiny zero-config build: bundle index.ts → dist/server.mjs as ESM Node.
+  const buildMjs = `import { build } from "esbuild";
+
+await build({
+  entryPoints: ["./index.ts"],
+  outfile: "./dist/server.mjs",
+  format: "esm",
+  platform: "node",
+  target: "node20",
+  bundle: true,
+  // Mark Apollo CMS internals as external — they're provided by the host
+  // backend at runtime via the loader's dynamic import().
+  external: ["@/*", "next", "react", "react-dom"],
+  logLevel: "info",
+});
+`;
+  writeFileSync(resolve(pluginDir, "build.mjs"), buildMjs);
+
+  const tsconfig = {
+    compilerOptions: {
+      target: "ES2022",
+      module: "esnext",
+      moduleResolution: "bundler",
+      esModuleInterop: true,
+      skipLibCheck: true,
+      strict: true,
+      noEmit: true,
+      jsx: "preserve",
+      // Resolve `@/...` against the apollo-cms backend so plugin code can
+      // type-check against the real types from the submodule.
+      baseUrl: "../../backend",
+      paths: { "@/*": ["src/*"] },
+    },
+    include: ["**/*.ts", "**/*.tsx"],
+    exclude: ["dist", "node_modules"],
+  };
+  writeFileSync(resolve(pluginDir, "tsconfig.json"), JSON.stringify(tsconfig, null, 2) + "\n");
+
+  const indexTs = `// Example Apollo CMS plugin — runs inside apps/backend at boot.
+//
+// The plugin loader picks up this file via package.json#exports["./server"]
+// → dist/server.mjs (built by \`pnpm cms-plugins:build\`).
+//
+// In dev under Bun the loader can also import index.ts directly (with a
+// warning); in production (Vercel / next start) the dist file is required.
+
+import type { PluginDefinition } from "@/lib/plugins/types";
+
+const plugin: PluginDefinition = {
+  // Register hooks — see apollo-cms's HOOKS export for the full surface.
+  registerHooks(hooks, HOOKS) {
+    hooks.action(HOOKS.auth.afterLogin, async (ctx) => {
+      console.log("[example-plugin] login:", ctx.authUserId);
+    });
+  },
+
+  // Register UI slots — inject components into the admin shell.
+  // registerUiSlots(slots) { ... }
+
+  // Register API routes under /api/v1/<your-route>.
+  // registerApiRoutes(router) { ... }
+};
+
+export default plugin;
+`;
+  writeFileSync(resolve(pluginDir, "index.ts"), indexTs);
+
+  writeFileSync(
+    resolve(pluginDir, ".gitignore"),
+    ["node_modules", "dist", ""].join("\n"),
+  );
+
+  const readme = `# ${pkgName}
+
+Project-specific plugin loaded by the apollo-cms backend via
+\`APOLLO_EXTRA_PLUGINS_DIR\`.
+
+## Develop
+
+Run from the **monorepo root** (not this folder):
+
+\`\`\`bash
+pnpm dev                     # builds plugins + starts backend & frontend
+pnpm cms-plugins:build       # rebuild after editing
+\`\`\`
+
+## Author a new hook
+
+Open \`index.ts\` and add to \`registerHooks\`. The full hook surface lives in
+\`apps/backend/src/lib/plugins/hook-registry.ts\`.
+
+## Add another plugin
+
+\`\`\`bash
+pnpm cms-plugin:new my-plugin
+\`\`\`
+`;
+  writeFileSync(resolve(pluginDir, "README.md"), readme);
+}
+
+function writeNewCmsPluginScript(targetDir) {
+  const scriptsDir = resolve(targetDir, "scripts");
+  mkdirSync(scriptsDir, { recursive: true });
+
+  const script = `#!/usr/bin/env node
+// Scaffold a new project-specific apollo-cms plugin under apps/cms-plugins/<slug>.
+// Usage: pnpm cms-plugin:new <slug>
+
+import { cpSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const monorepoRoot = resolve(__dirname, "..");
+const pluginsRoot = resolve(monorepoRoot, "apps/cms-plugins");
+const template = resolve(pluginsRoot, "example-plugin");
+
+const slug = (process.argv[2] ?? "").trim();
+if (!slug) {
+  console.error("Usage: pnpm cms-plugin:new <slug>");
+  process.exit(1);
+}
+if (!/^[a-z][a-z0-9-]*$/.test(slug)) {
+  console.error(\`Invalid slug "\${slug}" — use kebab-case (lowercase, digits, hyphens).\`);
+  process.exit(1);
+}
+if (!existsSync(template)) {
+  console.error(\`Template not found: \${template}\\nRecreate apps/cms-plugins/example-plugin or restore from a fresh \\\`npx create-apollo-monorepo\\\` scaffold.\`);
+  process.exit(1);
+}
+
+const target = resolve(pluginsRoot, slug);
+if (existsSync(target)) {
+  console.error(\`Plugin already exists: \${target}\`);
+  process.exit(1);
+}
+
+cpSync(template, target, { recursive: true, filter: (src) => !/[\\\\\\/](node_modules|dist)([\\\\\\/]|$)/.test(src) });
+
+// Patch plugin.json
+const manifestPath = resolve(target, "plugin.json");
+const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
+manifest.name = slug;
+manifest.title = slug.replace(/-/g, " ").replace(/\\b\\w/g, (c) => c.toUpperCase());
+manifest.description = \`Project plugin: \${slug}\`;
+writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + "\\n");
+
+// Patch package.json
+const pkgPath = resolve(target, "package.json");
+const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+const rootPkg = JSON.parse(readFileSync(resolve(monorepoRoot, "package.json"), "utf-8"));
+pkg.name = \`@\${rootPkg.name}/cms-\${slug}\`;
+writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\\n");
+
+console.log(\`Created apps/cms-plugins/\${slug}\`);
+console.log(\`Run: pnpm install && pnpm cms-plugins:build && pnpm dev:backend\`);
+`;
+  writeFileSync(resolve(scriptsDir, "new-cms-plugin.mjs"), script);
+}
+
+function writeReadme(targetDir, dirName, frontendName, adminPrefix) {
+  const singleOrigin = !!adminPrefix;
 
   const originSection = singleOrigin
     ? `## Routing model — single origin
@@ -557,7 +836,7 @@ paths to the backend so /_next/* doesn't collide:
 | \`/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\`) |
+| \`${adminPrefix}/*\`              | \`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.
@@ -585,7 +864,7 @@ The two apps run on separate origins. Default ports:
 
 \`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
+re-run the installer with \`--admin-prefix /admin\` or set
 \`APOLLO_ASSET_PREFIX\` in \`apps/backend/.env.local\` and add the matching
 \`rewrites()\` block to \`apps/frontend/next.config.ts\`.
 `;
@@ -614,6 +893,39 @@ pnpm dev                 # runs frontend (3001) + backend (3000) in parallel
 \`\`\`
 
 ${originSection}
+## Custom plugins
+
+Project-specific plugins live in \`apps/cms-plugins/<slug>/\` and are loaded by
+the apollo-cms backend via \`APOLLO_EXTRA_PLUGINS_DIR=../cms-plugins\` (set
+automatically in \`apps/backend/.env.local\`). The submodule stays clean —
+\`pnpm backend:update\` won't conflict with your plugins.
+
+### Author a new plugin
+
+\`\`\`bash
+pnpm cms-plugin:new my-plugin
+pnpm install
+pnpm dev
+\`\`\`
+
+The scaffolder copies \`apps/cms-plugins/example-plugin/\` to
+\`apps/cms-plugins/my-plugin/\` and renames it. Edit \`index.ts\` to register
+hooks, UI slots, and API routes — see
+\`apps/backend/docs/plugin-system.md\` for the full surface.
+
+### Build pipeline
+
+\`pnpm dev\` and \`pnpm build\` run \`pnpm cms-plugins:build\` first to compile
+each plugin's \`index.ts\` → \`dist/server.mjs\` (via esbuild). The backend's
+plugin loader resolves \`dist/server.mjs\` in production; in dev under Bun it
+also accepts \`index.ts\` directly.
+
+### Slug collisions
+
+Built-in plugins under \`apps/backend/plugins/\` always win on slug collision.
+If you see *"Plugin slug collision"* in the backend logs, rename your plugin's
+folder + \`plugin.json#name\`.
+
 ## Updating the backend
 
 Apollo CMS is tracked as a git submodule. Pull the latest:
@@ -629,6 +941,71 @@ 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 on Vercel
+
+Two Vercel projects, one repo. Each project picks up its own Root Directory.
+
+### 1) Backend project
+
+- **Import** this repo into Vercel as a new project.
+- **Root Directory**: \`apps/backend\`
+- **Build Command**: \`cd ../.. && pnpm install --frozen-lockfile && pnpm --filter ./apps/backend build\`
+- **Install Command**: leave empty (handled in build)
+- **Settings → Git → Include all submodules: ON** (Vercel checks out an empty \`apps/backend\` otherwise)
+- **Environment variables**:
+  \`\`\`
+  DATABASE_URL=postgresql://…
+  APOLLO_SECRET=<openssl rand -hex 32>
+  NEXT_PUBLIC_SITE_URL=https://yourdomain.com   # the PUBLIC origin
+  NEXT_PUBLIC_DEFAULT_LOCALE=en
+  ${singleOrigin ? `APOLLO_ASSET_PREFIX=${adminPrefix}` : "# APOLLO_ASSET_PREFIX=/cms-assets   # only when single-origin"}
+  CRON_SECRET=<random>                          # protects /api/cron
+  # Storage on Vercel cannot use local FS — pick one:
+  # Vercel Blob:        BLOB_READ_WRITE_TOKEN=…
+  # S3 / R2 / Spaces:   S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY, S3_BUCKET, S3_REGION, S3_ENDPOINT
+  APOLLO_DISABLE_LOCAL_STORAGE=1
+  \`\`\`
+- **Cron**: \`apps/backend/vercel.json\` declares \`/api/cron\` on a 5-minute schedule (from apollo-cms upstream).
+
+### 2) Frontend project
+
+- **Import the same repo** as a separate Vercel project.
+- **Root Directory**: \`apps/frontend\`
+- **Build Command**: \`cd ../.. && pnpm install --frozen-lockfile && pnpm --filter ./apps/frontend build\`
+- **Install Command**: leave empty
+- **Settings → Git → Include all submodules: ON**
+- **Environment variables**:
+  \`\`\`
+  NEXT_PUBLIC_SITE_URL=https://yourdomain.com
+${singleOrigin
+  ? `  BACKEND_INTERNAL_URL=https://<your-backend>.vercel.app`
+  : `  NEXT_PUBLIC_BACKEND_URL=https://<your-backend>.vercel.app`
+}
+  \`\`\`
+
+### 3) Custom domain
+
+Attach \`yourdomain.com\` to the **frontend** project${singleOrigin ? " (in single-origin mode it's the public entry point)" : ""}. The backend stays on its \`*.vercel.app\` URL${singleOrigin ? " — that's what the rewrite proxies to" : ""}.
+
+### 4) Skip duplicate builds (optional)
+
+Each push triggers both projects to rebuild. Add an **Ignored Build Step** in
+each project's Settings → Git:
+
+- **Backend**: \`git diff HEAD^ HEAD --quiet -- apps/backend\` (exits 0 → skip build)
+- **Frontend**: \`git diff HEAD^ HEAD --quiet -- apps/frontend\`
+
+### Gotchas
+
+- **Submodule must be initialized** on Vercel — the "Include all submodules"
+  toggle is the most common reason builds fail with a missing \`apps/backend\`.
+- **OAuth callbacks** for email providers must use the public domain:
+  \`https://yourdomain.com/api/email/oauth/callback\`.${singleOrigin ? " The frontend rewrite forwards it to the backend." : ""}
+- **Cron** runs on the backend project only. Vercel sends \`Authorization:
+  Bearer $CRON_SECRET\` automatically when \`CRON_SECRET\` is set.${singleOrigin ? `
+- **Better Auth** uses \`trustedProxyHeaders: true\` so the rewrite proxy's
+  \`x-forwarded-host\` lands cookies at the public origin without extra config.` : ""}
 `;
   writeFileSync(resolve(targetDir, "README.md"), readme);
 }
@@ -657,13 +1034,16 @@ async function main() {
 
   // ── Step 2: Gather env ──
   step(2, "Configuring environment");
-  const assetPrefix = normalizeAssetPrefix(flags.assetPrefix);
-  const singleOrigin = !!assetPrefix;
+  const adminPrefix =normalizeAdminPrefix(flags.adminPrefix);
+  const singleOrigin = !!adminPrefix;
   const { dbUrl, siteUrl, locale } = await gatherEnv(flags, { singleOrigin });
   const authSecret = randomBytes(48).toString("base64");
+  // 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";
   success(`Frontend pkg name: ${frontendName}`);
-  success(`Asset prefix: ${assetPrefix || "(disabled — separate origins)"}`);
+  success(`Asset prefix: ${adminPrefix || "(disabled — separate origins)"}`);
 
   // ── Step 3: Scaffold root ──
   step(3, "Scaffolding monorepo root");
@@ -672,8 +1052,8 @@ async function main() {
   writeRootPackageJson(targetDir, dirName);
   writePnpmWorkspace(targetDir);
   writeRootGitignore(targetDir);
-  writeRootEnv(targetDir, { dbUrl, siteUrl, locale, authSecret, assetPrefix, backendInternalUrl });
-  writeReadme(targetDir, dirName, frontendName, assetPrefix);
+  writeRootEnv(targetDir, { dbUrl, siteUrl, locale, authSecret, cronSecret, adminPrefix, backendInternalUrl });
+  writeReadme(targetDir, dirName, frontendName, adminPrefix);
   success("package.json, pnpm-workspace.yaml, .gitignore, .env.local, README.md");
 
   // ── Step 4: git init ──
@@ -683,9 +1063,15 @@ async function main() {
 
   // ── Step 5: Frontend skeleton ──
   step(5, "Creating frontend app");
-  writeFrontendApp(targetDir, frontendName, siteUrl, assetPrefix, backendInternalUrl);
+  writeFrontendApp(targetDir, frontendName, siteUrl, adminPrefix, backendInternalUrl);
   success(`apps/frontend (${frontendName})`);
 
+  // ── Step 5b: Custom plugins workspace + example ──
+  step("5b", "Scaffolding apps/cms-plugins/example-plugin");
+  writeExampleCmsPlugin(targetDir, dirName);
+  writeNewCmsPluginScript(targetDir);
+  success("apps/cms-plugins/example-plugin + scripts/new-cms-plugin.mjs");
+
   // ── Step 6: Backend submodule ──
   if (flags.skipSubmodule) {
     step(6, "Skipping git submodule (--skip-submodule)");
@@ -711,11 +1097,13 @@ async function main() {
     const backendEnvLines = [
       `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`,
     ];
-    if (assetPrefix) {
-      backendEnvLines.push(`APOLLO_ASSET_PREFIX=${assetPrefix}`);
+    if (adminPrefix) {
+      backendEnvLines.push(`APOLLO_ASSET_PREFIX=${adminPrefix}`);
     }
     backendEnvLines.push("");
     writeFileSync(resolve(targetDir, BACKEND_PATH, ".env.local"), backendEnvLines.join("\n"));

package/package.json

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