create-apollo-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

npx create-apollo-monorepo thamc-new

With flags:

npx create-apollo-monorepo thamc-new \
  --frontend-name "@thamc/frontend" \
  --db "postgresql://user:pass@localhost:5432/thamc" \
  --url "http://localhost:3000" \
  --locale th

Result

thamc-new/
├── apps/
│   ├── frontend/          ← @thamc/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/cron, /api/health, /api/mcp, /api/editing-presence/* | apps/backend | | /uploads/* | apps/backend (media) | | /monitoring | apps/backend (Sentry tunnel, no-op without DSN) |

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:

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 --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

cd thamc-new
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

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.