ReactLens

[!WARNING] Beta: We're still refining the algorithms and adding features. Expect changes.

ReactLens is a CLI tool that gives you a deep "X-ray" view of your React and Next.js projects. We use AST analysis to find complexity, circular dependencies, and unused files so you can keep your architecture clean.

Quick Start

You don't need to configure anything. Pick the method that works best for you:

1. Try it instantly (No installation)

Ideal for a quick architectural audit right now:

# Generates a beautiful HTML report of your ./src folder
npx @mohamed_fadl/reactlens analyze ./src --html reactlens-report.html

2. Add to your Project (Recommended for Teams)

Ideal for standardizing your team's workflow:

npm install -D @mohamed_fadl/reactlens

Add this shortcut to your package.json:

"scripts": {
  "lens:report": "reactlens analyze ./src --html reactlens-report.html"
}

Now, anyone on your team can generate the report by simply running:

npm run lens:report

3. Global Installation

Ideal if you want to use the tool across multiple projects on your personal machine:

npm install -g @mohamed_fadl/reactlens
reactlens analyze ./src --html report.html

Core Features & Usage

The HTML Dashboard (Evidence-Based)

Generate an interactive dashboard that proves every warning:

reactlens analyze ./src --html report.html

• Project Fingerprint: Every report embeds your project name and a sample of files.
• Transparent Evidence: Every architectural warning (like an oversized file) includes an Evidence block showing the exact AST line numbers that triggered the flag. Zero false-positives.

CI/CD Quality Gates

You can block Pull Requests if the codebase health drops below a certain threshold:

reactlens analyze ./src --fail-under 80

JSON Export

Export raw JSON for your CI/CD pipelines to parse:

reactlens analyze --json report.json --silent

How we calculate the Score

We look at three main pillars:

1. Complexity (40%): We check for massive components and "prop-heavy" code.
2. Coupling (40%): We look for circular dependencies that tangle your codebase.
3. Zombies (20%): We find files that aren't actually being used.

Dependency Visualizer

ReactLens can also generate a map of your modules (.svg, .png, .dot):

reactlens graph ./src --output arch.svg

(Note: The graph command requires Graphviz (2.40+) to be installed on your system. E.g., winget install graphviz on Windows or brew install graphviz on macOS).

License

This project is open-source and available under the MIT License.

Built with passion for clean architecture by Mohamed Fadl. Contributions, issues, and feature requests are welcome!