feat(richtext-lexical)!: remove deprecated HTMLConverterFeature by AlessioGr · Pull Request #16548 · payloadcms/payload

AlessioGr · 2026-05-08T04:59:00Z

BREAKING: removes the deprecated HTMLConverterFeature, lexicalHTML and the per-node converters.html API. Use convertLexicalToHTML and lexicalHTMLField from the non-deprecated converter instead.

Migration

- import { HTMLConverterFeature, lexicalHTML, convertLexicalToHTML } from '@payloadcms/richtext-lexical'
+ import { lexicalHTMLField, convertLexicalToHTML } from '@payloadcms/richtext-lexical'

  editor: lexicalEditor({
    features: ({ defaultFeatures }) => [
      ...defaultFeatures,
-     HTMLConverterFeature({}),
    ],
  }),

  fields: [
    { name: 'content', type: 'richText' },
-   lexicalHTML('content', { name: 'content_html' }),
+   lexicalHTMLField({ htmlFieldName: 'content_html', lexicalFieldName: 'content' }),
  ]

Custom nodes defining converters.html should export their converters instead.

To see the specific tasks where the Asana app for GitHub is being used, see below:
- https://app.asana.com/0/0/1214260152843236

AlessioGr · 2026-05-08T05:00:19Z

  { file: 'lexical__collections__Lexical__e2e__main', shards: 2 },
  { file: 'lexical__collections__Lexical__e2e__blocks', shards: 2 },
  { file: 'lexical__collections__Lexical__e2e__blocks#config.blockreferences.ts', shards: 2 },
-  { file: 'lexical__collections__RichText', shards: 1 },


this one only had a single test remaining that used this deprecated HTMLConverterFeature

github-actions · 2026-05-08T05:07:39Z

📦 esbuild Bundle Analysis for payload

This analysis was generated by esbuild-bundle-analyzer. 🤖

Meta File	Out File	Size (raw)	Note
packages/next/meta_index.json	esbuild/index.js	990.16 KB	🆕 Added
packages/payload/meta_index.json	esbuild/index.js	1.40 MB	🆕 Added
packages/payload/meta_shared.json	esbuild/exports/shared.js	192.48 KB	🆕 Added
packages/richtext-lexical/meta_client.json	esbuild/exports/client_optimized/index.js	293.43 KB	🆕 Added
packages/ui/meta_client.json	esbuild/exports/client_optimized/index.js	1.24 MB	🆕 Added
packages/ui/meta_shared.json	esbuild/exports/shared_optimized/index.js	16.32 KB	🆕 Added

Largest paths

These visualization shows top 20 largest paths in the bundle.

Meta file: packages/next/meta_index.json, Out file: esbuild/index.js

Path	Size
../../node_modules	${{\color{Goldenrod}{ ████████████████████▍ }}}$ 81.9%, 807.52 KB
dist/views/Version	${{\color{Goldenrod}{ █▎ }}}$ 5.2%, 51.49 KB
dist/views/Dashboard	${{\color{Goldenrod}{ ▌ }}}$ 2.2%, 21.38 KB
dist/views/Document	${{\color{Goldenrod}{ ▍ }}}$ 1.7%, 16.66 KB
dist/views/List	${{\color{Goldenrod}{ ▍ }}}$ 1.6%, 15.34 KB
dist/elements/Nav	${{\color{Goldenrod}{ ▎ }}}$ 1.1%, 10.87 KB
dist/views/Root	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 9.90 KB
dist/views/Versions	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 6.17 KB
dist/views/API	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 6.13 KB
dist/views/Account	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 6.06 KB
dist/elements/DocumentHeader	${{\color{Goldenrod}{ ▏ }}}$ 0.5%, 4.71 KB
dist/views/Login	${{\color{Goldenrod}{ }}}$ 0.4%, 4.40 KB
dist/layouts/Root	${{\color{Goldenrod}{ }}}$ 0.4%, 3.50 KB
dist/views/ForgotPassword	${{\color{Goldenrod}{ }}}$ 0.3%, 3.13 KB
dist/views/CreateFirstUser	${{\color{Goldenrod}{ }}}$ 0.3%, 2.81 KB
dist/templates/Default	${{\color{Goldenrod}{ }}}$ 0.3%, 2.64 KB
dist/views/ResetPassword	${{\color{Goldenrod}{ }}}$ 0.2%, 2.40 KB
dist/views/Logout	${{\color{Goldenrod}{ }}}$ 0.2%, 1.94 KB
dist/views/Verify	${{\color{Goldenrod}{ }}}$ 0.1%, 1.29 KB
dist/views/NotFound	${{\color{Goldenrod}{ }}}$ 0.1%, 1.21 KB
(other)	${{\color{Goldenrod}{ ████▌ }}}$ 18.1%, 177.96 KB

