perf: deduplicate blocks used in multiple places using new config.blocks property (#10905)

If you have multiple blocks that are used in multiple places, this can quickly blow up the size of your Payload Config. This will incur a performance hit, as more data is
1.  sent to the client (=> bloated `ClientConfig` and large initial html) and
2. processed on the server (permissions are calculated every single time you navigate to a page - this iterates through all blocks you have defined, even if they're duplicative)

This can be optimized by defining your block **once** in your Payload Config, and just referencing the block slug whenever it's used, instead of passing the entire block config. To do this, the block can be defined in the `blocks` array of the Payload Config. The slug can then be passed to the `blockReferences` array in the Blocks Field - the `blocks` array has to be empty for compatibility reasons.

```ts
import { buildConfig } from 'payload'
import { lexicalEditor, BlocksFeature } from '@payloadcms/richtext-lexical'

// Payload Config
const config = buildConfig({
  // Define the block once
  blocks: [
    {
      slug: 'TextBlock',
      fields: [
        {
          name: 'text',
          type: 'text',
        },
      ],
    },
  ],
  collections: [
    {
      slug: 'collection1',
      fields: [
        {
          name: 'content',
          type: 'blocks',
          // Reference the block by slug
          blockReferences: ['TextBlock'],
          blocks: [], // Required to be empty, for compatibility reasons
        },
      ],
    },
     {
      slug: 'collection2',
      fields: [
        {
          name: 'editor',
          type: 'richText',
          editor: lexicalEditor({
            BlocksFeature({
              // Same reference can be reused anywhere, even in the lexical editor, without incurred performance hit
              blocks: ['TextBlock'],
            })
          })
        },
      ],
    },
  ],
})
```

## v4.0 Plans

In 4.0, we will remove the `blockReferences` property, and allow string block references to be passed directly to the blocks `property`. Essentially, we'd remove the `blocks` property and rename `blockReferences` to `blocks`.

The reason we opted to a new property in this PR is to avoid breaking changes. Allowing strings to be passed to the `blocks` property will prevent plugins that iterate through fields / blocks from compiling.

## PR Changes

- Testing: This PR introduces a plugin that automatically converts blocks to block references. This is done in the fields__blocks test suite, to run our existing test suite using block references.

- Block References support: Most changes are similar. Everywhere we iterate through blocks, we have to now do the following:
1. Check if `field.blockReferences` is provided. If so, only iterate through that.
2. Check if the block is an object (= actual block), or string
3. If it's a string, pull the actual block from the Payload Config or from `payload.blocks`.

The exception is config sanitization and block type generations. This PR optimizes them so that each block is only handled once, instead of every time the block is referenced.

## Benchmarks

60 Block fields, each block field having the same 600 Blocks.

### Before:
**Initial HTML:** 195 kB
**Generated types:** takes 11 minutes, 461,209 lines

https://github.com/user-attachments/assets/11d49a4e-5414-4579-8050-e6346e552f56

### After:
**Initial HTML:** 73.6 kB
**Generated types:** takes 2 seconds, 35,810 lines

https://github.com/user-attachments/assets/3eab1a99-6c29-489d-add5-698df67780a3

### After Permissions Optimization (follow-up PR)
Initial HTML: 73.6 kB

https://github.com/user-attachments/assets/a909202e-45a8-4bf6-9a38-8c85813f1312


## Future Plans

1. This PR does not yet deduplicate block references during permissions calculation. We'll optimize that in a separate PR, as this one is already large enough
2. The same optimization can be done to deduplicate fields. One common use-case would be link field groups that may be referenced in multiple entities, outside of blocks. We might explore adding a new `fieldReferences` property, that allows you to reference those same `config.blocks`.

test/benchmark-blocks/.gitignore

@@ -0,0 +1,2 @@
+/media
+/media-gif

test/benchmark-blocks/blocks/blocks.ts

@@ -0,0 +1,61 @@
+import type { Block, BlocksField, BlockSlug } from 'payload'
+
+export const generateBlocks = (
+  blockCount: number,
+  useReferences?: boolean,
+): (Block | BlockSlug)[] => {
+  const blocks: (Block | BlockSlug)[] = []
+
+  for (let i = 0; i < blockCount; i++) {
+    if (useReferences) {
+      blocks.push(`block_${i}` as BlockSlug)
+    } else {
+      blocks.push({
+        slug: `block_${i}`,
+        fields: [
+          {
+            name: 'field1',
+            type: 'text',
+          },
+          {
+            name: 'field2',
+            type: 'text',
+          },
+          {
+            name: 'field3',
+            type: 'text',
+          },
+          {
+            name: 'field4',
+            type: 'number',
+          },
+        ],
+      })
+    }
+  }
+
+  return blocks
+}
+export const generateBlockFields = (
+  blockCount: number,
+  containerCount: number,
+  useReferences?: boolean,
+): BlocksField[] => {
+  const fields: BlocksField[] = []
+  for (let i = 0; i < containerCount; i++) {
+    const block: BlocksField = {
+      name: `blocksfield_${i}`,
+      type: 'blocks',
+      blocks: [],
+    }
+
+    if (useReferences) {
+      block.blockReferences = generateBlocks(blockCount, true)
+    } else {
+      block.blocks = generateBlocks(blockCount) as any
+    }
+    fields.push(block)
+  }
+
+  return fields
+}

test/benchmark-blocks/collections/Media/index.ts

@@ -0,0 +1,33 @@
+import type { CollectionConfig } from 'payload'
+
+export const mediaSlug = 'media'
+
+export const MediaCollection: CollectionConfig = {
+  slug: mediaSlug,
+  access: {
+    create: () => true,
+    read: () => true,
+  },
+  fields: [],
+  upload: {
+    crop: true,
+    focalPoint: true,
+    imageSizes: [
+      {
+        name: 'thumbnail',
+        height: 200,
+        width: 200,
+      },
+      {
+        name: 'medium',
+        height: 800,
+        width: 800,
+      },
+      {
+        name: 'large',
+        height: 1200,
+        width: 1200,
+      },
+    ],
+  },
+}

test/benchmark-blocks/collections/Posts/index.ts

@@ -0,0 +1,28 @@
+import type { CollectionConfig } from 'payload'
+
+import { lexicalEditor } from '@payloadcms/richtext-lexical'
+
+export const postsSlug = 'posts'
+
+export const PostsCollection: CollectionConfig = {
+  slug: postsSlug,
+  admin: {
+    useAsTitle: 'title',
+  },
+  fields: [
+    {
+      name: 'title',
+      type: 'text',
+    },
+    {
+      name: 'content',
+      type: 'richText',
+      editor: lexicalEditor({
+        features: ({ defaultFeatures }) => [...defaultFeatures],
+      }),
+    },
+  ],
+  versions: {
+    drafts: true,
+  },
+}

test/benchmark-blocks/config.ts

@@ -0,0 +1,56 @@
+import { lexicalEditor } from '@payloadcms/richtext-lexical'
+import { fileURLToPath } from 'node:url'
+import path from 'path'
+
+import { buildConfigWithDefaults } from '../buildConfigWithDefaults.js'
+import { devUser } from '../credentials.js'
+import { generateBlockFields, generateBlocks } from './blocks/blocks.js'
+import { MediaCollection } from './collections/Media/index.js'
+import { PostsCollection, postsSlug } from './collections/Posts/index.js'
+
+const filename = fileURLToPath(import.meta.url)
+const dirname = path.dirname(filename)
+
+const USE_BLOCK_REFERENCES = true
+
+export default buildConfigWithDefaults({
+  collections: [
+    PostsCollection,
+    {
+      slug: 'pages',
+      access: {
+        create: () => true,
+        read: () => true,
+      },
+      fields: generateBlockFields(40, 30 * 20, USE_BLOCK_REFERENCES),
+    },
+    MediaCollection,
+  ],
+  admin: {
+    importMap: {
+      baseDir: path.resolve(dirname),
+    },
+  },
+  editor: lexicalEditor({}),
+  // @ts-expect-error
+  blocks: USE_BLOCK_REFERENCES ? generateBlocks(30 * 20, false) : undefined,
+  onInit: async (payload) => {
+    await payload.create({
+      collection: 'users',
+      data: {
+        email: devUser.email,
+        password: devUser.password,
+      },
+    })
+
+    await payload.create({
+      collection: postsSlug,
+      data: {
+        title: 'example post',
+      },
+    })
+  },
+  typescript: {
+    outputFile: path.resolve(dirname, 'payload-types.ts'),
+  },
+})

test/benchmark-blocks/eslint.config.js

@@ -0,0 +1,19 @@
+import { rootParserOptions } from '../../eslint.config.js'
+import { testEslintConfig } from '../eslint.config.js'
+
+/** @typedef {import('eslint').Linter.Config} Config */
+
+/** @type {Config[]} */
+export const index = [
+  ...testEslintConfig,
+  {
+    languageOptions: {
+      parserOptions: {
+        ...rootParserOptions,
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+  },
+]
+
+export default index

test/benchmark-blocks/tsconfig.eslint.json

@@ -0,0 +1,13 @@
+{
+  // extend your base config to share compilerOptions, etc
+  //"extends": "./tsconfig.json",
+  "compilerOptions": {
+    // ensure that nobody can accidentally use this config for a build
+    "noEmit": true
+  },
+  "include": [
+    // whatever paths you intend to lint
+    "./**/*.ts",
+    "./**/*.tsx"
+  ]
+}

test/benchmark-blocks/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "../tsconfig.json",
+}

test/benchmark-blocks/types.d.ts

@@ -0,0 +1,9 @@
+import type { RequestContext as OriginalRequestContext } from 'payload'
+
+declare module 'payload' {
+  // Create a new interface that merges your additional fields with the original one
+  export interface RequestContext extends OriginalRequestContext {
+    myObject?: string
+    // ...
+  }
+}