apps/cms -- Payload CMS Admin Shell

Purpose

THIN SHELL ONLY -- this app exists solely to serve the Payload CMS admin panel via Next.js. All CMS logic (collections, globals, hooks, access control, payload.config.ts) lives in @repo/cms-core. This app contains no custom CMS code beyond Next.js routing boilerplate that Payload generates automatically.

Port: 3001

pnpm dev --filter @repo/cms   # http://localhost:3001/admin

Requires PostgreSQL running first:

docker compose up -d postgres   # Starts PostgreSQL on port 5432

Hard Rules

NEVER add collections, globals, hooks, or access control in this app -- put them in @repo/cms-core
NEVER import from @repo/core/infrastructure
NEVER modify auto-generated files (marked with "THIS FILE WAS GENERATED AUTOMATICALLY BY PAYLOAD")
All CMS configuration changes go in packages/cms-core/

Key Files

File	Purpose
`next.config.mjs`	Next.js 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)/admin/[[...segments]]/not-found.tsx`	Auto-generated 404 page (DO NOT MODIFY)
`src/app/(payload)/importMap.js`	Auto-generated Payload import map (DO NOT MODIFY)
`src/app/(payload)/custom.scss`	Custom SCSS overrides for admin panel styling

@payload-config Alias

The tsconfig.json defines a path alias that points to the config in @repo/cms-core:

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

When Payload or auto-generated files import @payload-config, it resolves to packages/cms-core/src/payload.config.ts. This is how the thin shell delegates all configuration to @repo/cms-core.

next.config.mjs

The Next.js config is minimal -- just the withPayload wrapper:

import { withPayload } from "@payloadcms/next/withPayload";

/** @type {import('next').NextConfig} */
const nextConfig = {};

export default withPayload(nextConfig);

withPayload() adds the necessary webpack aliases, module resolution, and middleware for Payload to work within Next.js.

Auto-Generated Files

The files under src/app/(payload)/ are generated by Payload and should NOT be manually edited:

layout.tsx -- Wraps the admin panel with RootLayout from @payloadcms/next/layouts, injects config and importMap
admin/[[...segments]]/page.tsx -- Catch-all route that renders RootPage from @payloadcms/next/views
admin/[[...segments]]/not-found.tsx -- 404 handler using NotFoundPage from @payloadcms/next/views
importMap.js -- Maps Payload component paths for the admin UI

If you need to regenerate these files, Payload will do so automatically during dev/build.

Type Generation

To regenerate Payload TypeScript types after changing collections/globals:

cd apps/cms && pnpm generate:types
# Equivalent to: payload generate:types
# Output goes to: packages/cms-core/src/payload-types.ts

Dependencies

Dependency	Purpose
`@repo/cms-core`	All Payload configuration (collections, globals, hooks, config)
`@payloadcms/next`	Next.js integration for Payload (withPayload, admin UI views)
`@payloadcms/ui`	Payload admin panel React components
`payload`	Payload CMS core
`next`	Next.js 15 framework
`react` / `react-dom`	React 19 runtime
`sharp`	Image processing for Payload uploads

Cross-References

ALL CMS configuration: packages/cms-core/ -- see packages/cms-core/AGENTS.md
CMS client for querying data: packages/cms-client/ -- see packages/cms-client/AGENTS.md
Core business logic: packages/core/ -- see packages/core/AGENTS.md

4.0 KiB Raw Blame History