Meta file: packages/payload/meta_index.json, Out file: esbuild/index.js

Path	Size
../../node_modules	${{\color{Goldenrod}{ █████████████████ }}}$ 68.2%, 953.25 KB
dist/fields/hooks	${{\color{Goldenrod}{ ▊ }}}$ 3.2%, 44.07 KB
dist/collections/operations	${{\color{Goldenrod}{ ▋ }}}$ 2.9%, 40.23 KB
dist/versions/migrations	${{\color{Goldenrod}{ ▎ }}}$ 1.3%, 18.50 KB
dist/auth/operations	${{\color{Goldenrod}{ ▎ }}}$ 1.1%, 15.63 KB
dist/fields/config	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 13.85 KB
dist/globals/operations	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 13.40 KB
dist/utilities/configToJSONSchema.js	${{\color{Goldenrod}{ ▏ }}}$ 0.9%, 13.13 KB
dist/queues/operations	${{\color{Goldenrod}{ ▏ }}}$ 0.9%, 12.63 KB
dist/fields/validations.js	${{\color{Goldenrod}{ ▏ }}}$ 0.8%, 10.57 KB
dist/collections/config	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 9.53 KB
dist/bin/generateImportMap	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 9.44 KB
dist/config/orderable	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.92 KB
dist/uploads/fetchAPI-multipart	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.80 KB
dist/index.js	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.77 KB
dist/hierarchy/utils	${{\color{Goldenrod}{ ▏ }}}$ 0.5%, 7.65 KB
dist/database/migrations	${{\color{Goldenrod}{ ▏ }}}$ 0.5%, 7.54 KB
dist/collections/endpoints	${{\color{Goldenrod}{ }}}$ 0.4%, 6.23 KB
dist/auth/strategies	${{\color{Goldenrod}{ }}}$ 0.4%, 5.50 KB
dist/config/sanitize.js	${{\color{Goldenrod}{ }}}$ 0.4%, 5.39 KB
(other)	${{\color{Goldenrod}{ ███████▉ }}}$ 31.8%, 444.01 KB

Meta file: packages/payload/meta_shared.json, Out file: esbuild/exports/shared.js

Path	Size
../../node_modules	${{\color{Goldenrod}{ ███████████████████▉ }}}$ 79.5%, 150.11 KB
dist/fields/validations.js	${{\color{Goldenrod}{ █▍ }}}$ 5.6%, 10.57 KB
dist/config/orderable	${{\color{Goldenrod}{ ▍ }}}$ 1.7%, 3.13 KB
dist/fields/baseFields	${{\color{Goldenrod}{ ▍ }}}$ 1.5%, 2.79 KB
dist/utilities/deepCopyObject.js	${{\color{Goldenrod}{ ▎ }}}$ 1.3%, 2.54 KB
dist/auth/cookies.js	${{\color{Goldenrod}{ ▏ }}}$ 0.8%, 1.55 KB
dist/utilities/flattenTopLevelFields.js	${{\color{Goldenrod}{ ▏ }}}$ 0.8%, 1.42 KB
dist/fields/config	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 1.37 KB
dist/utilities/getVersionsConfig.js	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 1.04 KB
dist/utilities/flattenAllFields.js	${{\color{Goldenrod}{ ▏ }}}$ 0.5%, 943 B
dist/utilities/unflatten.js	${{\color{Goldenrod}{ }}}$ 0.4%, 779 B
dist/utilities/sanitizeUserDataForEmail.js	${{\color{Goldenrod}{ }}}$ 0.4%, 713 B
dist/utilities/getFieldPermissions.js	${{\color{Goldenrod}{ }}}$ 0.3%, 651 B
dist/collections/config	${{\color{Goldenrod}{ }}}$ 0.3%, 570 B
dist/bin/generateImportMap	${{\color{Goldenrod}{ }}}$ 0.3%, 561 B
dist/auth/sessions.js	${{\color{Goldenrod}{ }}}$ 0.3%, 525 B
dist/fields/getFieldPaths.js	${{\color{Goldenrod}{ }}}$ 0.3%, 485 B
dist/utilities/appendDateTimezoneSelectFields.js	${{\color{Goldenrod}{ }}}$ 0.2%, 451 B
dist/utilities/getSafeRedirect.js	${{\color{Goldenrod}{ }}}$ 0.2%, 423 B
dist/utilities/deepMerge.js	${{\color{Goldenrod}{ }}}$ 0.2%, 413 B
(other)	${{\color{Goldenrod}{ █████▏ }}}$ 20.5%, 38.62 KB

