# nytimes/react-prosemirror architecture

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

- Interactive diagram: https://gitdiagram.com/nytimes/react-prosemirror
- Repository: https://github.com/nytimes/react-prosemirror

## Overview

##### Project Type and Purpose
- The project is a library meant for integrating the ProseMirror rich-text editor into React applications.
- Its purpose is twofold: first, to safely render ProseMirror editor views within React components; and second, to build React-driven node views (i.e., letting React components render document nodes).
- Key usage areas include providing hooks (useEditorEffect, useEditorEventCallback, etc.), contexts, and special components (such as <ProseMirror/>) that abstract away the integration complexities between ProseMirror’s single-phase update model and React’s double-phase (render and commit) update cycle.

##### Project’s File Structure
- Top-level directories and files indicate a highly organized project:
- Configuration and tool directories such as .devcontainer, .vscode, .github, and Yarn-related directories for package management.
- The main source code lives in the src directory, which is further subdivided into:
– components (React components like Editor, LayoutGroup, NodeViews, ProseMirror component, plus tests for these)
– contexts (special React context providers to expose editor state to children)
– hooks (custom hooks for accessing editor state, events, and more)
– nodeViews (logic for creating React-based node views, including constructors)
– plugins (custom ProseMirror plugins, such as for handling React integrations)
– testing (support files for setting up ProseMirror views during tests)
- The demo and dist directories provide usage examples and build artifacts.
- Configuration files for linting, formatting, testing, and bundling (vite.config.ts, tsconfig.json, jest.config.cjs) are also present, showing that the project is designed for robust development workflows.

##### Information in the README
- The README outlines two primary integration strategies: mounting a ProseMirror EditorView inside a React component and building React-based node views.
- It details how hooks like useEditorEffect, useEditorEventCallback, and useEditorEventListener are used to synchronize the ProseMirror state with the React component lifecycle.
- The problems of reconciling React’s two-phase rendering and ProseMirror’s direct DOM mutations are highlighted, which in turn explains the need for specialized hooks and context management.

a. Main Components:
- React Application Layer:
- <ProseMirror> Component: The central React component that manages the mounting of ProseMirror’s EditorView.
- React Context Providers: Provided via components in src/contexts (e.g., EditorContext, LayoutGroupContext, NodeViewsContext) to share EditorView and state.
- ProseMirror Core:
- EditorView: Represents the underlying ProseMirror editor.
- EditorState and Schema: Managed in conjunction with plugins for rendering and commands.
- Integration Modules:
- Custom Hooks: (located in src/hooks) such as useEditorEffect, useEditorEventCallback, useEditorEventListener, which safely synchronize side effects and event handling between React and ProseMirror.
- NodeViews: In src/nodeViews, which includes React-based implementations for rendering node content.
- Plugins: In src/plugins, which integrate additional functionality (including the react plugin) to handle node views and event synchronization.
- Supporting Infrastructure:
- Demo and Testing Components: Examples (in demo and src/testing) that showcase integration usage.
- Build/Configuration: Tools and scripts for development (e.g., Dockerfile in .devcontainer, ESLint, Prettier settings).

b. Relationships and Interactions:
- The <ProseMirror> component acts as a boundary that creates and maintains the ProseMirror EditorView. It receives the mount node (DOM element) from its child components.
- React components lower down the tree (for instance, BoldButton or SelectionWidget) use custom hooks to access the EditorView, dispatch transactions, or perform layout effects.
- The React hooks wrap around the ProseMirror API to safely bridge event handling and state changes between React and ProseMirror.
- Node views are created by a stable constructor (with references in src/nodeViews) that returns both a DOM element and a React component to be launched via a portal.

c. Architectural Patterns and Design Principles:
- Separation of Concerns: The system distinctly separates core ProseMirror functionalities, the React integration layer (hooks and contexts), and UI components.
- Plugin Architecture: The project leverages ProseMirror’s plugin system (e.g., the react plugin) to ensure the React integration is seamless.
- Event Handling Abstractions: Hook-based abstractions (useEditorEventCallback, useEditorEventListener) encapsulate the differences between React events and ProseMirror DOM events.
- Modularization: Clear divisions within src (components, contexts, hooks, nodeViews, plugins) help maintain a modular, scalable architecture.

