feat: payload version item in admin settings menu

CLAUDE.md

@@ -233,6 +233,7 @@ Generate types for a test directory: `pnpm run dev:generate-types <directory_nam
 - 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`
+- **Adding a key to `en.ts` makes it required in every other language file.** The build fails (TS2741) for each unpopulated locale until either `translateNewKeys` runs or English fallbacks are stubbed across all ~44 files. If `OPENAI_KEY` isn't available and the work is small, prefer hardcoding the user-facing string and deferring the translation key to a follow-up.
 
 ## Commit & PR Guidelines
 
@@ -356,4 +357,39 @@ import { MyClientComponent } from './MyComponent.js'
 import { MyClientComponent } from '../../exports/client/index.js'
 ```
 
+**3. Server-only components in built-in path strings must use the `/rsc` subpath:**
+
+When auto-injecting a built-in server component into a config slot via path-string syntax (e.g. inside `sanitizeConfig`, `inject*` helpers), use the `/rsc` subpath. The bare `@payloadcms/ui` resolves to the client bundle, which doesn't export server-only components — the runtime warns `getFromImportMap: PayloadComponent not found in importMap`.
+
+```typescript
+// BAD - resolves to the client bundle, server-only export is missing
+config.admin.components.settingsMenu.push('@payloadcms/ui#PayloadVersionMenuItem')
+
+// GOOD - resolves through the RSC export map
+config.admin.components.settingsMenu.push('@payloadcms/ui/rsc#PayloadVersionMenuItem')
+```
+
+See `packages/payload/src/hierarchy/injectHierarchyButton.ts` for the established pattern.
+
 **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.
+
+### Styling
+
+New components prefer vanilla CSS (`index.css`) over SCSS, using v4 design tokens. Existing SCSS files are migrated as touched.
+
+- Wrap rules in `@layer payload-default { ... }` (matches Tooltip, PopupButtonList, and other v4 components).
+- Use v4 tokens: `--bg-default-default`, `--text-default-secondary`, `--spacer-N`, `--radius-medium`, `--font-family-mono`, etc. Do not hardcode colors or pixels.
+- **Native CSS nesting does not support BEM concatenation.** `&__wrapper` only works in SCSS. In vanilla CSS, write each BEM child as a top-level rule within the layer:
+
+```css
+/* BAD - native CSS nesting cannot concat suffixes */
+.thing {
+  &__row { ... }
+}
+
+/* GOOD - separate top-level rules */
+.thing { ... }
+.thing__row { ... }
+```
+
+- `&` is still valid for pseudo-classes/states (`&:hover`, `&.is-open`) and descendants (`& .child`).

packages/payload/src/config/sanitize.ts

@@ -39,6 +39,7 @@ import { validateTimezones } from '../utilities/validateTimezones.js'
 import { getSchedulePublishTask } from '../versions/schedule/job.js'
 import { addDefaultsToConfig } from './defaults.js'
 import { addOrderableEndpoint, addOrderableFieldsAndHook } from './orderable/index.js'
+import { sanitizeDependencies } from './sanitizeDependencies.js'
 
 const sanitizeAdminConfig = (configToSanitize: Config): Partial<SanitizedConfig> => {
   const sanitizedConfig = { ...configToSanitize }
@@ -118,6 +119,15 @@ export const sanitizeConfig = async (incomingConfig: Config): Promise<SanitizedC
 
   const config: Partial<SanitizedConfig> = sanitizeAdminConfig(configWithDefaults)
 
+  config.admin!.packageVersions = await sanitizeDependencies()
+
+  if (config.admin!.versionInSettingsMenu !== false) {
+    const adminComponents = config.admin!.components ?? {}
+    config.admin!.components = adminComponents
+    const existing = adminComponents.settingsMenu ?? []
+    adminComponents.settingsMenu = [...existing, '@payloadcms/ui/rsc#PayloadVersionMenuItem']
+  }
+
   if (!config.endpoints) {
     config.endpoints = []
   }

packages/payload/src/config/sanitizeDependencies.spec.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import { sanitizeDependencies } from './sanitizeDependencies.js'
+
+describe('sanitizeDependencies', () => {
+  it('returns a record always containing a payload entry', async () => {
+    const deps = await sanitizeDependencies()
+    expect(deps.payload).toMatch(/^\d+\.\d+\.\d+/)
+  })
+
+  it('returns alphabetically sorted keys', async () => {
+    const deps = await sanitizeDependencies()
+    const keys = Object.keys(deps)
+    const sorted = [...keys].sort((a, b) => a.localeCompare(b))
+    expect(keys).toEqual(sorted)
+  })
+
+  it('falls back to a payload-only map when getDependencies throws', async () => {
+    vi.doMock('../utilities/dependencies/getDependencies.js', () => ({
+      getDependencies: () => Promise.reject(new Error('boom')),
+    }))
+    vi.resetModules()
+    const { sanitizeDependencies: freshSanitize } = await import('./sanitizeDependencies.js')
+    const deps = await freshSanitize()
+    expect(Object.keys(deps)).toEqual(['payload'])
+    expect(deps.payload).toMatch(/^\d+\.\d+\.\d+/)
+    vi.doUnmock('../utilities/dependencies/getDependencies.js')
+  })
+})

packages/payload/src/config/sanitizeDependencies.ts

@@ -0,0 +1,61 @@
+import { promises as fs } from 'fs'
+import path from 'path'
+import { fileURLToPath } from 'url'
+
+import { getDependencies } from '../utilities/dependencies/getDependencies.js'
+import { PAYLOAD_PACKAGE_LIST } from '../versions/payloadPackageList.js'
+
+const filename = fileURLToPath(import.meta.url)
+const dirname = path.dirname(filename)
+const payloadPkgRoot = path.resolve(dirname, '../../')
+
+const readPayloadFallbackVersion = async (): Promise<string> => {
+  try {
+    const pkgJsonPath = path.join(payloadPkgRoot, 'package.json')
+    const raw = await fs.readFile(pkgJsonPath, 'utf8')
+    const parsed = JSON.parse(raw) as { version?: string }
+    return parsed.version ?? '0.0.0'
+  } catch {
+    return '0.0.0'
+  }
+}
+
+/**
+ * Strip any subpath after the npm package name. For `@payloadcms/next/utilities`,
+ * the package name is `@payloadcms/next`. For `lodash/get`, it's `lodash`.
+ * The list passed to `getDependencies` includes subpath probes (e.g. to verify
+ * a specific export resolves), but for display we only want the bare package.
+ */
+const stripSubpath = (specifier: string): string => {
+  if (specifier.startsWith('@')) {
+    const [scope, name] = specifier.split('/')
+    return name ? `${scope}/${name}` : specifier
+  }
+  return specifier.split('/')[0] ?? specifier
+}
+
+/**
+ * Scan the user's project for installed Payload-related packages and return
+ * an alphabetically-sorted map of name → version. Always contains `payload`.
+ * Never throws — falls back to a single-entry map if the scan fails.
+ */
+export const sanitizeDependencies = async (): Promise<Record<string, string>> => {
+  try {
+    const result = await getDependencies(process.cwd(), ['payload', ...PAYLOAD_PACKAGE_LIST])
+    const map: Record<string, string> = {}
+    for (const [specifier, { version }] of result.resolved) {
+      const name = stripSubpath(specifier)
+      // If the same package is probed via multiple specifiers, keep the first hit.
+      if (!map[name]) {
+        map[name] = version
+      }
+    }
+    const sorted = Object.fromEntries(Object.entries(map).sort(([a], [b]) => a.localeCompare(b)))
+    if (!sorted.payload) {
+      sorted.payload = await readPayloadFallbackVersion()
+    }
+    return sorted
+  } catch {
+    return { payload: await readPayloadFallbackVersion() }
+  }
+}

packages/payload/src/config/types.ts

@@ -1137,6 +1137,13 @@ export type Config = {
     }
     /** The slug of a Collection that you want to be used to log in to the Admin dashboard. */
     user?: string
+    /**
+     * When false, the built-in Payload version item is not auto-injected into
+     * `admin.components.settingsMenu`. Users can still add `@payloadcms/ui/rsc#PayloadVersionMenuItem`
+     * manually to control placement.
+     * @default true
+     */
+    versionInSettingsMenu?: boolean
   }
 
   /**
@@ -1582,6 +1589,12 @@ export type Config = {
  */
 export type SanitizedConfig = {
   admin: {
+    /**
+     * Map of resolved Payload-related package versions (name → semver), computed
+     * at config sanitization. Always contains a `payload` entry. Missing packages
+     * are omitted. Used by the built-in version menu item.
+     */
+    packageVersions: Record<string, string>
     timezones: SanitizedTimezoneConfig
   } & DeepRequired<Config['admin']>
   blocks?: FlattenedBlock[]

packages/payload/src/config/versionMenu.spec.ts

@@ -0,0 +1,75 @@
+import { describe, expect, it } from 'vitest'
+
+import type { Config } from './types.js'
+
+import { sanitizeConfig } from './sanitize.js'
+
+const VERSION_MENU_ITEM = '@payloadcms/ui/rsc#PayloadVersionMenuItem'
+
+/** Minimal config shape — db/editor are not used during the sanitization paths we test */
+// @ts-expect-error
+const minimalConfig: Config = {
+  collections: [],
+}
+
+describe('version menu auto-injection', () => {
+  it('populates packageVersions.payload with a semver string', async () => {
+    const sanitized = await sanitizeConfig(minimalConfig)
+
+    expect(sanitized.admin.packageVersions.payload).toMatch(/^\d+\.\d+\.\d+/)
+  })
+
+  it('appends the menu item after user-defined settingsMenu entries', async () => {
+    const item1 = '/components/Item1.tsx#Item1'
+    const item2 = '/components/Item2.tsx#Item2'
+
+    // @ts-expect-error
+    const config: Config = {
+      collections: [],
+      admin: {
+        components: {
+          settingsMenu: [item1, item2],
+        },
+      },
+    }
+
+    const sanitized = await sanitizeConfig(config)
+    const menu = sanitized.admin.components!.settingsMenu!
+
+    expect(menu.slice(0, 2)).toEqual([item1, item2])
+    expect(menu[menu.length - 1]).toBe(VERSION_MENU_ITEM)
+  })
+
+  it('does NOT inject the menu item when versionInSettingsMenu is false', async () => {
+    // @ts-expect-error
+    const config: Config = {
+      collections: [],
+      admin: {
+        versionInSettingsMenu: false,
+        components: {
+          settingsMenu: ['/components/Item1.tsx#Item1'],
+        },
+      },
+    }
+
+    const sanitized = await sanitizeConfig(config)
+    const menu = sanitized.admin.components?.settingsMenu ?? []
+
+    expect(menu).not.toContain(VERSION_MENU_ITEM)
+  })
+
+  it('injects the menu item when no settingsMenu is defined', async () => {
+    // @ts-expect-error
+    const config: Config = {
+      collections: [],
+      admin: {
+        components: {},
+      },
+    }
+
+    const sanitized = await sanitizeConfig(config)
+    const menu = sanitized.admin.components!.settingsMenu!
+
+    expect(menu).toContain(VERSION_MENU_ITEM)
+  })
+})

packages/ui/src/elements/PayloadVersionMenuItem/PayloadVersionModalTrigger.tsx

@@ -0,0 +1,46 @@
+'use client'
+
+import React from 'react'
+
+// eslint-disable-next-line payload/no-imports-from-exports-dir -- Client component imports from same package's client bundle
+import { CopyToClipboard, Modal, PopupList, useModal } from '../../exports/client/index.js'
+import { formatForClipboard } from './formatForClipboard.js'
+import { VersionList } from './VersionList.js'
+import './index.css'
+
+const baseClass = 'payload-version-menu-item'
+const modalSlug = 'payload-version-info'
+
+export const PayloadVersionModalTrigger: React.FC<{
+  versions: Record<string, string>
+}> = ({ versions }) => {
+  const { closeModal, isModalOpen, openModal } = useModal()
+  const payloadVersion = versions.payload ?? '0.0.0'
+
+  return (
+    <PopupList.ButtonGroup>
+      <PopupList.Button className={`${baseClass}__button`} onClick={() => openModal(modalSlug)}>
+        {`Payload v${payloadVersion}`}
+      </PopupList.Button>
+      {isModalOpen(modalSlug) && (
+        <Modal className={baseClass} closeOnBlur={false} slug={modalSlug}>
+          <div className={`${baseClass}__wrapper`}>
+            <div className={`${baseClass}__header`}>
+              <h2>Payload Version Info</h2>
+              <CopyToClipboard value={formatForClipboard(versions)} />
+              <button
+                aria-label="Close"
+                className={`${baseClass}__close`}
+                onClick={() => closeModal(modalSlug)}
+                type="button"
+              >
+                ×
+              </button>
+            </div>
+            <VersionList versions={versions} />
+          </div>
+        </Modal>
+      )}
+    </PopupList.ButtonGroup>
+  )
+}

packages/ui/src/elements/PayloadVersionMenuItem/VersionList.tsx

@@ -0,0 +1,25 @@
+'use client'
+
+import React from 'react'
+
+export const VersionList: React.FC<{
+  versions: Record<string, string>
+}> = ({ versions }) => {
+  const ordered = [
+    ['payload', versions.payload],
+    ...Object.entries(versions)
+      .filter(([k]) => k !== 'payload')
+      .sort(([a], [b]) => a.localeCompare(b)),
+  ].filter(([, v]) => Boolean(v)) as Array<[string, string]>
+
+  return (
+    <dl className="payload-version-menu-item__list">
+      {ordered.map(([name, version]) => (
+        <div className="payload-version-menu-item__row" key={name}>
+          <dt>{name}</dt>
+          <dd>{version}</dd>
+        </div>
+      ))}
+    </dl>
+  )
+}

packages/ui/src/elements/PayloadVersionMenuItem/formatForClipboard.spec.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest'
+import { formatForClipboard } from './formatForClipboard.js'
+
+describe('formatForClipboard', () => {
+  it('puts payload first, rest alphabetical', () => {
+    expect(
+      formatForClipboard({
+        '@payloadcms/ui': '3.0.0',
+        '@payloadcms/db-mongodb': '3.0.0',
+        payload: '3.0.0',
+      }),
+    ).toBe('payload: 3.0.0\n@payloadcms/db-mongodb: 3.0.0\n@payloadcms/ui: 3.0.0')
+  })
+
+  it('returns empty string when payload missing', () => {
+    expect(formatForClipboard({})).toBe('')
+  })
+
+  it('handles a payload-only map', () => {
+    expect(formatForClipboard({ payload: '3.1.2' })).toBe('payload: 3.1.2')
+  })
+})

packages/ui/src/elements/PayloadVersionMenuItem/formatForClipboard.ts

@@ -0,0 +1,12 @@
+export const formatForClipboard = (deps: Record<string, string>): string => {
+  if (!deps.payload) {
+    return ''
+  }
+
+  const rest = Object.keys(deps)
+    .filter((k) => k !== 'payload')
+    .sort((a, b) => a.localeCompare(b))
+
+  const lines = [`payload: ${deps.payload}`, ...rest.map((k) => `${k}: ${deps[k]}`)]
+  return lines.join('\n')
+}