Meta file: packages/richtext-lexical/meta_client.json, Out file: esbuild/exports/client_optimized/index.js

Path	Size
dist/features/blocks	${{\color{Goldenrod}{ ███▏ }}}$ 12.6%, 36.44 KB
dist/lexical/plugins	${{\color{Goldenrod}{ ██▊ }}}$ 11.2%, 32.65 KB
dist/lexical/ui	${{\color{Goldenrod}{ ██▋ }}}$ 10.5%, 30.52 KB
dist/features/experimental_table	${{\color{Goldenrod}{ ██ }}}$ 8.2%, 23.70 KB
dist/packages/@lexical	${{\color{Goldenrod}{ █▋ }}}$ 6.5%, 18.99 KB
dist/features/link	${{\color{Goldenrod}{ █▌ }}}$ 6.4%, 18.53 KB
dist/features/toolbars	${{\color{Goldenrod}{ █▍ }}}$ 5.5%, 16.08 KB
dist/features/upload	${{\color{Goldenrod}{ █▏ }}}$ 4.7%, 13.77 KB
dist/features/textState	${{\color{Goldenrod}{ ▉ }}}$ 3.8%, 11.08 KB
dist/features/relationship	${{\color{Goldenrod}{ ▊ }}}$ 3.1%, 9.03 KB
dist/lexical/utils	${{\color{Goldenrod}{ ▊ }}}$ 3.0%, 8.79 KB
dist/features/converters	${{\color{Goldenrod}{ ▋ }}}$ 2.9%, 8.36 KB
dist/features/debug	${{\color{Goldenrod}{ ▋ }}}$ 2.5%, 7.40 KB
dist/utilities/fieldsDrawer	${{\color{Goldenrod}{ ▋ }}}$ 2.5%, 7.15 KB
dist/lexical/config	${{\color{Goldenrod}{ ▍ }}}$ 1.8%, 5.08 KB
dist/features/lists	${{\color{Goldenrod}{ ▍ }}}$ 1.7%, 5.00 KB
dist/features/format	${{\color{Goldenrod}{ ▎ }}}$ 1.2%, 3.46 KB
dist/lexical/LexicalEditor.js	${{\color{Goldenrod}{ ▎ }}}$ 1.1%, 3.23 KB
dist/field/Field.js	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 2.81 KB
dist/lexical/nodes	${{\color{Goldenrod}{ ▏ }}}$ 0.9%, 2.66 KB
(other)	${{\color{Goldenrod}{ █████████████████████▊ }}}$ 87.4%, 253.76 KB

Meta file: packages/ui/meta_client.json, Out file: esbuild/exports/client_optimized/index.js

