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

   # 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)"'
   

2. Count Pages/Screens

   # 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/
   

3. Map Components

   # 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/
   

4. Analyze Custom Hooks

   # Find custom hooks
   find . -path ./node_modules -prune -o -name "use*.ts" -print
   find . -path ./node_modules -prune -o -name "use*.tsx" -print
   
   # List hooks directory
   ls -la hooks/ src/hooks/ 2>/dev/null
   

5. Identify State Management

   # 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/
   

6. Review UI Library

   # 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

Pattern	Files to Look For	Use Case
React Context	*Context.tsx, *Provider.tsx	Simple global state
Zustand	stores/*.ts, use*Store.ts	Medium complexity
Redux Toolkit	store/, slices/, *Slice.ts	Complex state
Jotai/Recoil	atoms/, *Atom.ts	Atomic state
React Query	queries/, use*Query.ts	Server state

Output Format

Generate a React project report with:

1. Project Overview

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

2. Page/Screen Inventory

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

3. Component Architecture

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

4. Hooks Analysis

   • Custom hooks list
   • Hook dependencies
   • Shared logic patterns

5. State Management

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

6. UI/Styling

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

7. 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