create-apollo-monorepo 0.3.1 → 0.5.1

package/README.md

@@ -44,19 +44,29 @@ collide:
 | Browser path                         | Goes to              |
 | ------------------------------------ | -------------------- |
 | `/`, your custom routes              | `apps/frontend`      |
-| `/admin/*`                           | `apps/backend`       |
+| `/admin/*`                           | `apps/backend` (admin pages **and** their JS chunks) |
 | `/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.
+Apollo CMS reads `APOLLO_ASSET_PREFIX` (default `/admin`) and serves its built
+JS under `<prefix>/_next/static/`. Because the prefix coincides with the admin
+path, a single `/admin/:path*` rewrite covers both pages and chunks — no
+separate asset rewrite is emitted. The frontend **must not** define routes at
+`/admin`, `/api/auth`, `/api/v1`, etc.
+
+You can override the prefix:
+
+```bash
+npx create-apollo-monorepo my-app --admin-prefix /cms
+```
+
+When the prefix is anything other than `/admin`, the scaffold also emits a
+matching `<prefix>/:path*` rewrite for backend chunks.
 
 ### Separate origins (fallback)
 
-Pass `--asset-prefix none` (or `off`/`false`/`disabled`) to skip the rewrite
+Pass `--admin-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`).
@@ -71,7 +81,7 @@ subdomains (e.g. `cms.example.com` + `example.com`).
 | `-d, --db <url>`           | _(prompted)_                            | `DATABASE_URL` for backend           |
 | `-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 |
+| `--admin-prefix <path>`    | `/admin`                                | Single-origin admin/asset namespace; `none` to disable. Alias: `--asset-prefix` |
 | `--skip-install`           | off                                     | Don't run `pnpm install`             |
 | `--skip-submodule`         | off                                     | Don't add the git submodule          |
 | `-h, --help`               | —                                       | Show help                            |

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,10 +326,17 @@ 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",
@@ -371,7 +389,7 @@ function writeRootPackageJson(targetDir, dirName) {
 function writePnpmWorkspace(targetDir) {
   writeFileSync(
     resolve(targetDir, "pnpm-workspace.yaml"),
-    "packages:\n  - 'apps/*'\n",
+    "packages:\n  - 'apps/*'\n  - 'apps/cms-plugins/*'\n",
   );
 }
 
@@ -393,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/*,",
@@ -403,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 = [
@@ -413,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}`,
       "",
@@ -439,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 });
@@ -500,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*\` },
@@ -528,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}    ];
   },
 };
 
@@ -549,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}`,
         "",
       ]
     : [
@@ -594,8 +627,202 @@ export default config;
   );
 }
 
-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
@@ -609,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.
@@ -637,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\`.
 `;
@@ -666,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:
@@ -690,7 +950,7 @@ Two Vercel projects, one repo. Each project picks up its own Root Directory.
 
 - **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\`
+- **Build Command**: \`cd ../.. && pnpm install --frozen-lockfile && pnpm cms-plugins:build && cp -r ../cms-plugins/* apps/backend/plugins/ 2>/dev/null || true && 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**:
@@ -699,14 +959,16 @@ Two Vercel projects, one repo. Each project picks up its own Root Directory.
   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=${assetPrefix}` : "# APOLLO_ASSET_PREFIX=/cms-assets   # only when single-origin"}
+  ${singleOrigin ? `APOLLO_ASSET_PREFIX=${adminPrefix}` : "# APOLLO_ASSET_PREFIX=/admin   # only when single-origin"}
   CRON_SECRET=<random>                          # protects /api/cron
+  APOLLO_EXTRA_PLUGINS_DIR=./plugins             # picks up copied cms-plugins (see Build Command)
   # 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).
+- **About the \`cp\` step**: Turbopack rejects \`outputFileTracingIncludes\` globs that walk above the project root, so the Build Command copies built \`apps/cms-plugins/*/dist\` into \`apps/backend/plugins/\` before \`next build\`. NFT then traces them normally as if they were built-in plugins. Locally this isn't needed because \`APOLLO_EXTRA_PLUGINS_DIR=../cms-plugins\` reads them directly.
 
 ### 2) Frontend project
 
@@ -719,7 +981,7 @@ Two Vercel projects, one repo. Each project picks up its own Root Directory.
   \`\`\`
   NEXT_PUBLIC_SITE_URL=https://yourdomain.com
 ${singleOrigin
-  ? `  BACKEND_INTERNAL_URL=https://<your-backend>.vercel.app\n  NEXT_PUBLIC_APOLLO_ASSET_PREFIX=${assetPrefix}`
+  ? `  BACKEND_INTERNAL_URL=https://<your-backend>.vercel.app`
   : `  NEXT_PUBLIC_BACKEND_URL=https://<your-backend>.vercel.app`
 }
   \`\`\`
@@ -774,13 +1036,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");
@@ -789,8 +1054,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 ──
@@ -800,9 +1065,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)");
@@ -828,11 +1099,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.3.1",
+  "version": "0.5.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"