# posva/unplugin-vue-router architecture

> Architecture diagram of the GitHub repository posva/unplugin-vue-router, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/posva/unplugin-vue-router
- Repository: https://github.com/posva/unplugin-vue-router

## Overview

To represent **unplugin-vue-router** accurately, we’ll treat it as an open-source build-time plugin library for Vue/TypeScript. Your goal is to show how it integrates into various bundlers, how it processes source files to generate routes/types at build time, and how it exposes runtime modules for client use. Follow these tailored steps:

##### Main Components
a. Bundler Integration
- Vite plugin (`src/vite.ts`)
- Rollup plugin (`src/rollup.ts`)
- Webpack plugin (`src/webpack.ts`)
- esbuild plugin (`src/esbuild.ts`)
b. Build-Time Processing (Codegen & Core)
- Codegen modules (`src/codegen/*`) for generating route maps, records, and TypeScript declarations
- Core modules (`src/core/*`) for watching the routes folder, parsing file names, applying options, extending routes
- Data-Loader extensions (`src/data-loaders/*`) (experimental APIs)
- Volar support for IDE integration (`src/volar/*`)
c. Runtime Modules
- `src/runtime.ts` (client-side utilities)
- `client.d.ts` (type declarations for imports from `unplugin-vue-router/client`)
- Generated types file (`typed-router.d.ts` in project root)
d. Documentation Site
- VitePress config (`docs/.vitepress/*`) and markdown content (`docs/guide`, `docs/data-loaders`, etc.)
e. Examples & Tests
- Playground app demonstrating usage (`playground/`)
- E2E tests (`e2e/`) and unit tests (`tests/`)

##### Relationships & Data Flow
- **File System** → Bundler plugin entry → **Core** reads `src/pages` routes folder → Core emits file list → **Codegen** generates:
- `vue-router/auto-routes` module (runtime route array)
- TypeScript declarations (`typed-router.d.ts`)
- Generated modules are written into the build’s virtual module namespace (`virtual:`), then passed back to the bundler.
- **App Code** imports `routes` from `vue-router/auto-routes` and calls `createRouter` → Vue Router runtime.
- **Data Loaders** may inject code at build time for route-level data fetching.
- **Volar** hooks into language server via custom blocks for type-safe routing in IDE.
- **Docs Site** is a separate sub-project built with VitePress, consuming some core modules for live examples.

##### Architectural Patterns
- **Plugin Architecture**: each bundler adapter delegates to the same core + codegen logic.
- **Code Generation**: transforms file-based routes into typed route definitions at build time.
- **Virtual Modules**: uses the unplugin “virtual module” pattern to export generated code.
- **Separation of Concerns**:
- Bundler adapters (vite/rollup/webpack/esbuild)
- Core file-watching/parsing
- Codegen and type generation
- Runtime utilities vs. build-time logic

- Bundler Plugins (Vite, Rollup, Webpack, esbuild)
- Core Processor (`RoutesFolderWatcher`, parser, option handler)
- Codegen Modules (`generateRouteMap`, `generateDTS`, etc.)
- Virtual Modules (`vue-router/auto-routes`, `typed-router.d.ts`)
- Runtime API (`runtime.ts`, `client.d.ts`)
- Application (`createRouter`, Vue app)
- Data-Loader Extensions
- Volar Integration
- Docs Site & Playground (as consumers)
- Tests (as verification step)
- From Bundler → Core → Codegen → Virtual Modules → Application
- Runtime components in another (e.g., green)
- Consumers (app, docs, playground) in a third (e.g., orange)

