react-project

Purpose

Provide comprehensive analysis of React projects to help developers understand the frontend codebase quickly. This skill leverages the react-specialist agent to analyze React-specific patterns, Next.js conventions, and modern frontend best practices.

When to Use

Use this skill when you need to:

• Onboard to a React project - Get a complete overview of the frontend architecture
• Understand component structure - Map component hierarchy and relationships
• Count screens/pages - Identify all routes and page components
• Analyze UI patterns - Discover design patterns and component abstractions
• Review custom hooks - Understand shared logic and state patterns
• Examine state management - Identify Context, Zustand, Redux, or other solutions
• Map routing - Understand navigation structure and route organization
• Document the frontend - Generate onboarding documentation

Key Information

Project Structure Patterns

Next.js App Router (v13+)

project/
├── app/
│   ├── layout.tsx           # Root layout
│   ├── page.tsx             # Home page (/)
│   ├── globals.css
│   ├── (auth)/              # Route group
│   │   ├── login/
│   │   │   └── page.tsx     # /login
│   │   └── register/
│   │       └── page.tsx     # /register
│   ├── dashboard/
│   │   ├── layout.tsx       # Nested layout
│   │   ├── page.tsx         # /dashboard
│   │   └── [id]/
│   │       └── page.tsx     # /dashboard/:id
│   └── api/
│       └── route.ts         # API routes
├── components/
│   ├── ui/                  # Base UI components
│   ├── features/            # Feature-specific components
│   └── layouts/             # Layout components
├── hooks/                   # Custom hooks
├── lib/                     # Utilities and helpers
├── stores/                  # State management
└── types/                   # TypeScript types

Next.js Pages Router

project/
├── pages/
│   ├── _app.tsx             # App wrapper
│   ├── _document.tsx        # Document customization
│   ├── index.tsx            # Home page (/)
│   ├── api/                 # API routes
│   └── [slug].tsx           # Dynamic routes
├── components/
├── hooks/
└── styles/

Vite + React SPA

project/
├── src/
│   ├── main.tsx             # Entry point
│   ├── App.tsx              # Root component
│   ├── pages/               # Page components
│   ├── components/
│   ├── hooks/
│   ├── stores/
│   └── routes/              # Route configuration
└── index.html

Analysis Checklist

When analyzing a React project:

1. Identify Framework & Structure

```bash # Check for Next.js grep -l "next" package.json && ls -la app/ pages/ 2>/dev/null

# Check for Vite grep -l "vite" package.json && ls -la src/

# Check package.json for clues cat package.json | grep -E '"(next|vite|react-scripts|gatsby)"' ```

1. Count Pages/Screens

```bash # Next.js App Router pages find app -name "page.tsx" -o -name "page.jsx" | wc -l

# Next.js Pages Router find pages -name ".tsx" -o -name ".jsx" | grep -v "_" | wc -l

# SPA routes (look for route definitions) grep -r "path:" --include="*.tsx" src/routes/ ```

1. Map Components

```bash # Find all components find . -path ./node_modules -prune -o -name "*.tsx" -print | grep -E "(components|ui)/"

# Count components by directory find components -name "*.tsx" | wc -l

# Find component exports grep -r "export.function\|export default" --include=".tsx" components/ ```

1. Analyze Custom Hooks

```bash # Find custom hooks find . -path ./nodemodules -prune -o -name "use.ts" -print find . -path ./nodemodules -prune -o -name "use.tsx" -print

# List hooks directory ls -la hooks/ src/hooks/ 2>/dev/null ```

1. Identify State Management

```bash # Check for state libraries in package.json grep -E "(zustand|redux|recoil|jotai|mobx)" package.json

# Find Context providers grep -r "createContext\|useContext" --include="*.tsx"

# Find Zustand stores grep -r "create\(" --include="*.ts" stores/ ```

1. Review UI Library

```bash # Check for UI libraries grep -E "(@radix-ui|@headlessui|@mui|antd|chakra)" package.json

# Check for Tailwind ls tailwind.config.* 2>/dev/null

# Check for shadcn/ui ls components/ui/ 2>/dev/null ```

Component Patterns

Atomic Design

components/
├── atoms/           # Button, Input, Label
├── molecules/       # FormField, SearchBar
├── organisms/       # Header, Sidebar, Form
├── templates/       # PageLayout, DashboardLayout
└── pages/           # Assembled pages

Feature-Based

features/
├── auth/
│   ├── components/
│   ├── hooks/
│   └── api/
├── dashboard/
│   ├── components/
│   ├── hooks/
│   └── api/
└── settings/

Container/Presentational

components/
├── UserList/
│   ├── UserList.tsx         # Presentational
│   ├── UserListContainer.tsx # Container (data fetching)
│   └── index.ts

State Management Patterns

Output Format

Generate a React project report with:

1. Project Overview

- Framework (Next.js version, Vite, etc.) - React version - TypeScript usage - Key dependencies

1. Page/Screen Inventory

- Total page count - Route structure (tree view) - Dynamic routes - Protected routes

1. Component Architecture

- Component organization pattern - Total component count - Shared vs feature components - Component hierarchy diagram

1. Hooks Analysis

- Custom hooks list - Hook dependencies - Shared logic patterns

1. State Management

- Solution used (Context, Zustand, etc.) - Store structure - Data flow patterns

1. UI/Styling

- CSS solution (Tailwind, CSS Modules, etc.) - UI library (shadcn, Radix, etc.) - Design system patterns

1. Key Files to Read

- Recommended reading order - Entry points - Critical components

Mermaid Diagrams

Component Tree Example

graph TD
    App --> Layout
    Layout --> Header
    Layout --> Sidebar
    Layout --> MainContent
    MainContent --> Dashboard
    MainContent --> Settings
    Dashboard --> StatCard
    Dashboard --> Chart

Route Structure Example

graph LR
    / --> /dashboard
    / --> /settings
    /dashboard --> /dashboard/analytics
    /dashboard --> /dashboard/users
    /settings --> /settings/profile
    /settings --> /settings/security