[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 saves 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 restores them — swapping Object.setPrototypeOf on every node in the saved state so they point at the new class prototypes.

import {buildEditorFromExtensions, configExtension, HMRExtension} from '@lexical/extension';
import {HistoryExtension} from '@lexical/history';

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

• hot: HotContext | null — pass import.meta.hot (Vite, SvelteKit) or null in production. The HotContext interface requires only { readonly data: Record<string, unknown> }, so any bundler with a persistent data bag works.
• 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.
• The SvelteKit example had an inline HMR implementation that is now replaced by the shared HMRExtension.

Test plan

• 8 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.
• pnpm tsc --noEmit -p tsconfig.json clean.
• pnpm vitest run --project unit -t "HMRExtension" — 8 pass.
• E2E chromium — 773 pass (identical to main).

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
lexical	Ready	Preview	Aug 7, 2026 6:40pm
lexical-playground	Ready	Preview	Aug 7, 2026 6:40pm

[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.