convex-monorepo-payload/docs/payload-cms.md

Payload CMS

Payload is embedded in apps/next and manages marketing content. Convex remains the application backend for auth, realtime data, files, and workflows.

Configuration lives in apps/next/src/payload.config.ts. Payload uses PAYLOAD_SECRET, PAYLOAD_DB_URL, and NEXT_PUBLIC_SITE_URL from the validated environment contract. Local dev values come from Infisical and point Payload to Postgres at localhost:5432, because Next runs on the host.

Start the isolated services with bun db:up, then run bun dev:next. The local database persists across bun db:down; bun db:down:wipe removes it. Local Convex data is stored in a separate volume and Convex does not receive POSTGRES_URL by default.

To refresh the local seed snapshot from current staging/production-derived Payload content, stop Next and run bun db:sync:payload. The command uses staging only as a read-only dump source, verifies the restore destination is localhost, writes .local/payload-staging.dump, and force-applies it locally. Normal bun db:up never contacts staging; it only restores that local snapshot when .local/payload-seed-state.env is absent or does not match the current snapshot. The marker stays outside Postgres so Payload schema push does not see an unmanaged table. The snapshot is gitignored and contains sensitive production-derived records, including Payload users and password hashes. Do not share or commit it.

The public landing page is in apps/next/src/app/(frontend)/page.tsx; schemas are under apps/next/src/payload, and rendering components are under apps/next/src/components/landing. Custom routes belong in (frontend), not the generated (payload) route group.

Do not manually edit Payload-generated routes, layouts, import maps, or apps/next/payload-types.ts. When schema changes require regeneration, run the Payload generators through the package's environment wrapper:

cd apps/next
bun with-env bunx payload generate:types --config src/payload.config.ts
bun with-env bunx payload generate:db-schema --config src/payload.config.ts

For staging, use INFISICAL_ENV=staging; CI uses temporary Gitea-injected configuration and never Infisical. Production Payload may use the existing external/VPN Postgres URL or the commented optional Compose Postgres service.