# pixijs/pixi-react architecture

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

- Interactive diagram: https://gitdiagram.com/pixijs/pixi-react
- Repository: https://github.com/pixijs/pixi-react

## Overview

##### Main Components and Their Roles
- Library Core – This comprises the React integration with PixiJS:
- The Application component (in src/components/Application.tsx) wraps the PIXI.Application. It is the entry point where the PixiJS lifecycle is managed.
- The “extend” API (discussed in both the README and implemented across src/helpers and src/core) registers and exposes supported PixiJS components as React components.
- The React reconciler and creation of the rendering roots (e.g., in src/core/reconciler.ts, createRoot.tsx, and roots.ts) are responsible for mounting and updating the custom Pixi components.
- Helpers and Constants – These helper functions (located in src/helpers) and constant definitions (in src/constants) manage low-level operations such as diffing properties, creating or preparing instances, and handling event bindings. They harbor critical logic needed during the commit phase of the React reconciliation cycle.
- Hooks – Custom hooks (in src/hooks) like useApplication, useTick, and useExtend abstract away the complexities of integrating with the underlying PIXI application. They bridge the React application and the PixiJS world via context.
- Type Definitions – The project leverages TypeScript (files in src/typedefs) to provide type safety to component props, events, and other interfaces that define how the React wrappers interact with PixiJS objects.
- Test Infrastructure – The test directory (with both unit and end-to-end tests) represents a separate part of the architecture ensuring quality and stability of both the library interfaces and internal helper functions.
- Documentation and Examples – The docs folder (with Docusaurus configuration, MDX files, and examples) showcases how to use the library and offers examples of extending the library with custom components.

##### Relationships and Interactions
- The Application component creates and provides a PIXI.Application instance via React Context. The useApplication hook accesses this shared context.
- Helper modules (in the src/helpers directory) serve as middleware between the React components and the underlying PixiJS objects. They perform tasks like diffing props, updating instances, and handling lifecycle events.
- The library’s hooks reside between its React components and the core functionalities, ensuring that the external API is easy to use and reactive.
- The test and docs modules interact indirectly with the core library by verifying expected behaviors and offering usage examples, respectively.

##### Architectural Patterns and Design Principles
- Declarative UI – The components follow a declarative pattern that maps JSX to PixiJS objects.
- Separation of Concerns – Different directories encapsulate distinct responsibilities (core rendering, helpers, hooks, tests) to keep the codebase modular.
- Extensibility – The “extend” API mechanism lets users register only the necessary PixiJS subsystems, reflecting a design aimed at minimizing bloat.
- React-Reconciler Integration – Custom reconciliation logic is embedded to suit the non-DOM nature of PixiJS, a key architectural design point.
- Robust Type-Safety – The presence of TypeScript definitions enhances reliability and eases extension.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Library Core"
        A["Application Component & React Context"]
        B["React Reconciler & Core Renderer"]
    end

    subgraph "Extend API"
        C["Extend API Module"]
    end

    subgraph "Helpers & Constants"
        D["Helper Functions"]
        E["Constant Definitions"]
    end

    subgraph "Custom Hooks"
        F["useApplication Hook"]
        G["useTick Hook"]
        H["useExtend Hook"]
    end

    subgraph "Type Definitions"
        I["TypeScript Definitions"]
    end

    subgraph "Test & Documentation"
        J["Tests & Docs Modules"]
    end

    subgraph "External Dependencies"
        K["PixiJS"]
        L["React"]
    end

    L -->|"renders"| A
    A -->|"managesLifecycle"| B
    A -->|"providesContext"| F
    A -->|"providesContext"| G
    A -->|"providesContext"| H
    C -->|"registersComponents"| B
    D -->|"diffAndUpdate"| B
    E -->|"constValues"| B
    I -->|"typeSafety"| F
    I -->|"typeSafety"| G
    I -->|"typeSafety"| H
    I -->|"typeSafety"| B
    J -->|"verifies"| A
    J -->|"verifies"| B
    J -->|"verifies"| F
    J -->|"verifies"| G
    J -->|"verifies"| H
    K -->|"underlyingEngine"| B
    K -->|"integratesWith"| A
    L -->|"integratesWith"| A
    H -->|"utilizesExtendAPI"| C

    click A "https://github.com/pixijs/pixi-react/blob/main/src/components/Application.tsx"
    click B "https://github.com/pixijs/pixi-react/blob/main/src/core/reconciler.ts"
    click B "https://github.com/pixijs/pixi-react/blob/main/src/core/createRoot.tsx"
    click B "https://github.com/pixijs/pixi-react/blob/main/src/core/roots.ts"
    click C "https://github.com/pixijs/pixi-react/blob/main/src/helpers/extend.ts"
    click D "https://github.com/pixijs/pixi-react/tree/main/src/helpers"
    click E "https://github.com/pixijs/pixi-react/tree/main/src/constants"
    click F "https://github.com/pixijs/pixi-react/blob/main/src/hooks/useApplication.ts"
    click G "https://github.com/pixijs/pixi-react/blob/main/src/hooks/useTick.ts"
    click H "https://github.com/pixijs/pixi-react/blob/main/src/hooks/useExtend.ts"
    click I "https://github.com/pixijs/pixi-react/tree/main/src/typedefs"
    click J "https://github.com/pixijs/pixi-react/tree/main/test"
    click J "https://github.com/pixijs/pixi-react/tree/main/docs"

    classDef core fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef api fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef helpers fill:#FFFFE0,stroke:#000,stroke-width:2px;
    classDef hooks fill:#FFA07A,stroke:#000,stroke-width:2px;
    classDef types fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef test fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef external fill:#F08080,stroke:#000,stroke-width:2px;

    class A,B core;
    class C api;
    class D,E helpers;
    class F,G,H hooks;
    class I types;
    class J test;
    class K,L external;
```
