payload

Please read the /CLAUDE.md file for context.

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) and Cursor when working with code in this repository.

## Project Structure

Payload is a monorepo structured around Next.js, containing the core CMS platform, database adapters, plugins, and tooling.

### Key Directories

- `packages/` - All publishable packages
  - `packages/payload` - Core Payload package containing the main CMS logic
  - `packages/ui` - Admin UI components (React Server Components)
  - `packages/next` - Next.js integration layer
  - `packages/db-*` - Database adapters (MongoDB, Postgres, SQLite, Vercel Postgres, D1 SQLite)
  - `packages/drizzle` - Drizzle ORM integration
  - `packages/kv-redis` - Redis key-value store adapter
  - `packages/richtext-*` - Rich text editors (Lexical)
  - `packages/storage-*` - Storage adapters (S3, Azure, GCS, Vercel Blob, R2)
  - `packages/email-*` - Email adapters (Nodemailer, Resend)
  - `packages/plugin-*` - Additional functionality plugins
  - `packages/graphql` - GraphQL API layer
  - `packages/translations` - i18n translations
- `test/` - Test suites organized by feature area. Each directory contains a granular Payload config and test files
- `docs/` - Documentation (deployed to payloadcms.com)
- `tools/` - Monorepo tooling
- `templates/` - Production-ready project templates
- `examples/` - Example implementations

### Architecture Notes

- Payload 3.x is built as a Next.js native CMS that installs directly in `/app` folder
- UI is built with React Server Components (RSC)
- Database adapters use Drizzle ORM under the hood
- Packages use TypeScript with strict mode and path mappings defined in `tsconfig.base.json`
- Source files are in `src/`, compiled outputs go to `dist/`
- Monorepo uses pnpm workspaces and Turbo for builds

## Quick Start

1. `pnpm install`
2. `pnpm run build:core`
3. `pnpm run dev` (MongoDB) or `pnpm run dev:postgres`

## Build Commands

- `pnpm install` - Install all dependencies
- `pnpm turbo` - All Turbo commands should be run from root with pnpm - not with `turbo` directly
- `pnpm run build` or `pnpm run build:core` - Build core packages (excludes plugins and storage adapters)
- `pnpm run build:all` - Build all packages
- `pnpm run build:<directory_name>` - Build specific package (e.g. `pnpm run build:db-mongodb`, `pnpm run build:ui`)

## Development

### Coding Patterns and Best Practices

- Always use object parameters for function arguments: `fn({ name }: { name: string })` not `fn(name: string)` (improves backwards-compatibility)
- Prefer types over interfaces (except when extending external types)
- Prefer functions over classes (classes only for errors/adapters)
- Prefer pure functions; when mutation is unavoidable, return the mutated object instead of void.
- Organize functions top-down: exports before helpers
- Use JSDoc for complex functions; add tags only when justified beyond type signature
- Use `import type` for types, regular `import` for values, separate statements even from same module
- Prefix booleans with `is`/`has`/`can`/`should` (e.g., `isValid`, `hasData`) for clarity
- Prefer self describing function and variable names over generic names with comments to explain their purpose
- **Translation/Label handling**: Always use `getTranslation` from `@payloadcms/translations` when you need to render labels defined in the config - it already handles functions, strings, and translation objects correctly. Don't write custom if/else logic to handle different label types.
- **Memoize arrays/objects passed to hooks**: Never pass inline array/object literals to custom hooks - they create new references on every render, breaking memoization and causing unnecessary re-renders or remounts.

  ```typescript
  // BAD - creates new array every render, breaks hook memoization
  const [Drawer] = useHierarchyDrawer({
    filterByCollection: [collectionSlug],
  })

  // GOOD - memoized, stable reference
  const filterByCollection = useMemo(() => [collectionSlug], [collectionSlug])
  const [Drawer] = useHierarchyDrawer({
    filterByCollection,
  })
  ```

- Commenting Guidelines

  - Execution flow: Skip comments when code is self-documenting. Keep for complex logic, non-obvious "why", multi-line context, or if following a documented, multi-step flow.
  - Top of file/module: Use sparingly; only for non-obvious purpose/context or an overview of complex logic.
  - Type definitions: Property/interface documentation is always acceptable.

- Logger Usage (`payload.logger.error`)
  - Valid: `payload.logger.error('message')` or `payload.logger.error({ msg: '...', err: error })`
  - Invalid: `payload.logger.error('message', err)` - don't pass error as second argument
  - Use `err` not `error`, use `msg` not `message` in object form

### React Component File Structure

Each React component should have its own named folder:

