api-cms-payload

What it does

Instructs the agent to implement Payload CMS patterns using a code-first configuration approach. It highlights defining collections and globals as config objects with typed fields, hooks, and access control functions. It prescribes using the Local API for server-side operations, generating TypeScript types after schema changes, and separating config from UI concerns. It requires access control on every collection, and it specifies using database adapters, and recommended file and export conventions. Hooks and access control are defined per operation and can return boolean or a Where query. It also covers a broad set of field types, pattern usage for admin UI configuration, and multiple API surfaces (Local, REST, GraphQL).

How it works

• Use payload.config.ts to configure database adapter, editor, collections, globals, admin user, and TS type generation output.
• Define each collection in its own file with a slug, fields, admin settings, access controls, and optional hooks.
• Implement access control functions that receive { req } with the authenticated user and return boolean or a Where query to scope results.
• Attach hooks (beforeChange, afterChange, beforeRead, afterRead, beforeValidate, beforeDelete, afterDelete, etc.) to collections to run logic at lifecycle points.
• Use Local API calls via payload.find and payload.create for server-side operations; ensure overrideAccess is false when acting on behalf of a user.
• Define various field types (text, richText, relationship, upload, etc.) and optional admin/config properties.
• Follow the critical requirements: define access on every collection, generate TS types after schema changes, keep config and UI concerns separate, and avoid hardcoding credentials.
• Expose three APIs from one config: Local API (server-side), REST API, and GraphQL API.
• Use versioning/drafts and upload configurations as needed.
• Include explicit use of buildConfig, database adapters, and type generation as demonstrated in patterns.

When to use it

• When configuring payload.config.ts with a database adapter, collections, and globals
• When defining collection schemas with typed fields (text, richText, relationship, blocks, array, group, upload, select)
• When implementing access control functions (role-based, ownership-based, field-level)
• When writing collection hooks (beforeChange, afterChange, beforeRead, afterRead, beforeValidate, beforeDelete, afterDelete)
• When querying data via Local API, REST API, or GraphQL
• When setting up authentication collections with login, roles, and JWT
• When configuring uploads/media with image sizes and mime type restrictions
• When enabling versions and drafts on collections or globals
• When customizing the admin panel (groups, hidden collections, custom components)

What it can touch

• Local API: payload.find, payload.findByID, payload.create, payload.update, payload.delete, payload.count
• REST API endpoints at /api/{collection-slug}
• GraphQL API surfaces (from config)
• File system imports and exports for collection files and globals
• Environment variables for database connection strings and secrets

Caveats

• Access control is mandatory for every collection; open collections are a security risk
• Default Local API access bypass can occur if overrideAccess is not set to false; must set overrideAccess: false when acting on behalf of a user
• Hooks should avoid blocking side effects; avoid external API calls in beforeChange where possible
• Ensure TypeScript types are generated after schema changes via payload generate:types; keep UI imports out of the Payload config
• Do not hardcode credentials; use environment variables for database connections and secrets