d. Relevant Technologies and Frameworks:
- React: For the UI and component structure.
- ProseMirror: As the underlying rich-text editor engine.
- TypeScript: Evident from the .ts and .tsx file extensions.
- Testing: Frameworks and configuration shown via jest.config.cjs.
- Development Infrastructure: Docker (via .devcontainer), ESLint, Prettier, Yarn for package management, and Vite for bundling (vite.config.ts).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% React Application Layer
    subgraph "React Application Layer"
        PM["<ProseMirror> Component"]:::react
        EC["Editor Context Provider"]:::react
        LG["LayoutGroup Context Provider"]:::react
        NV["NodeViews Context Provider"]:::react
    end

    %% Integration Modules Layer
    subgraph "Integration Modules"
        subgraph "Custom Hooks"
            EH["useEditorEffect"]:::hook
            ECb["useEditorEventCallback"]:::hook
            EL["useEditorEventListener"]:::hook
        end
        NVCon["React NodeView Constructor"]:::hook
        RPlugin["React Integration Plugin"]:::plugin
        CEPlugin["Event Handling Plugin"]:::plugin
    end

    %% ProseMirror Core Engine
    subgraph "ProseMirror Core Engine"
        EV["EditorView"]:::pmcore
        ES["EditorState & Schema"]:::pmcore
    end

    %% Support and Demo
    subgraph "Support & Demo"
        Test["Testing Setup"]:::support
        DemoMenu["Demo Menu"]:::support
        DemoMain["Demo Main"]:::support
    end

    %% Relationships between React and ProseMirror
    PM -->|"creates"| EV
    PM -->|"provides"| EC
    PM -->|"provides"| LG
    PM -->|"provides"| NV

    %% Hooks interacting with ProseMirror Core
    EH -->|"syncs with"| EV
    ECb -->|"triggers updates on"| EV
    EL -->|"listens to events from"| EV

    %% NodeView and Plugin Interactions
    NVCon -->|"creates NodeViews for"| EV
    RPlugin -->|"integrates with"| EV
    CEPlugin -->|"enhances event handling on"| EV

    %% ProseMirror Core internal relation
    EV -->|"manages state using"| ES

    %% Support interactions
    Test -->|"verifies integration of"| EV
    DemoMenu -->|"demonstrates UI usage of"| PM
    DemoMain -->|"demonstrates overall integration of"| PM

    %% Click Events for React Components and Modules
    click PM "https://github.com/nytimes/react-prosemirror/blob/main/src/components/ProseMirror.tsx"
    click EC "https://github.com/nytimes/react-prosemirror/blob/main/src/contexts/EditorContext.ts"
    click LG "https://github.com/nytimes/react-prosemirror/blob/main/src/contexts/LayoutGroupContext.tsx"
    click NV "https://github.com/nytimes/react-prosemirror/blob/main/src/contexts/NodeViewsContext.ts"
    click EH "https://github.com/nytimes/react-prosemirror/blob/main/src/hooks/useEditorEffect.ts"
    click ECb "https://github.com/nytimes/react-prosemirror/blob/main/src/hooks/useEditorEventCallback.ts"
    click EL "https://github.com/nytimes/react-prosemirror/blob/main/src/hooks/useEditorEventListener.ts"
    click NVCon "https://github.com/nytimes/react-prosemirror/blob/main/src/nodeViews/createReactNodeViewConstructor.tsx"
    click RPlugin "https://github.com/nytimes/react-prosemirror/blob/main/src/plugins/react.ts"
    click CEPlugin "https://github.com/nytimes/react-prosemirror/blob/main/src/plugins/componentEventListeners.ts"
    click Test "https://github.com/nytimes/react-prosemirror/blob/main/src/testing/setupProseMirrorView.ts"
    click DemoMenu "https://github.com/nytimes/react-prosemirror/blob/main/demo/Menu.tsx"
    click DemoMain "https://github.com/nytimes/react-prosemirror/blob/main/demo/main.tsx"

    %% Styles
    classDef react fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef hook fill:#D5F5E3,stroke:#117864,stroke-width:2px;
    classDef plugin fill:#FCF3CF,stroke:#B7950B,stroke-width:2px;
    classDef pmcore fill:#F9E79F,stroke:#B7950B,stroke-width:2px,stroke-dasharray: 5 5;
    classDef support fill:#FADBD8,stroke:#943126,stroke-width:2px;
```
