create-apollo-suite-monorepo 1.0.1

package/README.md

@@ -0,0 +1,161 @@
+# create-apollo-suite-monorepo
+
+Scaffold a pnpm monorepo where your custom frontend lives alongside Apollo CMS
+mounted as a **git submodule** backend (read-only — pull updates only).
+
+## Usage
+
+```bash
+npx create-apollo-suite-monorepo my-site
+```
+
+With flags:
+
+```bash
+npx create-apollo-suite-monorepo my-site \
+  --frontend-name "@my-site/frontend" \
+  --db "postgresql://user:pass@localhost:5432/my-site" \
+  --url "http://localhost:3000" \
+  --locale th
+```
+
+## Result
+
+```
+my-site/
+├── apps/
+│   ├── frontend/          ← @my-site/frontend (Next.js skeleton)
+│   └── backend/           ← git submodule → apollo-cms
+├── package.json           ← root workspace
+├── pnpm-workspace.yaml
+├── .env.local             ← shared dev env
+├── .gitmodules            ← submodule config
+└── .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` (admin pages **and** their JS chunks) |
+| `/api/auth/*`, `/api/v1/*`, `/api/admin/*`, `/api/email/*`, `/api/health`, `/api/mcp`, `/api/editing-presence/*` | `apps/backend` |
+| `/uploads/*`                         | `apps/backend` (media) |
+
+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-suite-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 `--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`).
+
+## Flags
+
+| Flag                       | Default                                 | Description                          |
+| -------------------------- | --------------------------------------- | ------------------------------------ |
+| `--frontend-name <name>`   | `@<dir>/frontend`                       | Frontend `package.json` name         |
+| `--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>`          | `:3001` single-origin / `:3000` separate | `NEXT_PUBLIC_SITE_URL`               |
+| `-l, --locale <code>`      | `en`                                    | `NEXT_PUBLIC_DEFAULT_LOCALE`         |
+| `--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                            |
+
+## After install
+
+```bash
+cd my-site
+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
+pnpm backend:update  # git submodule update --remote --merge apps/backend
+```
+
+Don't edit files inside `apps/backend` — open issues / PRs against the
+`apollo-cms` repository upstream.
+
+### Scaffolds created before v0.9.991
+
+Two entries were missing from older scaffolds, and `pnpm dev` fails during
+`plugins:build` without them:
+
+```
+error: Could not resolve: "ioredis"
+error: Could not resolve: "@opentelemetry/api"
+```
+
+`apps/backend/plugins/*` has to be listed in the root `pnpm-workspace.yaml`
+(apollo-cms's own workspace file is ignored once the submodule is a package of
+an outer workspace, so the built-in plugins' dependencies never install), and
+`@opentelemetry/api` has to be a root devDependency (bun's bundler resolves
+`next`'s guarded `require()` of this optional peer, which pnpm — unlike bun —
+does not install). Patch an existing scaffold with:
+
+```yaml
+# pnpm-workspace.yaml
+packages:
+  - 'apps/*'
+  - 'apps/cms-plugins/*'
+  - 'apps/backend/plugins/*'   # add this
+```
+
+```jsonc
+// package.json
+"devDependencies": {
+  "concurrently": "^9.0.0",
+  "@opentelemetry/api": "^1.9.0"   // add this
+}
+```
+
+then re-run `pnpm install`.
+
+## Deploying to production
+
+The scaffold pins `packageManager: "pnpm@11.0.0"` so Corepack picks the right
+pnpm. If your CI / deploy host installs pnpm separately, **make sure it's
+pnpm 11+** — pnpm 11 sets `strictDepBuilds: true` by default and reads the
+allow-list from `allowBuilds` in `pnpm-workspace.yaml`. pnpm 10 silently
+ignores `allowBuilds`; pnpm 11 silently ignores the deprecated
+`onlyBuiltDependencies`. Mixing the two leads to `sharp` (and `esbuild`,
+`@swc/core`, …) skipping their postinstalls, which surfaces at runtime as:
+
+```
+Failed to load external module sharp-<hash>:
+  Error: Cannot find module 'sharp-<hash>'
+```
+
+The scaffold's `pnpm-workspace.yaml` already lists the binaries Apollo CMS
+needs in `allowBuilds`. If you add a new native dep, append it there.