Path	Size
../../node_modules	${{\color{Goldenrod}{ ███████████▊ }}}$ 47.2%, 579.26 KB
dist/elements/Hierarchy	${{\color{Goldenrod}{ ▉ }}}$ 3.6%, 44.30 KB
dist/elements/BulkUpload	${{\color{Goldenrod}{ ▌ }}}$ 2.3%, 28.33 KB
dist/views/HierarchyList	${{\color{Goldenrod}{ ▍ }}}$ 1.5%, 18.86 KB
dist/elements/Table	${{\color{Goldenrod}{ ▍ }}}$ 1.5%, 18.23 KB
dist/views/Edit	${{\color{Goldenrod}{ ▎ }}}$ 1.4%, 17.38 KB
dist/elements/WhereBuilder	${{\color{Goldenrod}{ ▎ }}}$ 1.4%, 17.36 KB
dist/forms/Form	${{\color{Goldenrod}{ ▎ }}}$ 1.3%, 15.92 KB
dist/fields/Relationship	${{\color{Goldenrod}{ ▎ }}}$ 1.3%, 15.83 KB
dist/fields/Blocks	${{\color{Goldenrod}{ ▎ }}}$ 1.2%, 15.13 KB
dist/fields/Upload	${{\color{Goldenrod}{ ▎ }}}$ 1.2%, 14.44 KB
dist/elements/QueryPresets	${{\color{Goldenrod}{ ▏ }}}$ 0.8%, 10.36 KB
dist/elements/PublishButton	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 9.09 KB
dist/elements/HTMLDiff	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 8.38 KB
dist/views/List	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 8.10 KB
dist/fields/Array	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.77 KB
dist/elements/ReactSelect	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.74 KB
dist/elements/LivePreview	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.04 KB
dist/elements/Upload	${{\color{Goldenrod}{ ▏ }}}$ 0.5%, 6.67 KB
dist/elements/RelationshipTable	${{\color{Goldenrod}{ ▏ }}}$ 0.5%, 6.28 KB
(other)	${{\color{Goldenrod}{ █████████████▏ }}}$ 52.8%, 647.17 KB

Meta file: packages/ui/meta_shared.json, Out file: esbuild/exports/shared_optimized/index.js

Path	Size
dist/graphics/Logo	${{\color{Goldenrod}{ █████ }}}$ 20.0%, 3.12 KB
../../node_modules	${{\color{Goldenrod}{ ████▎ }}}$ 17.0%, 2.65 KB
dist/graphics/Icon	${{\color{Goldenrod}{ ██▍ }}}$ 9.8%, 1.52 KB
dist/utilities/formatDocTitle	${{\color{Goldenrod}{ ██▏ }}}$ 8.5%, 1.32 KB
dist/providers/TableColumns	${{\color{Goldenrod}{ █▍ }}}$ 5.5%, 866 B
dist/utilities/groupNavItems.js	${{\color{Goldenrod}{ █▎ }}}$ 5.2%, 814 B
dist/utilities/getGlobalData.js	${{\color{Goldenrod}{ █▏ }}}$ 4.9%, 762 B
dist/utilities/api.js	${{\color{Goldenrod}{ █▏ }}}$ 4.8%, 756 B
dist/elements/Translation	${{\color{Goldenrod}{ ▊ }}}$ 3.2%, 493 B
dist/utilities/handleTakeOver.js	${{\color{Goldenrod}{ ▋ }}}$ 2.8%, 440 B
dist/utilities/traverseForLocalizedFields.js	${{\color{Goldenrod}{ ▋ }}}$ 2.6%, 399 B
dist/elements/withMergedProps	${{\color{Goldenrod}{ ▌ }}}$ 2.2%, 339 B
dist/utilities/getVisibleEntities.js	${{\color{Goldenrod}{ ▌ }}}$ 2.1%, 329 B
dist/utilities/getNavGroups.js	${{\color{Goldenrod}{ ▍ }}}$ 1.9%, 301 B
dist/elements/WithServerSideProps	${{\color{Goldenrod}{ ▍ }}}$ 1.5%, 232 B
dist/utilities/handleGoBack.js	${{\color{Goldenrod}{ ▎ }}}$ 1.2%, 180 B
dist/fields/mergeFieldStyles.js	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 159 B
dist/utilities/handleBackToDashboard.js	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 152 B
dist/forms/Form	${{\color{Goldenrod}{ ▏ }}}$ 0.9%, 147 B
dist/utilities/abortAndIgnore.js	${{\color{Goldenrod}{ ▏ }}}$ 0.9%, 146 B
(other)	${{\color{Goldenrod}{ ████████████████████ }}}$ 80.0%, 12.51 KB

Details

Next to the size is how much the size has increased or decreased compared with the base branch of this PR.

‼️: Size increased by 20% or more. Special attention should be given to this.
⚠️: Size increased in acceptable range (lower than 20%).
✅: No change or even downsized.
🗑️: The out file is deleted: not found in base branch.
🆕: The out file is newly found: will be added to base branch.

