# vitejs/vite-plugin-react architecture

> Architecture diagram of the GitHub repository vitejs/vite-plugin-react, 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/vitejs/vite-plugin-react
- Repository: https://github.com/vitejs/vite-plugin-react

## Overview

##### Project type and purpose
- This is an open-source monorepo hosting two Vite plugins—`@vitejs/plugin-react` (Babel-based) and `@vitejs/plugin-react-swc` (SWC-based)—plus shared utilities, playgrounds for examples/tests, build scripts, and CI/CD workflows.
- Its purpose is to extend the Vite bundler with React support: JSX transforms, fast refresh HMR, SSR hooks, etc.

##### High-level file-structure analysis
- Root (pnpm workspace): orchestrates installs, builds, releases. Contains global config (.eslintrc, tsconfig, GitHub workflows).
- packages/common: shared runtime code and helper utilities for fast refresh, warning, runtime injection.
- packages/plugin-react: Babel-based plugin; exposes a Vite plugin object, uses common refresh logic, has copy-runtime scripts.
- playground/: manual/demo apps (single‐package Vite projects) for end-to-end verification.
- scripts/: toolbelt for building CJS/ESM bundles, publishing, patching.
- .github/workflows: CI pipelines (lint, test, publish).

##### Key insights from README
- Directs readers to the two plugin READMEs for feature details (JSX, fast refresh, SSR).
- Emphasizes support for both Babel and SWC engines under a unified Vite plugin interface.

a. Monorepo orchestrator (pnpm workspace + root scripts + CI/CD)
b. packages/common module (shared runtime & utils)
c. plugin-react package (Babel transform + Vite plugin hooks)
d. plugin-react-swc package (SWC transform + Vite plugin hooks + playground tests)
e. Playground projects (real-world Vite projects consuming the plugins)
f. External services/dependencies: Vite core, Babel, SWC, Node.js ecosystem, npm registry/GitHub

##### Relationships and interactions
- The Monorepo Orchestrator installs dependencies and invokes build scripts.
- Both plugin packages import from common to apply refresh runtime injection.
- Each plugin exports a Vite plugin object implementing hooks (config, resolveId, load, transform) that:
- Receive source files from the user’s Vite build pipeline
- Apply Babel or SWC transforms (JSX, refresh annotations)
- Inject runtime code (copied from common)
- Return transformed code to Vite for bundling/HMR
- Playground projects import and configure the plugin, triggering the plugin’s hooks during their local dev/build.
- CI/CD (GitHub Actions) runs unit tests, playground e2e tests, publishes to npm.

##### Architectural patterns & design principles
- Monorepo with workspace-level dependency management for code sharing & atomic releases.
- Separation of concerns: common runtime code extracted to `packages/common`; two adapter packages layer on top (one for Babel, one for SWC).
- Plugin pattern: implementing Vite’s plugin interface to hook into the compiler lifecycle.
- Declarative build configuration via `build.config.ts` and `tsconfig.json`.

