# originjs/webpack-to-vite architecture

> Architecture diagram of the GitHub repository originjs/webpack-to-vite, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/originjs/webpack-to-vite
- Repository: https://github.com/originjs/webpack-to-vite

## Overview

##### Project Type and Purpose
- This is a Command-Line Interface (CLI) tool written in TypeScript/Node.js.
- Its purpose is to convert existing Webpack or Vue-CLI projects into Vite‐based projects automatically.
- Key workflow: take a project path as input → parse existing config files via AST → transform config and code patterns → generate new Vite project structure.

##### High-Level Architecture
The overall system can be broken down into these main components:
A. CLI Layer (bin/index.ts & src/cli)
B. Configuration Loader (src/config)
C. AST Parser Layer (src/ast-parse)
D. Transformation Layer (src/transform)
E. Code Generation Layer (src/generate + src/template)
F. Utilities (src/utils)
G. File System I/O (Node.js fs via utils/file.ts)
H. External Dependencies (TypeScript runtime, Babel parser/traverse, EJS, NPM registry for package updates)

##### Component Responsibilities and Interaction Flow
1. CLI Layer
- Exposes the command `webpack-to-vite` with options (project type, entry, cover flag).
- Parses CLI args → invokes the core conversion engine.
- Reports progress and errors (src/utils/report.ts).

2. Configuration Loader
- Reads existing config files: `vue.config.js`, `webpack.config.js`, or multi-file Webpack setups.
- Normalizes raw config into a common in-memory representation.
- Exposes projectType, entry points, plugin settings to downstream layers.

3. AST Parser Layer
- Uses Babel to parse JavaScript/TypeScript config and code into ASTs.
- Contains parser modules (`findHtmlConfigProperties`, `findWebpackConfigProperties`, etc.).
- Extracts configuration properties, plugin chains, require-context calls, JSX patterns.

4. Transformation Layer
- Applies a series of transformation functions on the parsed AST or config object.
- Modules under `src/transform` handle Vue-CLI vs Webpack different code paths.
- Examples: lazy-loading route transformation, HTML plugin chain rewrite, removal of obsolete HMR code.

5. Code Generation Layer
- Uses EJS templates (in `src/template`) for `vite.config.js`, `index.html`, package.json.
- `render.ts` and `generate/*` functions inject transformed config into templates.
- Generates new files under a target directory (e.g. `projectName-toVite`).

6. Utilities
- Common helper functions (`common.ts`), AST utilities (`astUtils.ts`), version management.
- File operations (`file.ts`): copying, writing, directory traversal.
- Config merging (`config.ts`).

7. File System I/O
- Reads input project files (config, source, assets).
- Writes output: new Vite config, HTML entry, package.json, and optionally overwrites original files.

8. External Dependencies
- Babel parser/traverse for AST operations.
- EJS for template rendering.
- TypeScript for compilation.
- NPM registry for devDependencies injection.

