[lexical-extension][lexical-react] Feature: HMR support for extensions

[mayrang]

Description

Lexical relies on object identity for node class registration, command dispatch, and extension deduplication. When a bundler's HMR re-executes a module, those objects get recreated and the previous editor state is lost. This PR adds an HMRExtension to @lexical/extension that preserves editor state, the editable flag, and undo/redo history across HMR cycles. It also splits three @lexical/react plugin modules for better React Fast Refresh compatibility.

HMRExtension

On each HMR cycle, the extension serializes the current EditorState, editable flag, and (when HistoryExtension is present) the full undo/redo stacks to the bundler's HMR data store. When the new editor instance is created, it calls editor.parseEditorState(json) to deserialize the saved state — all nodes are reconstructed with the new class prototypes automatically.

import {buildEditorFromExtensions, configExtension, defineExtension, HMRExtension} from '@lexical/extension';
import {RichTextExtension} from '@lexical/rich-text';
import {HistoryExtension} from '@lexical/history';

const editor = buildEditorFromExtensions(
  defineExtension({
    name: '[root]',
    namespace: 'my-editor',
    dependencies: [
      RichTextExtension,
      HistoryExtension,
      configExtension(HMRExtension, {hot: import.meta.hot ?? null}),
    ],
  }),
);

• hot: HotContext | null — pass import.meta.hot ?? null; the extension is a no-op when null, so no build-time conditional is needed. The HotContext interface requires only { readonly data: Record<string, unknown> }, so any bundler with a compatible data bag works.
• Multiple editors on the same page are isolated by namespace automatically. Use id only when two editors share both the same HMR context and namespace.
• When HistoryExtension is a peer, undo/redo stacks are preserved automatically. The extension detects it at runtime via getPeerDependencyFromEditor — no hard dependency.
• Corrupted or empty saved state falls back to $initialEditorState gracefully.

Fast Refresh splits

Vite's react-refresh plugin applies state-preserving HMR only when a module exports nothing but React components. Three @lexical/react plugins export hooks, classes, or commands alongside their component, which forces a full remount on every change.

This PR extracts non-component exports into companion *Utils files:

• LexicalAutoEmbedPluginUtils.ts — AutoEmbedOption, EmbedConfig, INSERT_EMBED_COMMAND, URL_MATCHER
• LexicalCollaborationContextUtils.ts — CollaborationContext, useCollaborationContext
• LexicalTypeaheadMenuPluginUtils.ts — PUNCTUATION, useBasicTypeaheadTriggerMatch, SCROLL_TYPEAHEAD_OPTION_INTO_VIEW_COMMAND, getScrollParent

Backwards compatibility

The original component modules re-export everything from their Utils counterpart, so existing import paths keep working. No API changes.

Design notes

• The HotContext interface is deliberately minimal. Bundler HMR contexts have wildly different shapes (Vite has accept, dispose, prune; webpack has module.hot.accept). The only shared property is a persistent data bag. Widening this interface is possible if a use case comes up.
• The *Utils split is one approach to Fast Refresh compatibility. An alternative is // @refresh reset directives on the component files, which forces a full remount but avoids the file split. The split gives more granular HMR boundaries — changes to the Utils file don't invalidate the component, and vice versa.

Test plan

• 23 unit tests in HMRExtension.test.ts — content preservation, editable flag, undo/redo round-trip, multi-cycle, null hot, corrupted state, empty saved state, no-history peer, namespace isolation, id isolation.
• pnpm run tsc clean.
• pnpm vitest run --project unit — all pass.
• E2E chromium — 776 pass.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
lexical	Ready	Preview	Sep 1, 2026 10:19pm UTC
lexical-playground	Ready	Preview	Sep 1, 2026 10:19pm UTC

[etrepum]

examples can’t depend on new exports, we’d have to create a new dev-examples for this until this api is published

[mayrang]

Done — moved the example to dev-examples/hmr/ and reverted examples/extension-sveltekit-ssr-hydration to its original inline implementation.

[etrepum]

The strategy here needs some consideration for multiple editors on the page, and it should create a new editor state rather than trying to mutate nodes that might be frozen already.

ChatGPT review

Review findings

1. [P1] Prototype replacement fails for reconciled custom nodes
   swapNodePrototypes() calls Object.setPrototypeOf() directly on nodes from the saved editor state. In development builds, however, the reconciler freezes nodes after rendering them into the DOM. A genuine HMR update that replaces a custom node class produces a different prototype, so changing the prototype of the frozen saved node throws a TypeError.

The surrounding catch converts that exception into “Starting fresh,” meaning the extension loses the editor state in precisely the custom-node HMR scenario it is intended to support. The current unit tests do not expose this because they never attach a root element, so their states are not reconciled and frozen, and they recreate editors with the same node classes.

The restoration mechanism should avoid mutating frozen nodes—for example, clone the state into new node instances with the newly registered classes—or otherwise establish a supported core-level mechanism for remapping node prototypes.

2. [P1] Every editor created from the same hot module shares one saved state
   The extension stores its state under the single constant key lexicalHMR. Each effect then unconditionally writes that key in the module’s shared hot.data object.

Consequently, two editors configured with the same import.meta.hot context overwrite one another. On initial mounting, the second editor can restore the first editor’s content; after that, whichever editor updates last becomes the state restored by both editors following HMR. This is a common arrangement when a module renders multiple instances of the same editor component.

Saved data needs to be namespaced per editor instance, using an explicit stable identifier in HMRConfig or a similarly stable key that survives the reload. Tests should cover two editors sharing one HotContext and verify that their content and history remain independent.

[etrepum]

It looks like something is wrong with the lockfile causing all of CI to fail. We could probably use namespace in addition to id to generate the HMR key, some editors may already set that separately for different editors on the page.

[etrepum]

I think the only thing left here is updating the flow stubs for the extracted utils modules