Module Migration Tool

English | 中文

This tool helps extract a portion of code from a large project to form an independent smaller project. The tool analyzes all dependencies of the entry file (or directory), recursively finds all related files, and then copies them to a new target directory while maintaining the original directory structure.

This tool can help developers quickly extract code from large projects while keeping all dependency relationships intact, which is particularly useful for teams that need to split monolithic applications into micro-frontends or microservices. The tool is designed with extensibility in mind, making it easy to add support for new file types or customize dependency analysis rules.

Features

• ✅ Analyze static dependencies in JavaScript/TypeScript files
• ✅ Analyze dependencies in Vue single-file components
• ✅ Analyze references in CSS/SCSS/LESS files
• ✅ Automatically handle relative path imports
• ✅ Support alias path resolution (such as @/components)
• ✅ Automatically detect project configuration (such as path aliases in tsconfig.json)
• ✅ Maintain original directory structure
• ✅ Generate visual dependency relationship reports
• ✅ Support single files or entire directories as entry points

Installation

# Install globally (you can also use npx to run without installation)
npm install -g module-migration-tool

# Or install locally in your project
npm install module-migration-tool --save-dev

Or clone the repository and install manually:

# Clone repository
git clone <repository-url>

# Enter project directory
cd migration-tool

# Install dependencies
npm install

# Link globally (optional)
npm link

Usage Process

The basic steps for using this tool are as follows:

1. Specify the source project path
2. Specify the entry file/directory
3. Specify the target path
4. The tool will automatically analyze dependencies and copy all necessary files

You can customize the tool's behavior through command-line parameters or configuration files, such as specifying paths to ignore or configuring alias path mappings.

Usage Methods

Command Line Usage

Using npx (no installation required):

# Basic usage
npx module-migration-tool --source <source directory> --entry <entry file/directory> --target <target directory>

When installed globally, you can use the migrate or module-migrate command:

# Basic usage
module-migrate --source <source directory> --entry <entry file/directory> --target <target directory>

# Example
module-migrate --source ./my-project/src --entry ./my-project/src/components/Feature --target ./new-project

Or if installed locally:

npx module-migrate --source <source directory> --entry <entry file/directory> --target <target directory>

Using Node.js directly:

node src/index.js --source <source directory> --entry <entry file/directory> --target <target directory>

Command Line Parameters

Parameter	Short	Description	Default
--source	-s	Source project path	./src
--entry	-e	Entry file/directory path	./src/index.js
--target	-t	Target path	./dist
--config	-c	Configuration file path	-
--no-report	-	Do not generate dependency report	false
--verbose	-v	Show detailed logs	false

Using Configuration Files

You can create a configuration file to customize the tool's behavior, then specify it with the --config parameter:

// migrate.config.js
module.exports = {
  // Supported file extensions
  extensions: [".js", ".jsx", ".ts", ".tsx", ".vue", ".css"],
  // Paths to ignore
  ignorePaths: ["node_modules", "dist", "test"],
  // Path alias configuration
  alias: {
    "@": "./src",
    "@components": "./src/components",
  },
  // Analysis options
  analysis: {
    includeCss: true,
    includeJson: false,
    includeImages: false,
  },
}

Start the tool using a configuration file:

node src/index.js --config ./migrate.config.js

Dependency Analysis Report

The tool generates an HTML format dependency relationship report that can be opened directly in a browser. The report includes:

• File dependency graph: Visually displays dependencies between files
• File count and dependency statistics: Quickly understand project scale
• File path search functionality: Easily find specific files
• Dependency expand/collapse functionality: Flexibly browse the dependency tree

Architecture Design

The project adopts a modular design, mainly containing the following modules:

• Analyzer Module: Responsible for analyzing dependencies in different types of files
  • JavaScript/TypeScript analyzer
  • CSS analyzer
  • Vue single-file component analyzer
• Resolver Module: Responsible for resolving various import paths
  • Path resolver
  • Alias resolver
• Report Generator: Generates visual dependency relationship reports
• Utility Functions: File operations, configuration management, and other common functionalities

Core Module Description

The project consists of the following core modules, each responsible for specific functionality:

Analyzer Module (analyzers)

• Function: Analyze dependencies in different types of files
• Core Files:
  • jsAnalyzer.js: Analyze import/require statements in JavaScript/TypeScript files
  • cssAnalyzer.js: Analyze @import and url() references in CSS files
  • vueAnalyzer.js: Analyze dependencies in Vue single-file components
  • index.js: Unified analyzer entry, selects the appropriate analyzer based on file type

Resolver Module (resolvers)

• Function: Resolve various types of import paths
• Core Files:
  • pathResolver.js: Handle relative path and absolute path resolution
  • aliasResolver.js: Handle alias path resolution (such as @/components)
  • index.js: Unified path resolver entry

Report Generator (reporters)

• Function: Generate visual dependency relationship reports
• Core Files:
  • htmlReporter.js: Generate HTML format dependency graph reports
  • index.js: Unified report generator entry

Utility Functions (utils)

• Function: Provide common functionality support
• Core Files:
  • fileUtils.js: File operation tools (copy files, ensure directories exist, etc.)
  • configUtils.js: Configuration management (merge configurations, detect project configurations, etc.)

Core Logic Module

• migrator.js: Migration tool core class, coordinates all modules, implements main migration logic
• index.js: Program entry, handles command-line parameters, provides user interface

Project Structure

migration-tool/
├── config/
│   └── default.js         # Default configuration
├── src/
│   ├── analyzers/         # Dependency analysis module
│   │   ├── index.js       # Analyzer entry
│   │   ├── jsAnalyzer.js  # JS/TS file analyzer
│   │   ├── cssAnalyzer.js # CSS file analyzer
│   │   └── vueAnalyzer.js # Vue file analyzer
│   ├── resolvers/         # Path resolution module
│   │   ├── index.js       # Resolver entry
│   │   ├── pathResolver.js  # Basic path resolution
│   │   └── aliasResolver.js # Alias path resolution
│   ├── utils/             # Utility functions
│   │   ├── fileUtils.js   # File operation tools
│   │   └── configUtils.js # Configuration tools
│   ├── reporters/         # Report generator
│   │   ├── index.js       # Reporter entry
│   │   └── htmlReporter.js # HTML report generator
│   ├── migrator.js        # Migration core class
│   └── index.js           # Program entry
├── test/                  # For test code
├── package.json           # Project configuration
└── README.md              # Project instructions

Notes

• The tool mainly handles relative paths and configured alias path imports, automatically ignoring third-party library imports
• If the project uses special path resolution strategies, you may need to customize alias configurations in the configuration file
• Processing large projects may take a significant amount of time, please be patient
• The tool may not identify certain complex dynamic imports or unconventional import methods

Development and Extension

Adding Support for New File Types

If you need to support a new file type, you can create a new analyzer in the src/analyzers directory, implement the analyzeFile method, and then register the analyzer in src/analyzers/index.js.

Customizing Report Format

To customize the dependency report format, you can modify the src/reporters/htmlReporter.js file or implement a completely new report generator, such as JSON or Markdown format.

License

MIT