fix(richtext-lexical): strip server-only properties from blocks in lexical client schema map (#15756)

AlessioGr · web-flow · commit c05ace22b321 · 2026-02-25T16:43:19.000Z
Fixes #15509 When a block used in `BlocksFeature` contains a nested `blocks` field with `blockReferences`, the admin panel crashes with "Functions cannot be passed directly to Client Components". This happens because the richText schema map conversion in `buildClientFieldSchemaMap` treats all entries as `Field` objects via an unsafe `as Field` cast. Block entries (which have `slug` but no `type`) pass through `createClientField` which doesn't understand them, causing `flattenedFields` - containing server-only properties - to be copied to the client. The fix replaces the unsafe cast with type-safe union discrimination on the `FieldSchemaMap` value type (`Block | Field | Tab | { fields }`) using `in` narrowing. Block entries are now routed through `createClientBlocks` which correctly strips server-only properties, while Field and fields-wrapper entries continue through `createClientFields` as before.
diff --git a/packages/payload/src/index.ts b/packages/payload/src/index.ts
@@ -1518,6 +1518,7 @@ export { slugField, type SlugFieldClientProps } from './fields/baseFields/slug/i
 export { type SlugField } from './fields/baseFields/slug/index.js'
 
 export {
+  createClientBlocks,
   createClientField,
   createClientFields,
   type ServerOnlyFieldAdminProperties,
diff --git a/packages/ui/src/utilities/buildClientFieldSchemaMap/traverseFields.ts b/packages/ui/src/utilities/buildClientFieldSchemaMap/traverseFields.ts
@@ -1,15 +1,15 @@
 import type { I18n } from '@payloadcms/translations'
 import type {
+  ClientBlock,
   ClientConfig,
   ClientField,
   ClientFieldSchemaMap,
-  Field,
   FieldSchemaMap,
   Payload,
   TabAsFieldClient,
 } from 'payload'
 
-import { createClientFields } from 'payload'
+import { createClientBlocks, createClientFields } from 'payload'
 import { fieldAffectsData, getFieldPaths, tabHasName } from 'payload/shared'
 
 type Args = {
@@ -143,27 +143,49 @@ export const traverseFields = ({
           }
         }
 
-        // Now loop through them, convert each entry to a client field and add it to the client schema map
+        // Now loop through them, convert each entry to a client field and add it to the client schema map.
+        // Schema map values are a union: Block | Field | Tab | { fields: Field[] }.
+        // Each variant needs different conversion to strip server-only properties.
         for (const [path, subField] of richTextFieldSchemaMap.entries()) {
-          // check if fields is the only key in the subField object
-          const isFieldsOnly = Object.keys(subField).length === 1 && 'fields' in subField
+          if ('slug' in subField) {
+            const clientBlocks = createClientBlocks({
+              blocks: [subField],
+              defaultIDType: payload.config.db.defaultIDType,
+              i18n,
+              importMap: payload.importMap,
+            })
+
+            clientSchemaMap.set(path, clientBlocks[0] as ClientBlock)
+            continue
+          }
 
-          const clientFields = createClientFields({
-            defaultIDType: payload.config.db.defaultIDType,
-            disableAddingID: true,
-            fields: isFieldsOnly ? subField.fields : [subField as Field],
-            i18n,
-            importMap: payload.importMap,
-          })
+          if ('type' in subField) {
+            const clientFields = createClientFields({
+              defaultIDType: payload.config.db.defaultIDType,
+              disableAddingID: true,
+              fields: [subField],
+              i18n,
+              importMap: payload.importMap,
+            })
+
+            clientSchemaMap.set(path, clientFields[0])
+            continue
+          }
+
+          if ('fields' in subField) {
+            const clientFields = createClientFields({
+              defaultIDType: payload.config.db.defaultIDType,
+              disableAddingID: true,
+              fields: subField.fields,
+              i18n,
+              importMap: payload.importMap,
+            })
+
+            clientSchemaMap.set(path, { fields: clientFields })
+            continue
+          }
 
-          clientSchemaMap.set(
-            path,
-            isFieldsOnly
-              ? {
-                  fields: clientFields,
-                }
-              : clientFields[0],
-          )
+          subField satisfies never
         }
         break
       }
diff --git a/test/lexical/baseConfig.ts b/test/lexical/baseConfig.ts
@@ -21,6 +21,11 @@ import { LexicalLinkFeature } from './collections/LexicalLinkFeature/index.js'
 import { LexicalListsFeature } from './collections/LexicalListsFeature/index.js'
 import { LexicalLocalizedFields } from './collections/LexicalLocalized/index.js'
 import { LexicalMigrateFields } from './collections/LexicalMigrate/index.js'
+import {
+  BlockWithBlockRef,
+  LexicalNestedBlocks,
+  NestedBlock,
+} from './collections/LexicalNestedBlocks/index.js'
 import { LexicalObjectReferenceBugCollection } from './collections/LexicalObjectReferenceBug/index.js'
 import { LexicalRelationshipsFields } from './collections/LexicalRelationships/index.js'
 import { OnDemandForm } from './collections/OnDemandForm/index.js'
@@ -36,6 +41,7 @@ const dirname = path.dirname(filename)
 
 export const baseConfig: Partial<Config> = {
   // ...extend config here
+  blocks: [NestedBlock, BlockWithBlockRef],
   collections: [
     LexicalFullyFeatured,
     LexicalAutosave,
@@ -53,6 +59,7 @@ export const baseConfig: Partial<Config> = {
     LexicalInBlock,
     LexicalAccessControl,
     LexicalRelationshipsFields,
+    LexicalNestedBlocks,
     RichTextFields,
     TextFields,
     Uploads,
diff --git a/test/lexical/collections/Lexical/e2e/blocks/e2e.spec.ts b/test/lexical/collections/Lexical/e2e/blocks/e2e.spec.ts
@@ -32,7 +32,7 @@ import { reInitializeDB } from '../../../../../__helpers/shared/clearAndSeed/reI
 import { initPayloadE2ENoConfig } from '../../../../../__helpers/shared/initPayloadE2ENoConfig.js'
 import { RESTClient } from '../../../../../__helpers/shared/rest.js'
 import { POLL_TOPASS_TIMEOUT, TEST_TIMEOUT_LONG } from '../../../../../playwright.config.js'
-import { lexicalFieldsSlug } from '../../../../slugs.js'
+import { lexicalFieldsSlug, lexicalNestedBlocksSlug } from '../../../../slugs.js'
 import { lexicalDocData } from '../../data.js'
 
 const filename = fileURLToPath(import.meta.url)
@@ -1295,6 +1295,36 @@ describe('lexicalBlocks', () => {
       ).toHaveText('Some Description')
     })
 
+    test('should render block with nested blocks field using blockReferences without crashing', async () => {
+      // https://github.com/payloadcms/payload/issues/15509
+      const url = new AdminUrlUtil(serverURL, lexicalNestedBlocksSlug)
+
+      await page.goto(url.create)
+      await waitForFormReady(page)
+
+      const richTextField = page.locator('.rich-text-lexical').first()
+      await expect(richTextField).toBeVisible()
+
+      const contentEditable = richTextField.locator('[contenteditable="true"]').first()
+      await contentEditable.click()
+
+      await page.keyboard.press('/')
+      await page.keyboard.type('blockwithblockref')
+
+      const slashMenuPopover = page.locator('#slash-menu .slash-menu-popup')
+      await expect(slashMenuPopover).toBeVisible()
+
+      const blockSelectButton = slashMenuPopover.locator('button').first()
+      await expect(blockSelectButton).toBeVisible()
+      await blockSelectButton.click()
+      await expect(slashMenuPopover).toBeHidden()
+
+      const newBlock = richTextField.locator('.LexicalEditorTheme__block').first()
+      await expect(newBlock).toBeVisible()
+
+      await expect(newBlock.locator('button:has-text("Add Nested Block")')).toBeVisible()
+    })
+
     test('ensure individual inline blocks in lexical editor within a block have initial state on initial load', async () => {
       await page.goto('http://localhost:3000/admin/collections/LexicalInBlock?limit=10')
 
diff --git a/test/lexical/collections/LexicalNestedBlocks/index.ts b/test/lexical/collections/LexicalNestedBlocks/index.ts
@@ -0,0 +1,56 @@
+import type { Block, BlockSlug, CollectionConfig } from 'payload'
+
+import { BlocksFeature, lexicalEditor } from '@payloadcms/richtext-lexical'
+
+import { lexicalNestedBlocksSlug } from '../../slugs.js'
+
+export const NestedBlock: Block = {
+  slug: 'nestedBlock',
+  fields: [
+    {
+      name: 'text',
+      type: 'text',
+    },
+  ],
+}
+
+export const BlockWithBlockRef: Block = {
+  slug: 'blockWithBlockRef',
+  fields: [
+    {
+      name: 'nestedBlocks',
+      type: 'blocks',
+      blockReferences: ['nestedBlock'],
+      blocks: [],
+    },
+  ],
+}
+
+export const LexicalNestedBlocks: CollectionConfig = {
+  slug: lexicalNestedBlocksSlug,
+  access: {
+    read: () => true,
+  },
+  admin: {
+    useAsTitle: 'title',
+  },
+  fields: [
+    {
+      name: 'title',
+      type: 'text',
+      required: true,
+    },
+    {
+      name: 'richText',
+      type: 'richText',
+      editor: lexicalEditor({
+        features: ({ defaultFeatures }) => [
+          ...defaultFeatures,
+          BlocksFeature({
+            blocks: ['blockWithBlockRef' as BlockSlug],
+          }),
+        ],
+      }),
+    },
+  ],
+}
diff --git a/test/lexical/config.blockreferences.ts b/test/lexical/config.blockreferences.ts
@@ -2,8 +2,8 @@
 
 import type { BlockSlug } from 'payload'
 
-import { buildConfigWithDefaults } from '../buildConfigWithDefaults.js'
 import { autoDedupeBlocksPlugin } from '../__helpers/shared/autoDedupeBlocksPlugin/index.js'
+import { buildConfigWithDefaults } from '../buildConfigWithDefaults.js'
 import { baseConfig } from './baseConfig.js'
 import {
   getLexicalFieldsCollection,
diff --git a/test/lexical/payload-types.ts b/test/lexical/payload-types.ts
@@ -81,7 +81,10 @@ export interface Config {
   auth: {
     users: UserAuthOperations;
   };
-  blocks: {};
+  blocks: {
+    nestedBlock: NestedBlock;
+    blockWithBlockRef: BlockWithBlockRef;
+  };
   collections: {
     'lexical-fully-featured': LexicalFullyFeatured;
     'lexical-autosave': LexicalAutosave;
@@ -96,6 +99,7 @@ export interface Config {
     LexicalInBlock: LexicalInBlock;
     'lexical-access-control': LexicalAccessControl;
     'lexical-relationship-fields': LexicalRelationshipField;
+    'lexical-nested-blocks': LexicalNestedBlock;
     'rich-text-fields': RichTextField;
     'text-fields': TextField;
     uploads: Upload;
@@ -124,6 +128,7 @@ export interface Config {
     LexicalInBlock: LexicalInBlockSelect<false> | LexicalInBlockSelect<true>;
     'lexical-access-control': LexicalAccessControlSelect<false> | LexicalAccessControlSelect<true>;
     'lexical-relationship-fields': LexicalRelationshipFieldsSelect<false> | LexicalRelationshipFieldsSelect<true>;
+    'lexical-nested-blocks': LexicalNestedBlocksSelect<false> | LexicalNestedBlocksSelect<true>;
     'rich-text-fields': RichTextFieldsSelect<false> | RichTextFieldsSelect<true>;
     'text-fields': TextFieldsSelect<false> | TextFieldsSelect<true>;
     uploads: UploadsSelect<false> | UploadsSelect<true>;
@@ -172,6 +177,33 @@ export interface UserAuthOperations {
     password: string;
   };
 }
+/**
+ * This interface was referenced by `Config`'s JSON-Schema
+ * via the `definition` "nestedBlock".
+ */
+export interface NestedBlock {
+  text?: string | null;
+  id?: string | null;
+  blockName?: string | null;
+  blockType: 'nestedBlock';
+}
+/**
+ * This interface was referenced by `Config`'s JSON-Schema
+ * via the `definition` "blockWithBlockRef".
+ */
+export interface BlockWithBlockRef {
+  nestedBlocks?:
+    | {
+        text?: string | null;
+        id?: string | null;
+        blockName?: string | null;
+        blockType: 'nestedBlock';
+      }[]
+    | null;
+  id?: string | null;
+  blockName?: string | null;
+  blockType: 'blockWithBlockRef';
+}
 /**
  * This interface was referenced by `Config`'s JSON-Schema
  * via the `definition` "lexical-fully-featured".
@@ -706,6 +738,31 @@ export interface LexicalRelationshipField {
   createdAt: string;
   _status?: ('draft' | 'published') | null;
 }
+/**
+ * This interface was referenced by `Config`'s JSON-Schema
+ * via the `definition` "lexical-nested-blocks".
+ */
+export interface LexicalNestedBlock {
+  id: string;
+  title: string;
+  richText?: {
+    root: {
+      type: string;
+      children: {
+        type: any;
+        version: number;
+        [k: string]: unknown;
+      }[];
+      direction: ('ltr' | 'rtl') | null;
+      format: 'left' | 'start' | 'center' | 'right' | 'end' | 'justify' | '';
+      indent: number;
+      version: number;
+    };
+    [k: string]: unknown;
+  } | null;
+  updatedAt: string;
+  createdAt: string;
+}
 /**
  * This interface was referenced by `Config`'s JSON-Schema
  * via the `definition` "rich-text-fields".
@@ -1130,6 +1187,10 @@ export interface PayloadLockedDocument {
         relationTo: 'lexical-relationship-fields';
         value: string | LexicalRelationshipField;
       } | null)
+    | ({
+        relationTo: 'lexical-nested-blocks';
+        value: string | LexicalNestedBlock;
+      } | null)
     | ({
         relationTo: 'rich-text-fields';
         value: string | RichTextField;
@@ -1368,6 +1429,16 @@ export interface LexicalRelationshipFieldsSelect<T extends boolean = true> {
   createdAt?: T;
   _status?: T;
 }
+/**
+ * This interface was referenced by `Config`'s JSON-Schema
+ * via the `definition` "lexical-nested-blocks_select".
+ */
+export interface LexicalNestedBlocksSelect<T extends boolean = true> {
+  title?: T;
+  richText?: T;
+  updatedAt?: T;
+  createdAt?: T;
+}
 /**
  * This interface was referenced by `Config`'s JSON-Schema
  * via the `definition` "rich-text-fields_select".
diff --git a/test/lexical/slugs.ts b/test/lexical/slugs.ts
@@ -21,6 +21,8 @@ export const uploads2Slug = 'uploads2'
 
 export const arrayFieldsSlug = 'array-fields'
 
+export const lexicalNestedBlocksSlug = 'lexical-nested-blocks'
+
 export const collectionSlugs = [
   lexicalFieldsSlug,
   lexicalLocalizedFieldsSlug,
