chore: replace magic strings with centralized constants (#15475)

Replaces hardcoded preference key strings with centralized constants to
prevent typos and improve maintainability. Creates PREFERENCE_KEYS
object in packages/payload/src/preferences/keys.ts and updates all
usages throughout the codebase.

I have another PR that sets preferences and figured it would be nice if
we had a centralized place for the pref constants.

---------

Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

Author: 3 people

packages/next/src/elements/Nav/getNavPrefs.ts

@@ -1,5 +1,6 @@
 import type { NavPreferences, PayloadRequest } from 'payload'
 
+import { PREFERENCE_KEYS } from 'payload/shared'
 import { cache } from 'react'
 
 export const getNavPrefs = cache(async (req: PayloadRequest): Promise<NavPreferences> => {
@@ -15,7 +16,7 @@ export const getNavPrefs = cache(async (req: PayloadRequest): Promise<NavPrefere
             and: [
               {
                 key: {
-                  equals: 'nav',
+                  equals: PREFERENCE_KEYS.NAV,
                 },
               },
               {

packages/next/src/views/BrowseByFolder/buildView.tsx

@@ -12,6 +12,7 @@ import { RenderServerComponent } from '@payloadcms/ui/elements/RenderServerCompo
 import { getFolderResultsComponentAndData, upsertPreferences } from '@payloadcms/ui/rsc'
 import { formatAdminURL } from '@payloadcms/ui/shared'
 import { redirect } from 'next/navigation.js'
+import { PREFERENCE_KEYS } from 'payload/shared'
 import React from 'react'
 
 export type BuildFolderViewArgs = {
@@ -111,7 +112,7 @@ export const buildBrowseByFolderView = async (
     sort?: FolderSortKeys
     viewPreference?: 'grid' | 'list'
   }>({
-    key: 'browse-by-folder',
+    key: PREFERENCE_KEYS.BROWSE_BY_FOLDER,
     req: initPageResult.req,
     value: {
       sort: query?.sort as FolderSortKeys,

packages/next/src/views/Dashboard/Default/ModularDashboard/index.tsx

@@ -11,6 +11,7 @@ import type {
 } from 'payload'
 
 import { RenderServerComponent } from '@payloadcms/ui/elements/RenderServerComponent'
+import { PREFERENCE_KEYS } from 'payload/shared'
 import React from 'react'
 
 import type { DashboardViewServerProps } from '../index.js'
@@ -74,7 +75,7 @@ async function getItemsFromPreferences(
   user: TypedUser,
 ): Promise<null | WidgetItem[]> {
   const savedPreferences = await getPreferences(
-    'dashboard-layout',
+    PREFERENCE_KEYS.DASHBOARD_LAYOUT,
     payload,
     user.id,
     user.collection,

packages/next/src/views/Dashboard/Default/ModularDashboard/useDashboardLayout.ts

@@ -9,6 +9,7 @@ import {
   usePreferences,
   useServerFunctions,
 } from '@payloadcms/ui'
+import { PREFERENCE_KEYS } from 'payload/shared'
 import React, { useCallback, useEffect, useState } from 'react'
 
 import type { WidgetInstanceClient, WidgetItem } from './index.client.js'
@@ -206,7 +207,7 @@ function useSetLayoutPreference() {
   const { setPreference } = usePreferences()
   return useCallback(
     async (layout: null | WidgetItem[]) => {
-      await setPreference('dashboard-layout', { layouts: layout }, false)
+      await setPreference(PREFERENCE_KEYS.DASHBOARD_LAYOUT, { layouts: layout }, false)
     },
     [setPreference],
   )

packages/payload/src/exports/shared.ts

@@ -61,13 +61,15 @@ export type {
 
 export { buildFolderWhereConstraints } from '../folders/utils/buildFolderWhereConstraints.js'
 export { formatFolderOrDocumentItem } from '../folders/utils/formatFolderOrDocumentItem.js'
+export { PREFERENCE_KEYS } from '../preferences/keys.js'
+
 export { validOperators, validOperatorSet } from '../types/constants.js'
 
 export { formatFilesize } from '../uploads/formatFilesize.js'
-
 export { isImage } from '../uploads/isImage.js'
 export { appendUploadSelectFields } from '../utilities/appendUploadSelectFields.js'
 export { applyLocaleFiltering } from '../utilities/applyLocaleFiltering.js'
+
 export { combineWhereConstraints } from '../utilities/combineWhereConstraints.js'
 
 export {
@@ -76,25 +78,25 @@ export {
   deepCopyObjectSimple,
   deepCopyObjectSimpleWithoutReactComponents,
 } from '../utilities/deepCopyObject.js'
-
 export {
   deepMerge,
   deepMergeWithCombinedArrays,
   deepMergeWithReactComponents,
   deepMergeWithSourceArrays,
 } from '../utilities/deepMerge.js'
+
 export { extractID } from '../utilities/extractID.js'
 
 export { flattenAllFields } from '../utilities/flattenAllFields.js'
-
 export { flattenTopLevelFields } from '../utilities/flattenTopLevelFields.js'
 export { formatAdminURL } from '../utilities/formatAdminURL.js'
 export { formatLabels, toWords } from '../utilities/formatLabels.js'
-export { getBestFitFromSizes } from '../utilities/getBestFitFromSizes.js'
 
+export { getBestFitFromSizes } from '../utilities/getBestFitFromSizes.js'
 export { getDataByPath } from '../utilities/getDataByPath.js'
 export { getFieldPermissions } from '../utilities/getFieldPermissions.js'
 export { getObjectDotNotation } from '../utilities/getObjectDotNotation.js'
+
 export { getSafeRedirect } from '../utilities/getSafeRedirect.js'
 
 export { getSelectMode } from '../utilities/getSelectMode.js'
@@ -146,7 +148,6 @@ export {
 } from '../utilities/transformColumnPreferences.js'
 
 export { transformWhereQuery } from '../utilities/transformWhereQuery.js'
-
 export { unflatten } from '../utilities/unflatten.js'
 export { validateMimeType } from '../utilities/validateMimeType.js'
 export { validateWhereQuery } from '../utilities/validateWhereQuery.js'

packages/payload/src/preferences/keys.ts

@@ -0,0 +1,21 @@
+/**
+ * Centralized preference keys used throughout Payload admin UI.
+ * Import these constants instead of using string literals to prevent typos.
+ */
+
+export const PREFERENCE_KEYS = {
+  /**
+   * Stores browse by folder view state
+   */
+  BROWSE_BY_FOLDER: 'browse-by-folder',
+
+  /**
+   * Stores dashboard layout configuration
+   */
+  DASHBOARD_LAYOUT: 'dashboard-layout',
+
+  /**
+   * Stores navigation group collapse/expand state and nav open/closed state
+   */
+  NAV: 'nav',
+} as const

packages/ui/src/elements/Nav/NavToggler/index.tsx

@@ -1,5 +1,6 @@
 'use client'
 import { useWindowInfo } from '@faceless-ui/window-info'
+import { PREFERENCE_KEYS } from 'payload/shared'
 import React from 'react'
 
 import { usePreferences } from '../../../providers/Preferences/index.js'
@@ -41,7 +42,7 @@ export const NavToggler: React.FC<{
         // this is because the js may open or close the nav based on the window size, routing, etc
         if (!largeBreak) {
           await setPreference(
-            'nav',
+            PREFERENCE_KEYS.NAV,
             {
               open: !navOpen,
             },

packages/ui/src/elements/Nav/context.tsx

@@ -1,6 +1,7 @@
 'use client'
 import { useWindowInfo } from '@faceless-ui/window-info'
 import { usePathname } from 'next/navigation.js'
+import { PREFERENCE_KEYS } from 'payload/shared'
 import React, { useEffect, useRef } from 'react'
 
 import { usePreferences } from '../../providers/Preferences/index.js'
@@ -27,7 +28,7 @@ export const NavContext = React.createContext<NavContextType>({
 export const useNav = () => React.use(NavContext)
 
 const getNavPreference = async (getPreference): Promise<boolean> => {
-  const navPrefs = await getPreference('nav')
+  const navPrefs = await getPreference(PREFERENCE_KEYS.NAV)
   const preferredState = navPrefs?.open
   if (typeof preferredState === 'boolean') {
     return preferredState

packages/ui/src/elements/NavGroup/index.tsx

@@ -1,6 +1,7 @@
 'use client'
 import type { NavPreferences } from 'payload'
 
+import { PREFERENCE_KEYS } from 'payload/shared'
 import React, { useState } from 'react'
 
 import { ChevronIcon } from '../../icons/Chevron/index.js'
@@ -17,8 +18,6 @@ type Props = {
   label: string
 }
 
-const preferencesKey = 'nav'
-
 export const NavGroup: React.FC<Props> = ({ children, isOpen: isOpenFromProps, label }) => {
   const [collapsed, setCollapsed] = useState(
     typeof isOpenFromProps !== 'undefined' ? !isOpenFromProps : false,
@@ -39,7 +38,7 @@ export const NavGroup: React.FC<Props> = ({ children, isOpen: isOpenFromProps, l
         newGroupPrefs[label].open = Boolean(collapsed)
       }
 
-      void setPreference(preferencesKey, { groups: newGroupPrefs }, true)
+      void setPreference(PREFERENCE_KEYS.NAV, { groups: newGroupPrefs }, true)
       setCollapsed(!collapsed)
     }
 

packages/ui/src/views/BrowseByFolder/index.tsx

@@ -6,6 +6,7 @@ import type { FolderListViewClientProps } from 'payload'
 import { useDndMonitor } from '@dnd-kit/core'
 import { getTranslation } from '@payloadcms/translations'
 import { useRouter } from 'next/navigation.js'
+import { PREFERENCE_KEYS } from 'payload/shared'
 import React, { Fragment } from 'react'
 
 import { DroppableBreadcrumb } from '../../elements/FolderView/Breadcrumbs/index.js'
@@ -171,7 +172,7 @@ function BrowseByFolderViewInContext(props: BrowseByFolderViewInContextProps) {
 
   const handleSetViewType = React.useCallback(
     (view: 'grid' | 'list') => {
-      void setPreference('browse-by-folder', {
+      void setPreference(PREFERENCE_KEYS.BROWSE_BY_FOLDER, {
         viewPreference: view,
       })
       setActiveView(view)