Skip to content

README.md

Latest commit

 

History

History
165 lines (115 loc) · 4.59 KB

README.md

File metadata and controls

165 lines (115 loc) · 4.59 KB

React Package Analyzer

A powerful tool for analyzing component usage patterns in React applications. This tool helps you track and understand how UI components from various libraries are used throughout your codebase, making migration planning, dependency management, and codebase analysis easier.

Features

  • Track component usage from multiple UI libraries simultaneously
  • Detect import patterns and component distribution
  • Generate detailed reports in JSON and Markdown formats
  • Automatic detection of import aliases from jsconfig.json or tsconfig.json
  • Dependency chain analysis to understand component relationships
  • Library-agnostic design that works with any React UI component library

Philosophy

React Package Analyzer is built on four core principles:

  • Library-agnostic: Works with any React-based UI library
  • Application-agnostic: Compatible with any React application structure
  • Usage-focused: Analyzes how components are actually used in your codebase
  • Data-driven: Provides objective metrics based on actual usage patterns

For a deeper exploration of these principles and the design philosophy behind this tool, see our Core Philosophy document.

Installation

npm install react-package-analyzer

Usage

The React Package Analyzer is configured using a simple configuration file in your project root.

1. Create a configuration file

Create a file named react-import-analyzer.config.js in your project root:

module.exports = {
    // UI libraries to analyze
    packagesToTrack: [
        '@mui/material',
        '@chakra-ui/react',
    ],
    
    // Output formats (json, markdown, or both)
    format: 'json,markdown',
    
    // GitHub repo URL for linking in reports (optional)
    repoUrl: 'https://github.com/username/project/blob/main',
    
    // Files to include in analysis
    include: 'src/**/*.{js,jsx,ts,tsx}',
    
    // Output directory for reports
    outputDir: './import-analysis'
}

2. Import aliases

The analyzer automatically detects import aliases from your jsconfig.json or tsconfig.json file:

{
  "compilerOptions": {
    "baseUrl": "src",
    "paths": {
      "@components/*": ["components/*"],
      "@pages/*": ["pages/*"],
      "@hooks/*": ["hooks/*"],
      "@utils/*": ["utils/*"],
      "@layouts/*": ["components/layouts/*"]
    }
  },
  "include": ["src"]
}

This allows the analyzer to correctly resolve imports that use aliases like:

import { Button } from '@components/ui/Button';

3. Run the analyzer

After setting up your configuration file, you can run the analyzer in one of the following ways:

If installed globally or locally:

analyze-imports

Using npx (without installing):

npx react-package-analyzer

Using npx with specific version:

npx react-package-analyzer@latest

The tool will automatically detect and use your react-import-analyzer.config.js file.

You can also specify a different configuration file:

npx react-package-analyzer --config custom-config.js

Or run it directly on a specific directory:

npx react-package-analyzer --dir ./src

Example project structure

For an example of a project that uses this tool, see the test project.

Here's an example project structure showing where to place the configuration file:

my-react-app/
├── src/
│   ├── components/
│   ├── pages/
│   └── ...
├── jsconfig.json
├── react-import-analyzer.config.js
└── package.json

Output

The analyzer generates several output files in your specified output directory:

  • raw.jsonl: Detailed component usage data for each file
  • detailed.json: Comprehensive statistics about component usage
  • summary.json: High-level statistics about component usage
  • dependency-chains.json: Maps relationships between files
  • import-intersections.json: Analysis of component import relationships
  • report.md: Human-readable markdown report of all findings

Schema Documentation

For detailed information about the output file formats, please see the schema documentation.

Documentation

  • Core Philosophy - Learn about the underlying principles and design decisions
  • Markdown Reports - Detailed explanation of the generated markdown reports
  • Data Output - Comprehensive guide to the data files produced during analysis

License

MIT See LICENSE for the full license text.