# mdx-js/mdx architecture

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

- Interactive diagram: https://gitdiagram.com/mdx-js/mdx
- Repository: https://github.com/mdx-js/mdx

## Overview

##### Main Components & Their Roles
- MDX Core (packages/mdx): This is the heart of the project. It includes the compiler, utilities, and plugins (e.g., the recma and rehype plugins) needed to process MDX content into executable JavaScript.
- Bundler Integrations:
– Esbuild (packages/esbuild): Provides integration to work with esbuild.
– Rollup (packages/rollup): Enables Rollup bundler support.
– Remark MDX (packages/remark-mdx): Acts as a transformer within the remark ecosystem.
- Loader Packages:
– Loader (packages/loader): Likely the standard loader for environments like webpack.
– Node-Loader (packages/node-loader): Provides a Node-specific loader implementation.
- Framework Adapters:
– React (packages/react): Integration with React.
– Preact (packages/preact): Integration with Preact.
– Vue (packages/vue): Integration with Vue.
- Documentation & Website:
– Docs (docs folder): Contains guides, tutorials, and informational pages on how to use and extend MDX.
– Website (website folder): Likely used for generating the mdxjs.com site, including the custom loaders and schema descriptions.

##### Relationships and Interactions
- The MDX Core acts as a central engine that is extended by the various integration packages.
- The loader packages serve as the bridge between the core MDX compilation and bundlers across different environments.
- Packaging is modular: each integration or adapter package (esbuild, react, vue, etc.) interacts with the core MDX package to provide targeted functionality.
- The Docs and Website components are largely independent but use MDX to render content and showcase examples, implying a relationship where the website often demonstrates MDX’s capabilities.
- External services (like Vercel, Netlify, etc.) are mentioned in the README badges/sponsors area, hinting at CI/CD, deployment and community integrations, though these are peripheral to the core system design.

##### Architectural Patterns & Principles
- Modular/Package-Based Architecture: The project is split into numerous packages, each responsible for a specific integration or functionality.
- Separation of Concerns: The MDX main functionality is decoupled from environment-specific integrations (loaders and bundlers), and from the presentation layer (Docs and Website).
- Plugin Architecture: The use of plugins (observed in the lib/plugin directory) indicates that MDX processing is extensible by injecting transformation logic.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Integration Packages Subgraph
    subgraph "Integration Packages"
        %% Bundler Integrations
        subgraph "Bundler Integrations"
            Esbuild["Esbuild Integration"]:::integration
            Rollup["Rollup Integration"]:::integration
            Remark["Remark MDX Transformer"]:::integration
        end
        %% Loader Packages
        subgraph "Loader Packages"
            Loader["Loader Package"]:::integration
            NodeLoader["Node-Loader Package"]:::integration
        end
        %% Framework Adapters
        subgraph "Framework Adapters"
            React["React Adapter"]:::integration
            Preact["Preact Adapter"]:::integration
            Vue["Vue Adapter"]:::integration
        end
    end

    %% Central MDX Core Component
    MDXCore["MDX Core"]:::core

    %% Content & Presentation Subgraph
    subgraph "Content & Presentation"
        Docs["Documentation"]:::docs
        Website["Website"]:::docs
    end

    %% Relationships: Integrations use MDX Core
    Esbuild -->|"uses"| MDXCore
    Rollup -->|"uses"| MDXCore
    Remark -->|"uses"| MDXCore
    Loader -->|"uses"| MDXCore
    NodeLoader -->|"uses"| MDXCore
    React -->|"uses"| MDXCore
    Preact -->|"uses"| MDXCore
    Vue -->|"uses"| MDXCore

    %% Relationships: MDX Core feeds content to Docs & Website
    MDXCore -->|"renders"| Docs
    MDXCore -->|"renders"| Website

    %% Click Events
    click MDXCore "https://github.com/mdx-js/mdx/tree/main/packages/mdx"
    click Esbuild "https://github.com/mdx-js/mdx/tree/main/packages/esbuild"
    click Rollup "https://github.com/mdx-js/mdx/tree/main/packages/rollup"
    click Remark "https://github.com/mdx-js/mdx/tree/main/packages/remark-mdx"
    click Loader "https://github.com/mdx-js/mdx/tree/main/packages/loader"
    click NodeLoader "https://github.com/mdx-js/mdx/tree/main/packages/node-loader"
    click React "https://github.com/mdx-js/mdx/tree/main/packages/react"
    click Preact "https://github.com/mdx-js/mdx/tree/main/packages/preact"
    click Vue "https://github.com/mdx-js/mdx/tree/main/packages/vue"
    click Docs "https://github.com/mdx-js/mdx/tree/main/docs"
    click Website "https://github.com/mdx-js/mdx/tree/main/website"

    %% Styles
    classDef core fill:#FFD700,stroke:#DAA520,stroke-width:2px;
    classDef integration fill:#87CEFA,stroke:#1E90FF,stroke-width:2px;
    classDef docs fill:#90EE90,stroke:#32CD32,stroke-width:2px;
```
