# facebook/lexical architecture

> Architecture diagram of the GitHub repository facebook/lexical, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/facebook/lexical
- Repository: https://github.com/facebook/lexical

## Overview

##### Main Components
- Core Engine (“lexical” package)
- Extension Packages (e.g. lexical-code, lexical-markdown, lexical-yjs, etc.)
- Framework Bindings (lexical-react)
- Developer Tools (lexical-devtools browser extension)
- Example Apps & Playground (examples/ and packages/lexical-playground)
- Documentation Site (lexical-website)
- CI/CD Pipeline & External Services (GitHub Actions, npm registry)

##### Relationships & Data Flows
- Extensions depend on the Core Engine.
- Framework Bindings import Core + Extensions to expose React APIs.
- Example Apps import Framework Bindings (and possibly some Extensions) to render live editors.
- Playground → Exercise the full stack: Core → Extensions → React Bindings → Browser DOM
- Devtools Extension:
- background scripts communicate with browser (tabs)
- content scripts inject code into the page to hook the editor
- DevTools panel UI fetches editor state via messaging with content/background
- Documentation Site: static site generator reads package metadata and MDX docs to produce public website
- CI Pipeline: GitHub Actions runs tests → publishes packages to npm → deploys website

##### Architectural Patterns
- Monorepo workspace pattern (all packages live in a single repo)
- Publishable packages pattern (each subfolder under packages/ is its own npm module)
- Plugin architecture in Core Engine (registerCommands, node transforms)
- Double buffering model in Core Engine (current vs pending EditorState)
- React “hooks + components” pattern in lexical-react

##### Technologies & Frameworks
- Node.js + npm workspaces / Lerna-like scripts
- TypeScript + Flow (type systems in various packages)
- Jest for unit tests, Playwright for e2e
- Docusaurus for website
- Vite for example apps bundling
- GitHub Actions for CI/CD

##### Layered Views
To avoid clutter, consider two layers:
A. Package Architecture (monorepo structure)
B. Runtime Architecture (how an end-user’s browser, devtools extension, and examples interact with Core + Extensions + Bindings)

##### Key Points to Capture
- The Core Engine is dependency-free and is extended via plugins.
- All extensions and framework bindings flow from the Core.
- Publishing pipeline: code → version bump → npm publish → website regeneration.
- DevTools is a complex browser extension with multiple entrypoints: background, content, injected, and panel.
- Examples and Playground demonstrate usage of Core + Extensions + Bindings in a Vite-powered environment.

- the modular composition of Lexical (Core + Extensions + Bindings)
- how code moves from development through CI to npm and website
- the runtime interactions in both example apps and the devtools extension

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Monorepo Code Layer
    subgraph "Monorepo Code" 
        direction TB
        Core["lexical\n(Core Engine)"]:::code
        ExtCode["lexical-code\n(Code Highlight)"]:::ext
        ExtMD["lexical-markdown\n(Markdown)"]:::ext
        ExtYJS["lexical-yjs\n(Collaboration)"]:::ext
        Bindings["lexical-react\n(React Bindings)"]:::binding
        DevToolsCore["lexical-devtools-core\n(DevTools Logic)"]:::devtools
        DevToolsExt["DevTools Extension\n(entrypoints, UI, background, content)"]:::devtools
        Playground["lexical-playground\n(Playground App)"]:::example
        Examples["examples/*\n(Standalone Demos)"]:::example
        Docs["lexical-website\n(Documentation Site)"]:::docs
    end

    %% CI/CD Layer
    subgraph "CI/CD Pipeline" 
        direction TB
        GHActions["GitHub Actions\n(Workflows)"]:::ci
        ReleaseScripts["npm Scripts\n(Release & Publish)"]:::script
        NPM["npm Registry"]:::service
        WebsiteDeploy["Docs Deploy"]:::service
    end

    %% Runtime Layer
    subgraph "Runtime Components"
        direction TB
        Dev["Developer"]:::actor
        Browser["Browser"]:::runtime
        EditorState["Editor (Core → Ext → Bindings → DOM)"]:::runtime
        DevToolsPanel["DevTools Panel UI"]:::runtime
        Background["Background Script"]:::runtime
        Content["Content Script"]:::runtime
        Injected["Injected Hook"]:::runtime
    end

    %% Relationships
    Core -->|provides APIs| ExtCode
    Core -->|provides APIs| ExtMD
    Core -->|provides APIs| ExtYJS
    Core -->|provides APIs| Bindings
    ExtCode -->|extends| Bindings
    ExtMD -->|extends| Bindings
    ExtYJS -->|extends| Bindings
    Bindings -->|imported by| Playground
    Bindings -->|imported by| Examples
    Playground -->|runs in| Browser
    Examples -->|runs in| Browser
    Browser -->|hosts| EditorState

    Dev -->|pushes code| GHActions
    GHActions -->|runs| ReleaseScripts
    ReleaseScripts -->|publishes| NPM
    GHActions -->|deploys| WebsiteDeploy

    %% DevTools Runtime Flow
    DevToolsPanel -->|messages| Background
    Background -->|injects| Content
    Content -->|hooks| Injected
    Injected -->|interacts with| EditorState

    %% Click Events
    click Core "https://github.com/facebook/lexical/tree/main/packages/lexical"
    click ExtCode "https://github.com/facebook/lexical/tree/main/packages/lexical-code"
    click ExtMD "https://github.com/facebook/lexical/tree/main/packages/lexical-markdown"
    click ExtYJS "https://github.com/facebook/lexical/tree/main/packages/lexical-yjs"
    click Bindings "https://github.com/facebook/lexical/tree/main/packages/lexical-react"
    click DevToolsCore "https://github.com/facebook/lexical/tree/main/packages/lexical-devtools-core"
    click DevToolsExt "https://github.com/facebook/lexical/tree/main/packages/lexical-devtools/src/entrypoints"
    click Playground "https://github.com/facebook/lexical/tree/main/packages/lexical-playground"
    click Examples "https://github.com/facebook/lexical/tree/main/examples/node-replacement"
    click Docs "https://github.com/facebook/lexical/tree/main/packages/lexical-website"
    click GHActions "https://github.com/facebook/lexical/tree/main/.github/workflows"
    click ReleaseScripts "https://github.com/facebook/lexical/tree/main/scripts/npm"

    %% Styles
    classDef code fill:#FFD580,stroke:#333,stroke-width:1px
    classDef ext fill:#FFE0B2,stroke:#333,stroke-width:1px
    classDef binding fill:#B3E5FC,stroke:#333,stroke-width:1px
    classDef devtools fill:#D1C4E9,stroke:#333,stroke-width:1px
    classDef example fill:#C8E6C9,stroke:#333,stroke-width:1px
    classDef docs fill:#FFCCBC,stroke:#333,stroke-width:1px
    classDef ci fill:#BBDEFB,stroke:#333,stroke-width:1px
    classDef script fill:#CFD8DC,stroke:#333,stroke-width:1px
    classDef service fill:#F0F4C3,stroke:#333,stroke-width:1px
    classDef actor fill:#FFECB3,stroke:#333,stroke-width:1px
    classDef runtime fill:#E1BEE7,stroke:#333,stroke-width:1px
```