##### Essential elements
- Module boundaries for root, common, plugin-react, plugin-react-swc, playgrounds
- Vite plugin lifecycle: config → load → transform → handle HMR
- Build & release pipeline (scripts + GitHub Actions)
- External dependencies (Vite core, Babel, SWC, Node/npm registry)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Monorepo Orchestrator
    subgraph "Monorepo Orchestrator"
        direction TB
        pnpm["pnpm-workspace.yaml"]:::core
        scriptsDir["scripts/"]:::core
        workflowsDir[".github/workflows/"]:::core
    end

    %% Shared Common Module
    subgraph "packages/common" 
        direction TB
        commonPkg["package.json"]:::common
        commonIndex["index.ts"]:::common
        runtime["refresh-runtime.js"]:::common
        utils["refresh-utils.ts"]:::common
        warning["warning.ts"]:::common
    end

    %% Babel Plugin Package
    subgraph "@vitejs/plugin-react (Babel)"
        direction TB
        pluginReactPkg["package.json"]:::babel
        pluginReactIndex["src/index.ts"]:::babel
        buildConfig["build.config.ts"]:::babel
        copyScript["scripts/copyRefreshRuntime.ts"]:::babel
        tsconfigReact["tsconfig.json"]:::babel
    end

    %% SWC Plugin Package
    subgraph "@vitejs/plugin-react-swc (SWC)"
        direction TB
        pluginSwcPkg["package.json"]:::swc
        pluginSwcIndex["src/index.ts"]:::swc
        bundleScript["scripts/bundle.ts"]:::swc
        playwrightConfig["playwright.config.ts"]:::swc
        tsconfigSwc["tsconfig.json"]:::swc
        swcPlayground["playground/"]:::swc
    end

    %% Playground Projects
    subgraph "Playground Projects"
        direction TB
        playgroundRoot["playground/"]:::playground
    end

    %% CI/CD Workflows
    subgraph "CI/CD Workflows"
        direction TB
        ciYml["ci.yml"]:::core
        publishYml["publish.yml"]:::core
        releaseCont["release-continuous.yml"]:::core
        sprYml["semantic-pull-request.yml"]:::core
    end

    %% External Dependencies
    viteCore["Vite Core"]:::external
    babelEngine["Babel"]:::external
    swcEngine["SWC"]:::external
    npmRegistry["npm registry/GitHub"]:::external

    %% Relationships
    pnpm -->|"manages workspace"| commonPkg
    pnpm -->|"manages workspace"| pluginReactPkg
    pnpm -->|"manages workspace"| pluginSwcPkg

    scriptsDir -->|"build & release scripts"| pluginReactPkg
    scriptsDir -->|"build & release scripts"| pluginSwcPkg

    workflowsDir -->|"defines pipelines"| ciYml
    workflowsDir -->|"defines pipelines"| publishYml
    workflowsDir -->|"defines pipelines"| releaseCont
    workflowsDir -->|"defines pipelines"| sprYml

    ciYml -->|"triggers builds/tests"| pnpm
    ciYml -->|"runs e2e on"| playgroundRoot
    publishYml -->|"publishes to"| npmRegistry
    releaseCont -->|"automates release"| npmRegistry

    pnpm -->|"publishes to"| npmRegistry

    pluginReactPkg -->|"imports"| commonIndex
    pluginSwcPkg -->|"imports"| commonIndex

    pluginReactPkg -->|"invokes hooks on"| viteCore
    pluginSwcPkg -->|"invokes hooks on"| viteCore

    pluginReactPkg -->|"delegates transform to"| babelEngine
    pluginSwcPkg -->|"delegates transform to"| swcEngine

    pluginReactPkg -->|"injects runtime from"| runtime
    pluginSwcPkg -->|"injects runtime from"| runtime

    playgroundRoot -->|"uses plugin"| pluginReactPkg
    playgroundRoot -->|"uses plugin"| pluginSwcPkg

    %% Click Events
    click pnpm "https://github.com/vitejs/vite-plugin-react/blob/main/pnpm-workspace.yaml"
    click scriptsDir "https://github.com/vitejs/vite-plugin-react/tree/main/scripts/"
    click workflowsDir "https://github.com/vitejs/vite-plugin-react/tree/main/.github/workflows/"
    click commonPkg "https://github.com/vitejs/vite-plugin-react/blob/main/packages/common/package.json"
    click commonIndex "https://github.com/vitejs/vite-plugin-react/blob/main/packages/common/index.ts"
    click runtime "https://github.com/vitejs/vite-plugin-react/blob/main/packages/common/refresh-runtime.js"
    click utils "https://github.com/vitejs/vite-plugin-react/blob/main/packages/common/refresh-utils.ts"
    click warning "https://github.com/vitejs/vite-plugin-react/blob/main/packages/common/warning.ts"
    click pluginReactPkg "https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-oxc/package.json"
    click pluginReactIndex "https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-oxc/src/index.ts"
    click buildConfig "https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-oxc/build.config.ts"
    click copyScript "https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-oxc/scripts/copyRefreshRuntime.ts"
    click tsconfigReact "https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-oxc/tsconfig.json"
    click pluginSwcPkg "https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc/package.json"
    click pluginSwcIndex "https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc/src/index.ts"
    click bundleScript "https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc/scripts/bundle.ts"
    click playwrightConfig "https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc/playwright.config.ts"
    click tsconfigSwc "https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc/tsconfig.json"
    click swcPlayground "https://github.com/vitejs/vite-plugin-react/tree/main/packages/plugin-react-swc/playground/"
    click playgroundRoot "https://github.com/vitejs/vite-plugin-react/tree/main/playground/"
    click ciYml "https://github.com/vitejs/vite-plugin-react/blob/main/.github/workflows/ci.yml"
    click publishYml "https://github.com/vitejs/vite-plugin-react/blob/main/.github/workflows/publish.yml"
    click releaseCont "https://github.com/vitejs/vite-plugin-react/blob/main/.github/workflows/release-continuous.yml"
    click sprYml "https://github.com/vitejs/vite-plugin-react/blob/main/.github/workflows/semantic-pull-request.yml"

    %% Styles
    classDef core fill:#add8e6,stroke:#000,stroke-width:1px
    classDef common fill:#90ee90,stroke:#000,stroke-width:1px
    classDef babel fill:#ffa500,stroke:#000,stroke-width:1px
    classDef swc fill:#dda0dd,stroke:#000,stroke-width:1px
    classDef playground fill:#d3d3d3,stroke:#000,stroke-width:1px
    classDef external fill:#ffffe0,stroke:#000,stroke-width:1px
```
