React Tree Lens 🔍

A powerful React component for visualizing your component hierarchy in real-time. Perfect for debugging, learning React architecture, and understanding component relationships.

✨ What's New (Improved Version)

• 📊 Rich Component Tree: Shows actual component hierarchy with proper nesting
• 🎯 Interactive Interface: Click to expand/collapse nodes and inspect props
• 🔍 Props Inspection: View component props and their values in detail
• 📱 Responsive Design: Beautiful, modern UI that works on all screen sizes
• ⚡ Zero Configuration: Just wrap your app and start exploring
• 🎨 Visual Icons: Different icons for components, HTML elements, and text nodes

🚀 Quick Start

Installation

npm install react-tree-lens

TypeScript Support

This package includes full TypeScript support with exported type definitions.

Basic Usage

import React from 'react';
import { ReactTreeProvider, TreeViewer, useReactTree } from 'react-tree-lens';
import type { ReactTreeProviderProps, TreeNode, TreeContext } from 'react-tree-lens';

// Basic setup
function App() {
  return (
    <ReactTreeProvider showTreeViewer={true} position="right" theme="dark">
      <YourAppContent />
    </ReactTreeProvider>
  );
}

// Using the hook with proper typing
function MyComponent() {
  const treeContext: TreeContext = useReactTree();
  
  return (
    <div>
      <button onClick={treeContext.toggleVisibility}>
        Toggle Tree View
      </button>
    </div>
  );
}

Type Definitions

import type {
  TreeNode,           // Tree structure interface
  ReactTreeProviderProps, // Provider props
  TreeContext,        // Context interface
  TreePosition,       // 'left' | 'right' | 'top' | 'bottom'
  TreeTheme,          // 'light' | 'dark'
  TreeNodeType,       // 'component' | 'html' | 'text'
  TreeViewerProps,    // TreeViewer component props
  UseReactTreeReturn  // Hook return type
} from 'react-tree-lens';

Advanced Usage

import React from 'react';
import { ReactTreeProvider, TreeViewer } from 'react-tree-lens';
import type { ReactTreeProviderProps, TreePosition, TreeTheme } from 'react-tree-lens';

interface CustomAppProps {
  children: React.ReactNode;
  debugMode?: boolean;
}

function CustomApp({ children, debugMode = false }: CustomAppProps) {
  const position: TreePosition = 'right';
  const theme: TreeTheme = 'dark';
  
  const providerProps: ReactTreeProviderProps = {
    children,
    showTreeViewer: debugMode,
    position,
    theme
  };

  return (
    <ReactTreeProvider {...providerProps}>
      {children}
    </ReactTreeProvider>
  );
}

📖 Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | children | ReactNode | - | Your React application components | | showTreeViewer | boolean | true | Whether to show the tree viewer initially | | position | 'left' \| 'right' \| 'top' \| 'bottom' | 'left' | Position of the tree viewer | | theme | 'light' \| 'dark' | 'light' | Color theme (coming soon) |

🎯 Features

Real-time Component Analysis

• Live Updates: Tree structure updates as your components change
• Component Types: Distinguishes between React components, HTML elements, and text nodes
• Hierarchy Visualization: Clear parent-child relationships with proper indentation

Interactive Tree Viewer

• Expandable Nodes: Click arrows to expand/collapse component branches
• Node Selection: Click on any component to see its details
• Props Inspector: View all props passed to selected components
• Component Count: Shows total number of components in your tree

Modern UI

• Clean Design: Minimal, developer-friendly interface
• Color Coding: Components, HTML elements, and text have different colors
• Responsive Layout: Adapts to different screen sizes and positions
• Floating Toggle: Easy-to-access eye button to show/hide the tree

🔧 How It Works

The React Tree Lens analyzes the component structure by:

1. Wrapping Your App: Provides context to all child components
2. Parsing Elements: Recursively analyzes React elements and their children
3. Building Tree Structure: Creates a hierarchical representation of your components
4. Real-time Updates: Rebuilds the tree when components change

🎨 Visual Legend

• 🔵 Component: Custom React components
• 🟢 HTML Element: Native HTML tags (div, span, button, etc.)
• ⚪ Text Node: String and number content

📱 Demo

Visit our live demo to see the tree viewer in action with different component patterns:

• Basic Components: Simple component hierarchy
• Form Components: Complex forms with validation
• Deeply Nested: Multi-level component nesting
• Dynamic Content: Components with conditional rendering

🛠️ Development

To run this project locally:

# Clone the repository
git clone <your-repo-url>
cd react-tree-lens

# Install dependencies
npm install

# Start development server
npm run dev

# Open http://localhost:4000

📝 Important Notes

Current Limitations

• Component Boundaries: The tree viewer can only show components that are direct children of ReactTreeProvider
• Internal State: Cannot inspect component state or hooks (only props)
• Performance: Large component trees may impact performance

Best Practices

• Use in development mode for debugging and learning
• Position the tree viewer where it doesn't interfere with your app
• Consider the tree viewer size when positioning on smaller screens

🔮 Roadmap

• [ ] State Inspection: View component state and hooks
• [ ] Performance Metrics: Show render times and optimization opportunities
• [ ] Component Search: Filter and search through component tree
• [ ] Export Tree: Save component hierarchy as JSON or image
• [ ] Dark Theme: Full dark mode support
• [ ] React DevTools Integration: Connect with React DevTools

🤝 Contributing

We welcome contributions! Please feel free to submit issues and pull requests.

📄 License

MIT License - see LICENSE file for details.

Made with ❤️ for the React community

Perfect for developers who want to understand and visualize their React component architecture.