```
ComponentName/
├── index.tsx       # Component implementation
└── index.css       # Styles (if applicable)
```

- **Do:** Create a folder per component with `index.tsx` and `index.css`
- **Don't:** Place multiple `ComponentName.tsx` files in a single folder with one shared `.css` file
- Re-export from barrel files (`index.ts`) when grouping related components in a parent directory
- New styles should be written in plain CSS, not SCSS - SCSS is being phased out and is no longer linted (see [Writing CSS](#writing-css))

### Running Dev Server

- `pnpm run dev` - Start dev server with default config (`test/_community/config.ts`)
- `pnpm run dev <directory_name>` - Start dev server with specific test config (e.g. `pnpm run dev fields` loads `test/fields/config.ts`)
- `pnpm run dev:postgres` - Run dev server with Postgres

### Development Environment

- Auto-login is enabled by default with credentials: `[email protected]` / `test`
- To disable: pass `--no-auto-login` flag or set `PAYLOAD_PUBLIC_DISABLE_AUTO_LOGIN=false`
- Default database is MongoDB (in-memory). Switch to Postgres with `PAYLOAD_DATABASE=postgres`
- Docker services: `pnpm docker:start` / `pnpm docker:clean` / `pnpm docker:test`

### Playwright MCP

You should have access to the Playwright MCP server. This MCP server enables LLMs to interact with web pages through structured accessibility snapshots, bypassing the need for screenshots or visually-tuned models.

**Prerequisites:**

- The dev server MUST be running (`pnpm run dev`) before using the MCP
- First call `browser_install` to set up the browser if needed

**Key tools (not exhaustive):**

- `browser_navigate` - Navigate to a URL
- `browser_snapshot` - Get accessibility snapshot of current page
- `browser_click` - Click elements (requires `ref` from snapshot)
- `browser_fill_form` - Fill form fields
- `browser_take_screenshot` - Capture screenshot (use `fullPage: true` for full page)

**Screenshots for visual verification:**

Use `browser_take_screenshot` to visually verify UI state. Useful for:

- Confirming layout and styling look correct
- Checking component rendering (tags, forms, tables)
- Debugging UI issues that aren't visible in accessibility snapshots

```
browser_take_screenshot()                    # Viewport only
browser_take_screenshot({ fullPage: true })  # Full scrollable page
```

Screenshots are saved to `.playwright-mcp/` and displayed inline.

**Usage flow:**

1. Ensure dev server is running on `localhost:3000`
2. Call `browser_navigate` to open a page
3. Call `browser_snapshot` to get element refs
4. Use refs to interact with `browser_click`, `browser_fill_form`, etc.

## Testing

### Writing Tests - Required Practices

**Tests MUST be self-contained and clean up after themselves:**

- If you create a database record in a test, you MUST delete it before the test completes
- For multiple tests with similar cleanup needs, use `afterEach` to centralize cleanup logic
- Track created resources (IDs, files, etc.) in a shared array within the `describe` block
- Do not use conditionals in tests where it can be avoided such as `if else`
- Do not use `try {} finally {}` in e2e tests; prefer Playwright cleanup hooks (`afterEach`, `afterAll`)

**Example pattern:**

```typescript
describe('My Feature', () => {
  const createdIDs: number[] = []

  afterEach(async () => {
    for (const id of createdIDs) {
      await payload.delete({ collection: 'my-collection', id })
    }
    createdIDs.length = 0
  })

  it('should create a record', async () => {
    const id = 123
    createdIDs.push(id)

    await payload.create({ collection: 'my-collection', data: { id, title: 'Test' } })
    // assertions...
  })
})
```

**Additional test guidelines:**

- Use descriptive test names starting with "should" (e.g., "should create document with custom ID")
- Add blank lines after variable declarations to improve readability
- Collection and global slugs should be kept in a shared file and re-used i.e. on relationship fields `relationTo: collectionSlug`
- One test should verify one behavior - keep tests focused
- When adding a new collection for testing, add it to both `collections/` directory and the config file import statements

### How to run tests

- `pnpm run test` - Run all tests (integration + components + e2e)
- `pnpm run test:int` - Integration tests (MongoDB, recommended)
- `pnpm run test:int <dir>` - Specific test suite (e.g. `fields`)
- `pnpm run test:int:postgres|sqlite` - Integration tests with other databases
- `pnpm run test:e2e` - Playwright tests (add `:headed` or `:debug` suffix)
- `pnpm run test:unit|components|types` - Other test suites

### Test Structure

Each test directory in `test/` follows this pattern:

```
test/<feature-name>/
├── config.ts        # Lightweight Payload config for testing
├── int.spec.ts      # Integration tests (Vitest)
├── e2e.spec.ts      # End-to-end tests (Playwright)
└── payload-types.ts # Generated types
```

Generate types for a test directory: `pnpm run dev:generate-types <directory_name>`

## Linting & Formatting

- `pnpm run lint` - Run linter across all packages
- `pnpm run lint:fix` - Fix linting issues

## Internationalization

- Translation files are in `packages/translations/src/languages/`
- Add new strings to English locale first, then translate to other languages
- Run `pnpm run translateNewKeys` to auto-translate new keys (requires `OPENAI_KEY` in `.env`)
- Lexical translations: `cd packages/richtext-lexical && pnpm run translateNewKeys`

## Commit & PR Guidelines

This repository follows [Conventional Commits](https://www.conventionalcommits.org/).

### PR Title Format

`<type>(<scope>): <title>`

- Title must start with lowercase letter
- Types: `build`, `chore`, `ci`, `docs`, `examples`, `feat`, `fix`, `perf`, `refactor`, `revert`, `style`, `templates`, `test`
- Prefer `feat` for new features, `fix` for bug fixes
- Scopes match package names: `db-*`, `richtext-*`, `storage-*`, `plugin-*`, `ui`, `next`, `graphql`, `translations`, etc.
- Choose most relevant scope if multiple packages modified, or omit scope entirely

Examples:

- `feat(db-mongodb): add support for transactions`
- `feat(richtext-lexical): add options to hide block handles`
- `fix(ui): json field type ignoring editorOptions`
- `feat: add new collection functionality`

### Commit Guidelines

- First commit of branch should follow PR title format
- Subsequent commits should use `chore` without scope unless specific package is being modified
- All commits in a PR are squashed on merge using PR title as commit message

## Additional Resources

- LLMS.txt: <https://payloadcms.com/llms.txt>
- LLMS-FULL.txt: <https://payloadcms.com/llms-full.txt>
- Node version: >=24.15.0
- pnpm version: ^11.9.0

## Admin Panel

The admin panel is made up of both client and server react components.

### Patterns

ALWAYS use `formatAdminURL` when formatting api and admin routes.

**Building API URLs with query parameters:** Use `qs-esm` to build query strings with proper object syntax instead of manual string concatenation.

Incorrect:

```typescript
const whereClause = parentId
  ? `where[${parentFieldName}][equals]=${parentId}`
  : `where[or][0][${parentFieldName}][exists]=false&where[or][1][${parentFieldName}][equals]=`

const url = `${serverURL}${api}/${collectionSlug}?${whereClause}&limit=${limit}&page=${page}`
```

Correct:

```typescript
import { formatAdminURL } from 'payload/shared'
import * as qs from 'qs-esm'

const where = parentId
  ? { [parentFieldName]: { equals: parentId } }
  : {
      or: [{ [parentFieldName]: { exists: false } }, { [parentFieldName]: { equals: null } }],
    }

const queryString = qs.stringify({ limit, page, where }, { addQueryPrefix: true })
const url = formatAdminURL({ apiRoute: api, path: `/${collectionSlug}${queryString}`, serverURL })
```

**Building server functions, views, or endpoints:** Always use `overrideAccess: false` and pass the `user` to payload operations. Without these, the operation runs with access control disabled, which is a security vulnerability.

Incorrect:

```typescript
// INSECURE - runs with full access, bypassing all access control
const docs = await payload.find({
  collection: 'posts',
})
```

Correct:

```typescript
// SECURE - respects access control for the current user
const docs = await payload.find({
  collection: 'posts',
  overrideAccess: false,
  user,
})
```

### Writing CSS

Stylelint enforces the rules below on `.css` files (SCSS is no longer linted and is being phased out). Run `pnpm run lint:css` to check, or `pnpm run lint` to run all linters.

**Mobile-first media queries only - never `max-width`:**

```css
/* BAD - rejected by plugin/no-max-width-media-query */
@media (max-width: 768px) {
  ...;
}

/* GOOD */
@media (min-width: 768px) {
  ...;
}
```

**Only the four canonical breakpoints are allowed in a media query** (`plugin/no-non-standard-breakpoints`): `400px`, `768px`, `1024px`, `1440px`. Don't invent one-off breakpoint values.

**Never use `!important`** (`plugin/no-important`). Refactor selector specificity instead.
Exceptions to this rule are when it's not possible to do so when dealing with external libraries.

**Prefer logical properties over physical properties** for RTL support:

```css
/* BAD - physical properties don't flip for RTL */
padding-left: var(--spacer-3);
margin-right: var(--spacer-2);
border-left: 1px solid var(--color-border);
left: 0;

/* GOOD - logical properties adapt automatically */
padding-inline-start: var(--spacer-3);
margin-inline-end: var(--spacer-2);
border-inline-start: var(--stroke-width-small) solid var(--color-border);
inset-inline-start: 0;
```

Use `padding-inline`/`padding-block`, `margin-inline`/`margin-block`, `inset-inline`/`inset-block`, and `border-inline`/`border-block` (with their `-start`/`-end` variants) instead of the `-left`/`-right`/`-top`/`-bottom` equivalents where a direction is implied.

**Prioritize design tokens over hardcoded pixel/rem values:**

Spacing (`width`/`height`, `margin*`, `padding*`, `top`/`right`/`bottom`/`left`, `inset*`, `gap*`, `flex-basis`, etc.) should use a `--spacer-*` token from `packages/ui/src/css/spacing.css`, not a raw pixel or rem value:

| Token          | Pixel |
| -------------- | ----- |
| `--spacer-0`   | 0px   |
| `--spacer-1`   | 4px   |
| `--spacer-1-5` | 6px   |
| `--spacer-2`   | 8px   |
| `--spacer-2-5` | 12px  |
| `--spacer-3`   | 16px  |
| `--spacer-4`   | 24px  |
| `--spacer-5`   | 32px  |
| `--spacer-6`   | 40px  |

- If the value needed isn't an exact token, round to the nearest `--spacer-*` token rather than hand-writing a one-off value.
- If a niche value must be precise (not a rounding-friendly case), use `calc()` with a spacer token instead of a raw pixel/rem value, e.g. `calc(var(--spacer-1) * 2.5)` for `10px`.
- The same principle applies to other token families:
  - **Colors:** use semantic `--color-*` tokens from `colors.css` (e.g. `--color-bg`, `--color-text-brand`, `--color-border`). Never reference raw `--ramp-*` palette tokens directly outside of `colors.css` as they aren't theme-aware.
  - **Radius:** use `--radius-*` from `radius.css` (`--radius-small` 2px, `--radius-medium` 5px, `--radius-large` 13px, `--radius-full` 9999px) instead of hardcoded values.
  - **Stroke width:** use `--stroke-width-small` (1px) / `--stroke-width-medium` (2px) from `theme.css`.
  - **Box shadows:** use elevation tokens from `elevations.css` (`--elevation-100-canvas`, `--elevation-300-tooltip`, `--elevation-400-menu-panel`, `--elevation-500-modal-window`) instead of a hardcoded `box-shadow`/`rgba()` value - they also handle light/dark theming.
  - **Typography:** use `--text-*` tokens from `typography.css`.

**No sub-pixel precision** (`plugin/no-subpixel-values`) - applies to whatever raw value remains after the above (e.g. an exception case):

- Pixel values may have at most one decimal place (e.g. `0.5px` is fine, `13.523px` is not).
- Box-model and position properties - `width`/`height`, `margin*`, `padding*`, `top`/`right`/`bottom`/`left`, `inset*`, `gap*`, `flex-basis`, `min-`/`max-width`/`height` - must be whole numbers with no decimals at all.
- `font-size`, `letter-spacing`, `line-height`, and custom properties (`--*`) are exempt, since a `var()` can't be statically traced to the property it ends up on.

### RSC/Client Bundling Rules

These rules prevent production bundling issues where client code gets evaluated in server context.

**1. Avoid barrel exports (`export *`) - always use explicit named exports:**

Barrel exports cause bundling issues, break tree-shaking, and can break client/server boundaries in production. Always use explicit named exports.

```typescript
// BAD - barrel export
export * from '../../elements/SomeComponent/exports.js'

// GOOD - explicit named exports
export { SomeComponent } from '../../elements/SomeComponent/index.js'
export { AnotherComponent } from '../../elements/AnotherComponent/index.js'
```

**2. Server components must import client components from `exports/client/index.js`:**

When a `.server.tsx` file needs to render a client component, it must import from the client exports bundle, not via relative path. Relative imports don't respect `'use client'` boundaries in production builds.

```typescript
// BAD - relative import doesn't work in prod
import { MyClientComponent } from './MyComponent.js'

// GOOD - import from client exports bundle
// eslint-disable-next-line payload/no-imports-from-exports-dir -- Server component must reference exports dir for proper client boundary
import { MyClientComponent } from '../../exports/client/index.js'
```

**Testing bundling changes:** Always test with `pnpm prepare-run-test-against-prod` followed by `pnpm dev:prod <suite>`. Dev mode (`pnpm dev`) doesn't catch these issues.