##### Be Detailed but Focused
- Related modules under drop-shadows or containers (e.g., “src/codegen,” “src/core,” “src/data-loaders”).
- Call out important config files (`route.schema.json`, `unplugin-vue-router` options).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Bundler Adapters
    subgraph "Bundler Adapters"
        direction TB
        VitePlugin["Vite Plugin"]:::build
        RollupPlugin["Rollup Plugin"]:::build
        WebpackPlugin["Webpack Plugin"]:::build
        EsbuildPlugin["Esbuild Plugin"]:::build
    end

    %% Build Pipeline
    subgraph "Build Pipeline"
        direction TB
        subgraph "Core Processor" 
            direction TB
            RFW["RoutesFolderWatcher"]:::build
            DP["definePage API"]:::build
            ER["Route Extension Logic"]:::build
            CTX["Shared Context & Constants"]:::build
            CB["Custom Block Handling"]:::build
            OPT["Options Handler"]:::build
            TM["Route Tree Model"]:::build
            UTIL["Utility Functions"]:::build
        end
        subgraph "Codegen Modules"
            direction TB
            GRM["generateRouteMap"]:::build
            GRR["generateRouteRecords"]:::build
            GDT["generateDTS"]:::build
            GFIM["generateRouteFileInfoMap"]:::build
            GPRM["generateRouteParams"]:::build
            VRM["vueRouterModule"]:::build
        end
        subgraph "Virtual Modules"
            direction TB
            ARM["vue-router/auto-routes"]:::build
            TDT["typed-router.d.ts"]:::build
        end
    end

    %% Runtime / API
    subgraph "Runtime / API"
        direction TB
        RUNTIME["runtime.ts"]:::runtime
        CLIENTDTS["client.d.ts"]:::runtime
        APP["Application<br/>createRouter()"]:::runtime
        VUEROUTER["Vue Router (>=4.4.0)"]:::external
    end

    %% Consumers & Tests
    subgraph "Consumers & Tests"
        direction TB
        DocsSite["Documentation Site"]:::consumer
        Playground["Playground App"]:::consumer
        NuxtExample["Nuxt Example App"]:::consumer
        E2E["E2E Tests"]:::consumer
        UnitTests["Unit & Integration Tests"]:::consumer
    end

    %% Data-Loader & Volar
    DL["Data-Loader Extensions"]:::build
    VOLAR["Volar IDE Integration"]:::build

    %% External Dependencies
    FS["File System (src/pages)"]:::external
    TS["TypeScript"]:::external

    %% Connections
    VitePlugin -->|delegates to| RFW
    RollupPlugin -->|delegates to| RFW
    WebpackPlugin -->|delegates to| RFW
    EsbuildPlugin -->|delegates to| RFW

    RFW -->|"file list"| GRM
    DP -->|"page defs"| ER
    ER -->|"extended routes"| GRM
    OPT -->|options| RFW
    CTX -->|context| ER
    CB -->|custom blocks| RFW
    TM -->|tree model| ER
    UTIL -->|utils| GRM

    GRM -->|"routes map"| VRM
    GRR -->|"route records"| VRM
    GDT -->|"TS declarations"| TDT
    GFIM -->|info map| GRM
    GPRM -->|params code| GRM

    VRM --> ARM
    TDT --> ARM

    ARM -->|virtual module| APP
    TDT -->|import types| APP

    APP -->|"calls"| VUEROUTER

    FS -->|watch| RFW
    TS -->|typegen| GDT

    DL -->|inject data APIs| GRM
    VOLAR -->|IDE hooks| RFW

    DocsSite -->|uses core & codegen| GRM
    Playground -->|imports plugin| VitePlugin
    NuxtExample -->|imports plugin| WebpackPlugin

    E2E -->|verifies| GRM
    UnitTests -->|verifies| DP
    UnitTests -->|verifies| DL

    %% Click Events
    click VitePlugin "https://github.com/posva/unplugin-vue-router/blob/main/src/vite.ts"
    click RollupPlugin "https://github.com/posva/unplugin-vue-router/blob/main/src/rollup.ts"
    click WebpackPlugin "https://github.com/posva/unplugin-vue-router/blob/main/src/webpack.ts"
    click EsbuildPlugin "https://github.com/posva/unplugin-vue-router/blob/main/src/esbuild.ts"

    click RFW "https://github.com/posva/unplugin-vue-router/blob/main/src/core/RoutesFolderWatcher.ts"
    click DP "https://github.com/posva/unplugin-vue-router/blob/main/src/core/definePage.ts"
    click ER "https://github.com/posva/unplugin-vue-router/blob/main/src/core/extendRoutes.ts"
    click CTX "https://github.com/posva/unplugin-vue-router/blob/main/src/core/context.ts"
    click CB "https://github.com/posva/unplugin-vue-router/blob/main/src/core/customBlock.ts"
    click OPT "https://github.com/posva/unplugin-vue-router/blob/main/src/core/options.ts"
    click TM "https://github.com/posva/unplugin-vue-router/blob/main/src/core/tree.ts"
    click UTIL "https://github.com/posva/unplugin-vue-router/blob/main/src/core/utils.ts"
    click TM "https://github.com/posva/unplugin-vue-router/blob/main/src/core/treeNodeValue.ts"
    click GRM "https://github.com/posva/unplugin-vue-router/blob/main/src/codegen/generateRouteMap.ts"
    click GRR "https://github.com/posva/unplugin-vue-router/blob/main/src/codegen/generateRouteRecords.ts"
    click GDT "https://github.com/posva/unplugin-vue-router/blob/main/src/codegen/generateDTS.ts"
    click GFIM "https://github.com/posva/unplugin-vue-router/blob/main/src/codegen/generateRouteFileInfoMap.ts"
    click GPRM "https://github.com/posva/unplugin-vue-router/blob/main/src/codegen/generateRouteParams.ts"
    click VRM "https://github.com/posva/unplugin-vue-router/blob/main/src/codegen/vueRouterModule.ts"

    click DL "https://github.com/posva/unplugin-vue-router/tree/main/src/data-loaders/"
    click VOLAR "https://github.com/posva/unplugin-vue-router/blob/main/src/volar/entries/sfc-route-blocks.ts"
    click VOLAR "https://github.com/posva/unplugin-vue-router/blob/main/src/volar/entries/sfc-typed-router.ts"
    click VOLAR "https://github.com/posva/unplugin-vue-router/blob/main/src/volar/utils/augment-vls-ctx.ts"

    click RUNTIME "https://github.com/posva/unplugin-vue-router/blob/main/src/runtime.ts"
    click CLIENTDTS "https://github.com/posva/unplugin-vue-router/blob/main/client.d.ts"
    click TDT "https://github.com/posva/unplugin-vue-router/blob/main/typed-router.d.ts"

    click DocsSite "https://github.com/posva/unplugin-vue-router/blob/main/docs/.vitepress/config.ts"
    click DocsSite "https://github.com/posva/unplugin-vue-router/blob/main/docs/.vitepress/meta.ts"
    click DocsSite "https://github.com/posva/unplugin-vue-router/tree/main/docs/guide/"
    click DocsSite "https://github.com/posva/unplugin-vue-router/tree/main/docs/data-loaders/"

    click Playground "https://github.com/posva/unplugin-vue-router/tree/main/playground/"
    click NuxtExample "https://github.com/posva/unplugin-vue-router/tree/main/examples/nuxt/"

    click E2E "https://github.com/posva/unplugin-vue-router/tree/main/e2e/"
    click UnitTests "https://github.com/posva/unplugin-vue-router/tree/main/tests/"
    click UnitTests "https://github.com/posva/unplugin-vue-router/tree/main/tests/data-loaders/"

    %% Styles
    classDef build fill:#D0E8FF,stroke:#2E6EB5,stroke-width:1px
    classDef runtime fill:#D8F0D6,stroke:#2E8B57,stroke-width:1px
    classDef consumer fill:#FFE4BB,stroke:#E69500,stroke-width:1px
    classDef external fill:#F0F0F0,stroke:#888888,stroke-width:1px,stroke-dasharray: 2 2
```