##### Architectural Patterns and Design Principles
- Layered Pipeline: CLI → Config Loader → Parser → Transformer → Generator → FS.
- Separation of Concerns: Each module has a single responsibility (parsing vs transforming vs generating).
- Plugin-style Parsers/Transformers: New patterns can be added by dropping in new parser or transformation modules.
- Template‐driven Generation: Decouples logic from file output via EJS.
- Test Harness: Comprehensive unit tests verify each module’s behavior in isolation (tests directory).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "CLI Layer"
        CLI_BIN["bin/index.ts"]:::cli
        CLI_CORE["src/cli/cli.ts"]:::cli
    end

    subgraph "Configuration Loader"
        CONFIG_CORE["src/config/config.ts"]:::config
        CONFIG_PARSE["src/config/parse.ts"]:::config
        CONFIG_VUECLI["src/config/vuecli.ts"]:::config
        CONFIG_WEBPACK["src/config/webpack.ts"]:::config
        CONFIG_VITE["src/config/vite.ts"]:::config
    end

    subgraph "AST Parser Layer"
        AST_PARSE["src/ast-parse/astParse.ts"]:::parser
        subgraph "Parsers"
            PARSE_HTML_PROPS["findHtmlConfigProperties.ts"]:::parser
            PARSE_HTML_CHAIN["findHtmlPluginChain.ts"]:::parser
            PARSE_JSX["findJsxInScriptParser.ts"]:::parser
            PARSE_REQ_CTX["findRequireContext.ts"]:::parser
            PARSE_WP_PROPS["findWebpackConfigProperties.ts"]:::parser
            PARSE_INDEX["index.ts"]:::parser
        end
        subgraph "Transformations"
            TRANS_ADD_JSX["addJsxTransformation.ts"]:::parser
            TRANS_CHAIN_WP["chainWebpackTransformation.ts"]:::parser
            TRANS_HTML_VUE["indexHtmlTransformationVueCli.ts"]:::parser
            TRANS_HTML_WP["indexHtmlTransformationWebpack.ts"]:::parser
            TRANS_LAZY["lazyLoadingRoutesTransformation.ts"]:::parser
            TRANS_REMOVE_LANG["removeHtmlLangInTemplateTransformation.ts"]:::parser
            TRANS_INDEX["index.ts"]:::parser
        end
    end

    subgraph "Transformation Layer"
        TRANSFORMER["src/transform/transformer.ts"]:::transform
        TRANS_VUECLI["src/transform/transformVuecli.ts"]:::transform
        TRANS_WEBPACK["src/transform/transformWebpack.ts"]:::transform
        TRANS_CONTEXT["src/transform/context.ts"]:::transform
    end

    subgraph "Code Generation Layer"
        RENDER["src/generate/render.ts"]:::gen
        GENE_HTML["src/generate/geneIndexHtml.ts"]:::gen
        GENE_PKG["src/generate/genePackageJson.ts"]:::gen
        GENE_VITECFG["src/generate/geneViteConfig.ts"]:::gen
        TEMPLATE_HTML["src/template/index.html"]:::gen
        TEMPLATE_VITE["src/template/vite.config.ejs"]:::gen
    end

    subgraph "Utilities"
        UTIL_COMMON["src/utils/common.ts"]:::utils
        UTIL_AST["src/utils/astUtils.ts"]:::utils
        UTIL_CONFIG["src/utils/config.ts"]:::utils
        UTIL_REPORT["src/utils/report.ts"]:::utils
        UTIL_VERSION["src/utils/version.ts"]:::utils
    end

    subgraph "File System I/O"
        FS_FILE["src/utils/file.ts"]:::fs
    end

    subgraph "External Dependencies"
        EXT_BABEL["Babel parser/traverse"]:::external
        EXT_EJS["EJS"]:::external
        EXT_TS["TypeScript"]:::external
        EXT_NPM["NPM registry"]:::external
    end

    CLI_BIN -->|"invokes"| CLI_CORE
    CLI_CORE -->|"loads config"| CONFIG_CORE
    CONFIG_CORE --> CONFIG_PARSE
    CONFIG_PARSE --> CONFIG_VUECLI
    CONFIG_PARSE --> CONFIG_WEBPACK
    CONFIG_PARSE --> CONFIG_VITE
    CONFIG_VUECLI --> AST_PARSE
    CONFIG_WEBPACK --> AST_PARSE
    AST_PARSE --> PARSE_INDEX
    PARSE_INDEX --> PARSE_HTML_PROPS
    PARSE_INDEX --> PARSE_HTML_CHAIN
    PARSE_INDEX --> PARSE_JSX
    PARSE_INDEX --> PARSE_REQ_CTX
    PARSE_INDEX --> PARSE_WP_PROPS
    PARSE_INDEX --> TRANS_INDEX
    TRANS_INDEX --> TRANS_ADD_JSX
    TRANS_INDEX --> TRANS_CHAIN_WP
    TRANS_INDEX --> TRANS_HTML_VUE
    TRANS_INDEX --> TRANS_HTML_WP
    TRANS_INDEX --> TRANS_LAZY
    TRANS_INDEX --> TRANS_REMOVE_LANG
    PARSE_INDEX --> TRANSFORMER
    TRANSFORMER --> TRANS_VUECLI
    TRANSFORMER --> TRANS_WEBPACK
    TRANSFORMER --> TRANS_CONTEXT
    TRANS_CONTEXT --> RENDER
    RENDER --> GENE_HTML
    RENDER --> GENE_PKG
    RENDER --> GENE_VITECFG
    GENE_HTML --> TEMPLATE_HTML
    GENE_VITECFG --> TEMPLATE_VITE
    GENE_HTML --> FS_FILE
    GENE_PKG --> FS_FILE
    GENE_VITECFG --> FS_FILE

    UTIL_COMMON -.-> CLI_CORE
    UTIL_COMMON -.-> CONFIG_CORE
    UTIL_AST -.-> AST_PARSE
    UTIL_CONFIG -.-> CONFIG_CORE
    UTIL_REPORT -.-> CLI_CORE
    UTIL_VERSION -.-> RENDER
    FS_FILE -->|"reads/writes"| CLI_CORE

    EXT_BABEL --- AST_PARSE
    EXT_EJS --- RENDER
    EXT_TS --- CLI_BIN
    EXT_NPM --- RENDER

    click CLI_BIN "https://github.com/originjs/webpack-to-vite/blob/main/bin/index.ts"
    click CLI_CORE "https://github.com/originjs/webpack-to-vite/blob/main/src/cli/cli.ts"
    click CONFIG_CORE "https://github.com/originjs/webpack-to-vite/blob/main/src/config/config.ts"
    click CONFIG_PARSE "https://github.com/originjs/webpack-to-vite/blob/main/src/config/parse.ts"
    click CONFIG_VUECLI "https://github.com/originjs/webpack-to-vite/blob/main/src/config/vuecli.ts"
    click CONFIG_WEBPACK "https://github.com/originjs/webpack-to-vite/blob/main/src/config/webpack.ts"
    click CONFIG_VITE "https://github.com/originjs/webpack-to-vite/blob/main/src/config/vite.ts"
    click AST_PARSE "https://github.com/originjs/webpack-to-vite/blob/main/src/ast-parse/astParse.ts"
    click PARSE_HTML_PROPS "https://github.com/originjs/webpack-to-vite/blob/main/src/ast-parse/parsers/findHtmlConfigProperties.ts"
    click PARSE_HTML_CHAIN "https://github.com/originjs/webpack-to-vite/blob/main/src/ast-parse/parsers/findHtmlPluginChain.ts"
    click PARSE_JSX "https://github.com/originjs/webpack-to-vite/blob/main/src/ast-parse/parsers/findJsxInScriptParser.ts"
    click PARSE_REQ_CTX "https://github.com/originjs/webpack-to-vite/blob/main/src/ast-parse/parsers/findRequireContext.ts"
    click PARSE_WP_PROPS "https://github.com/originjs/webpack-to-vite/blob/main/src/ast-parse/parsers/findWebpackConfigProperties.ts"
    click PARSE_INDEX "https://github.com/originjs/webpack-to-vite/blob/main/src/ast-parse/parsers/index.ts"
    click TRANS_ADD_JSX "https://github.com/originjs/webpack-to-vite/blob/main/src/ast-parse/transformations/addJsxTransformation.ts"
    click TRANS_CHAIN_WP "https://github.com/originjs/webpack-to-vite/blob/main/src/ast-parse/transformations/chainWebpackTransformation.ts"
    click TRANS_HTML_VUE "https://github.com/originjs/webpack-to-vite/blob/main/src/ast-parse/transformations/indexHtmlTransformationVueCli.ts"
    click TRANS_HTML_WP "https://github.com/originjs/webpack-to-vite/blob/main/src/ast-parse/transformations/indexHtmlTransformationWebpack.ts"
    click TRANS_LAZY "https://github.com/originjs/webpack-to-vite/blob/main/src/ast-parse/transformations/lazyLoadingRoutesTransformation.ts"
    click TRANS_REMOVE_LANG "https://github.com/originjs/webpack-to-vite/blob/main/src/ast-parse/transformations/removeHtmlLangInTemplateTransformation.ts"
    click TRANS_INDEX "https://github.com/originjs/webpack-to-vite/blob/main/src/ast-parse/transformations/index.ts"
    click TRANSFORMER "https://github.com/originjs/webpack-to-vite/blob/main/src/transform/transformer.ts"
    click TRANS_VUECLI "https://github.com/originjs/webpack-to-vite/blob/main/src/transform/transformVuecli.ts"
    click TRANS_WEBPACK "https://github.com/originjs/webpack-to-vite/blob/main/src/transform/transformWebpack.ts"
    click TRANS_CONTEXT "https://github.com/originjs/webpack-to-vite/blob/main/src/transform/context.ts"
    click RENDER "https://github.com/originjs/webpack-to-vite/blob/main/src/generate/render.ts"
    click GENE_HTML "https://github.com/originjs/webpack-to-vite/blob/main/src/generate/geneIndexHtml.ts"
    click GENE_PKG "https://github.com/originjs/webpack-to-vite/blob/main/src/generate/genePackageJson.ts"
    click GENE_VITECFG "https://github.com/originjs/webpack-to-vite/blob/main/src/generate/geneViteConfig.ts"
    click TEMPLATE_HTML "https://github.com/originjs/webpack-to-vite/blob/main/src/template/index.html"
    click TEMPLATE_VITE "https://github.com/originjs/webpack-to-vite/blob/main/src/template/vite.config.ejs"
    click UTIL_COMMON "https://github.com/originjs/webpack-to-vite/blob/main/src/utils/common.ts"
    click UTIL_AST "https://github.com/originjs/webpack-to-vite/blob/main/src/utils/astUtils.ts"
    click UTIL_CONFIG "https://github.com/originjs/webpack-to-vite/blob/main/src/utils/config.ts"
    click UTIL_REPORT "https://github.com/originjs/webpack-to-vite/blob/main/src/utils/report.ts"
    click UTIL_VERSION "https://github.com/originjs/webpack-to-vite/blob/main/src/utils/version.ts"
    click FS_FILE "https://github.com/originjs/webpack-to-vite/blob/main/src/utils/file.ts"

    classDef cli fill:#D0E6FF,stroke:#0366d6,color:#0366d6
    classDef config fill:#F0F0F0,stroke:#888888,color:#444444
    classDef parser fill:#DFFFD0,stroke:#2a7d2a,color:#2a7d2a
    classDef transform fill:#FFF4C1,stroke:#a67f00,color:#a67f00
    classDef gen fill:#EAD1DC,stroke:#732673,color:#732673
    classDef utils fill:#F0F0F0,stroke:#888888,color:#444444
    classDef fs fill:#FFE4B5,stroke:#b35100,color:#b35100
    classDef external fill:#E5E5E5,stroke:#666666,color:#333333
```
