@star4beam/react-package-analyzer v0.0.1-test

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, simply run the following command from your project's root directory:

analyze-imports

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

You can also specify a different configuration file:

analyze-imports --config custom-config.js

Example project structure

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.