agentic-dev/apps/cms/AGENTS.md

AGENTS.md — apps/cms

Thin shell hosting the Payload CMS admin panel via Next.js. All CMS configuration (collections, globals, hooks, access control, payload.config.ts) lives in @repo/core-cms, which aggregates collections from feature packages.

Purpose

This app exists solely to serve the Payload Admin UI. It contains no custom CMS code beyond Next.js routing boilerplate. All business knowledge lives in feature packages (@repo/auth, etc.), which export their collections/globals via subpath exports (.../cms). @repo/core-cms composes them into a single Payload config.

Port: 3001

docker compose up -d postgres    # Start PostgreSQL on port 5432
pnpm dev --filter @repo/cms      # http://localhost:3001/admin

Key Files

File	Purpose
next.config.mjs	Minimal config wrapped with withPayload() from @payloadcms/next
tsconfig.json	TypeScript config with @payload-config path alias
src/app/(payload)/layout.tsx	Auto-generated Payload root layout (DO NOT MODIFY)
src/app/(payload)/admin/[[...segments]]/page.tsx	Auto-generated catch-all admin page (DO NOT MODIFY)
src/app/(payload)/importMap.js	Auto-generated Payload import map (DO NOT MODIFY)

Hard Rules

• NEVER add collections, globals, or hooks in this app — put them in feature packages
• NEVER create custom CMS logic here — use @repo/core-cms
• NEVER modify auto-generated files under src/app/(payload)/
• All Payload config changes go in packages/core-cms/src/payload.config.ts

@payload-config Alias

The tsconfig.json points to @repo/core-cms:

{
  "compilerOptions": {
    "paths": {
      "@payload-config": ["../../packages/core-cms/src/payload.config.ts"]
    }
  }
}

When Payload imports @payload-config, it resolves to the composed config from @repo/core-cms, which in turn imports feature collections.

Composition flow

Feature (@repo/auth)
  └─ src/integrations/cms/collections/users.ts
      └─ exported as ./cms

Core CMS (@repo/core-cms)
  └─ src/payload.config.ts
      imports all feature /cms exports
      calls buildConfig({ collections, globals })

This app (@repo/cms)
  └─ src/app/(payload)/layout.tsx
      loads config from @payload-config
      Payload CLI auto-generates admin routes

Type Generation

After adding/modifying collections in any feature's /cms folder:

cd apps/cms && pnpm generate:types
# Regenerates packages/core-cms/src/generated-types.ts

Dependencies

Dependency	Purpose
@repo/core-cms	Payload config + buildConfig
@payloadcms/next	Next.js integration for Payload
payload	Payload CMS core
next	Next.js 15 framework
sharp	Image processing

Cross-References

• Feature collections: each feature's src/integrations/cms/ folder
• CMS composition: packages/core-cms/AGENTS.md