/web-editor-lexical

name: web-editor-lexical
description: Extensible text editor framework by Meta

Lexical Editor Patterns

> **Quick Guide:** Lexical is a lightweight (22kb min+gzip) extensible text editor framework. Use `LexicalComposer` for React setup with plugins as child components. Extend via the node system (ElementNode, TextNode, DecoratorNode), command system (createCommand + priorities), and transforms. EditorState is immutable -- all mutations happen inside `editor.update()`. Use `$`-prefixed functions only inside update/read closures. **Current: v0.42.x (pre-1.0)**

---

<critical_requirements>

CRITICAL: Before Using This Skill

> **All code must follow project conventions in CLAUDE.md** (kebab-case, named exports, import ordering, `import type`, named constants)

**(You MUST call `$`-prefixed functions (`$getRoot`, `$getSelection`, `$createTextNode`) ONLY inside `editor.update()` or `editor.read()` closures -- calling them outside throws runtime errors)**

**(You MUST register custom nodes in the `nodes` array of `initialConfig` -- unregistered nodes cause silent failures or runtime errors)**

**(You MUST return a cleanup function from `useEffect` when registering commands, transforms, or listeners -- Lexical register methods return unsubscribe functions)**

**(You MUST include preconditions in transforms to prevent infinite loops -- a transform that unconditionally modifies its target node re-triggers itself)**

</critical_requirements>

---

**Auto-detection:** Lexical, lexical, @lexical/react, @lexical/rich-text, @lexical/list, @lexical/code, @lexical/link, @lexical/html, @lexical/headless, LexicalComposer, EditorState, LexicalNode, ElementNode, TextNode, DecoratorNode, createCommand, dispatchCommand, registerCommand, COMMAND_PRIORITY, $getRoot, $getSelection, $createParagraphNode, $createTextNode, RichTextPlugin, OnChangePlugin, HistoryPlugin, useLexicalComposerContext, editor.update, editor.read, registerNodeTransform, exportJSON, importJSON, exportDOM, importDOM, NodeState, createState

**When to use:**

• Building rich text editors with custom formatting and embedded content
• Creating editors with custom node types (mentions, embeds, code blocks)
• Implementing collaborative editing with operational transforms
• Building structured content editors (not just plain text)

**When NOT to use:**

• Plain text inputs without formatting (use a standard `<textarea>`)
• Simple markdown editing without live preview (use a textarea with markdown parsing)
• Editors that need pure decorations without document mutation (Lexical decorator nodes mutate content)

**Key patterns covered:**

• React setup with LexicalComposer, plugins, and initialConfig
• Node system: ElementNode, TextNode, DecoratorNode, custom nodes
• Command system: createCommand, priorities, dispatching, propagation
• Transforms for automatic node mutations
• EditorState immutability and the update lifecycle
• JSON and HTML serialization

**Detailed Resources:**

• [examples/core.md](examples/core.md) - Editor setup, plugins, commands, transforms
• [examples/custom-nodes.md](examples/custom-nodes.md) - Custom ElementNode, TextNode, DecoratorNode, NodeState API
• [examples/serialization.md](examples/serialization.md) - JSON/HTML serialization, import/export, headless usage
• [reference.md](reference.md) - Decision frameworks, command priority table, anti-patterns

---

<philosophy>

Philosophy

Lexical is an editor framework, not a batteries-included editor. The core is intentionally minimal -- it provides the node tree, selection, reconciler, command system, and update lifecycle. Everything else (toolbars, formatting, lists, links, embeds) is a plugin.

**Key architectural principles:**

• **Immutable EditorState:** The editor maintains a frozen state snapshot. Mutations happen inside `editor.update()` closures that clone the state, apply changes, then reconcile to DOM.
• **`$`-function convention:** Functions prefixed with `$` (like `$getRoot()`, `$getSelection()`) must run inside `editor.update()` or `editor.read()` closures -- similar to React hooks requiring a component context.
• **Plugin = React component:** In the React binding, a plugin is a React component rendered as a child of `<LexicalComposer>`. It accesses the editor via `useLexicalComposerContext()` and registers commands/transforms/listeners in `useEffect`.
• **Command-driven architecture:** User interactions and plugin communication flow through typed commands with priority-based listeners, enabling plugins to intercept or augment behavior.
• **Node-driven content model:** Content is a tree of typed nodes. Custom content types (mentions, embeds, polls) are custom node classes.

**When to use Lexical:**

• Rich text editing with custom formatting and embedded content
• Content editors requiring structured output (not just HTML strings)
• Editors needing accessibility and screen reader support
• Applications requiring server-side rendering or headless processing of editor content

**When NOT to use Lexical:**

• Simple text inputs (a `<textarea>` is simpler and lighter)
• Editors needing pure decorations that don't affect document content
• Projects requiring a stable 1.0 API (Lexical is pre-1.0, APIs may change)

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: React Editor Setup

The minimal setup uses `LexicalComposer` wrapping plugin components. Each plugin is a React component that accesses the editor via context.

import { LexicalComposer } from "@lexical/react/LexicalComposer";
import { RichTextPlugin } from "@lexical/react/LexicalRichTextPlugin";
import { ContentEditable } from "@lexical/react/LexicalContentEditable";
import { HistoryPlugin } from "@lexical/react/LexicalHistoryPlugin";
import { LexicalErrorBoundary } from "@lexical/react/LexicalErrorBoundary";

const EDITOR_NAMESPACE = "MyEditor";

const theme = {
  paragraph: "editor-paragraph",
  text: {
    bold: "editor-text-bold",
    italic: "editor-text-ita