Adds all breaking changes docs from my own PRs to the v4 migration doc. | PR | Breaking change | Merged | In v4 migration doc | |----|-----------------|--------|---------------------| | [#16359](#16359) | `feat!` Deleted `@payloadcms/richtext-slate` — Lexical is now the only supported rich text editor | 2026-04-23 | ✅ Added (was missing) | | [#16414](#16414) | `feat!` Removed deprecated `jobs.depth` and `jobs.runHooks` config options | 2026-04-28 | ✅ Added (was missing) | | [#16416](#16416) | `feat!` Removed deprecated `state: 'failed'`/`'succeeded'` job task return shape | 2026-05-01 | ✅ Added (was missing) | | [#16537](#16537) | `feat!` Bumped minimum Next.js version to 16.2.6 | 2026-05-07 | ✅ Added (was missing) | | [#16540](#16540) | `feat!` Bumped minimum Node.js version to 24.15.0 | 2026-05-08 | ✅ Added (was missing) | | [#16546](#16546) | `feat!` Removed croner `sloppyRanges` compatibility setting (stricter cron parsing) | 2026-05-08 | ✅ Added (was missing) | | [#16547](#16547) | `feat!` Removed deprecated `min`/`max` from `relationship`/`upload` fields | 2026-05-08 | ✅ Added (was missing) | | [#16548](#16548) | `feat(richtext-lexical)!` Removed deprecated `HTMLConverterFeature` / `lexicalHTML` | 2026-05-11 | ✅ Added (was missing) | | [#16692](#16692) | `feat!` Bumped minimum TypeScript version to 6.0.3 | 2026-05-20 | ✅ Added (was missing) | | [#16693](#16693) | `refactor!` Removed `allowLocalizedWithinLocalized` compat flag + `PAYLOAD_DO_NOT_SANITIZE_LOCALIZED_PROPERTY` env var | 2026-05-21 | ✅ Added (was missing) |

commit

1253b3e

AlessioGr requested a review from denolfe as a code owner May 8, 2026 04:59

github-actions Bot added the created-by: Payload team label May 8, 2026

AlessioGr enabled auto-merge (squash) May 8, 2026 04:59

AlessioGr commented May 8, 2026

View reviewed changes

fix test

60381ad

paulpopus approved these changes May 11, 2026

View reviewed changes

AlessioGr merged commit 0149ad9 into main May 11, 2026
321 of 326 checks passed

AlessioGr deleted the feat/remove-html-converter branch May 11, 2026 15:25

AlessioGr mentioned this pull request May 22, 2026

docs: add breaking changes docs to migration doc #16723

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(richtext-lexical)!: remove deprecated HTMLConverterFeature#16548

feat(richtext-lexical)!: remove deprecated HTMLConverterFeature#16548
AlessioGr merged 2 commits into
mainfrom
feat/remove-html-converter

AlessioGr commented May 8, 2026 •

edited

Loading

Uh oh!

AlessioGr May 8, 2026

Uh oh!

github-actions Bot commented May 8, 2026 •

edited

Loading

Meta file: packages/next/meta_index.json, Out file: esbuild/index.js

Meta file: packages/payload/meta_index.json, Out file: esbuild/index.js

Meta file: packages/payload/meta_shared.json, Out file: esbuild/exports/shared.js

Meta file: packages/richtext-lexical/meta_client.json, Out file: esbuild/exports/client_optimized/index.js

Meta file: packages/ui/meta_client.json, Out file: esbuild/exports/client_optimized/index.js

Meta file: packages/ui/meta_shared.json, Out file: esbuild/exports/shared_optimized/index.js

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

AlessioGr commented May 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Migration

Uh oh!

AlessioGr May 8, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented May 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📦 esbuild Bundle Analysis for payload

Meta file: packages/next/meta_index.json, Out file: esbuild/index.js

Meta file: packages/payload/meta_index.json, Out file: esbuild/index.js

Meta file: packages/payload/meta_shared.json, Out file: esbuild/exports/shared.js

Meta file: packages/richtext-lexical/meta_client.json, Out file: esbuild/exports/client_optimized/index.js

Meta file: packages/ui/meta_client.json, Out file: esbuild/exports/client_optimized/index.js

Meta file: packages/ui/meta_shared.json, Out file: esbuild/exports/shared_optimized/index.js

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

AlessioGr commented May 8, 2026 •

edited

Loading

github-actions Bot commented May 8, 2026 •

edited

Loading