Modern React Project Template - Agents.md Example

Modern React Project Development Guide

Project Overview

This is a modern frontend project template based on React 18, TypeScript, and Vite. It's suitable for building high-performance Single Page Applications (SPA) with integrated modern development toolchain and best practices.

Tech Stack

• Frontend Framework: React 18 + TypeScript
• Build Tool: Vite
• State Management: Zustand / Redux Toolkit
• Routing: React Router v6
• UI Components: Ant Design / Material-UI
• Styling: Tailwind CSS / Styled-components
• HTTP Client: Axios
• Testing Framework: Vitest + React Testing Library
• Code Quality: ESLint + Prettier + Husky

Project Structure

react-project/
├── public/                 # Static assets
│   ├── favicon.ico
│   └── index.html
├── src/
│   ├── components/         # Reusable components
│   │   ├── common/        # Common components
│   │   └── ui/            # UI components
│   ├── pages/             # Page components
│   ├── hooks/             # Custom Hooks
│   ├── store/             # State management
│   ├── services/          # API services
│   ├── utils/             # Utility functions
│   ├── types/             # TypeScript type definitions
│   ├── styles/            # Global styles
│   ├── constants/         # Constants
│   ├── App.tsx
│   └── main.tsx
├── tests/                 # Test files
├── docs/                  # Project documentation
├── .env.example          # Environment variables example
├── package.json
├── tsconfig.json
├── vite.config.ts
└── README.md

Development Guidelines

Component Development Standards

1. Function Components First: Use function components and Hooks
2. TypeScript Types: Define interfaces for all props
3. Component Naming: Use PascalCase, file name matches component name
4. Single Responsibility: Each component handles only one functionality

// Example: Button Component
interface ButtonProps {
  variant: 'primary' | 'secondary' | 'danger';
  size?: 'small' | 'medium' | 'large';
  disabled?: boolean;
  onClick?: () => void;
  children: React.ReactNode;
}

export const Button: React.FC<ButtonProps> = ({
  variant,
  size = 'medium',
  disabled = false,
  onClick,
  children
}) => {
  return (
    <button
      className={`btn btn-${variant} btn-${size}`}
      disabled={disabled}
      onClick={onClick}
    >
      {children}
    </button>
  );
};

State Management Standards

Using Zustand for state management:

// store/userStore.ts
import { create } from 'zustand';

interface User {
  id: string;
  name: string;
  email: string;
}

interface UserState {
  user: User | null;
  isLoading: boolean;
  setUser: (user: User) => void;
  clearUser: () => void;
  setLoading: (loading: boolean) => void;
}

export const useUserStore = create<UserState>((set) => ({
  user: null,
  isLoading: false,
  setUser: (user) => set({ user }),
  clearUser: () => set({ user: null }),
  setLoading: (isLoading) => set({ isLoading }),
}));

API Service Standards

// services/api.ts
import axios from 'axios';

const api = axios.create({
  baseURL: import.meta.env.VITE_API_URL,
  timeout: 10000,
});

// Request interceptor
api.interceptors.request.use((config) => {
  const token = localStorage.getItem('token');
  if (token) {
    config.headers.Authorization = `Bearer ${token}`;
  }
  return config;
});

// Response interceptor
api.interceptors.response.use(
  (response) => response.data,
  (error) => {
    console.error('API Error:', error);
    return Promise.reject(error);
  }
);

export default api;

Environment Setup

Development Requirements

• Node.js >= 18.0.0
• npm >= 8.0.0 or yarn >= 1.22.0

Installation Steps

# 1. Create project
npm create vite@latest my-react-app -- --template react-ts

# 2. Navigate to project directory
cd my-react-app

# 3. Install dependencies
npm install

# 4. Install additional dependencies
npm install zustand react-router-dom axios
npm install -D @types/node

# 5. Start development server
npm run dev

Environment Variables Configuration

# .env.local
VITE_API_URL=http://localhost:3001/api
VITE_APP_TITLE=My React App
VITE_ENABLE_MOCK=false

Routing Configuration

// App.tsx
import { BrowserRouter, Routes, Route } from 'react-router-dom';
import { HomePage } from './pages/HomePage';
import { AboutPage } from './pages/AboutPage';
import { NotFoundPage } from './pages/NotFoundPage';

function App() {
  return (
    <BrowserRouter>
      <Routes>
        <Route path="/" element={<HomePage />} />
        <Route path="/about" element={<AboutPage />} />
        <Route path="*" element={<NotFoundPage />} />
      </Routes>
    </BrowserRouter>
  );
}

export default App;

Testing Strategy

Unit Testing Example

// tests/components/Button.test.tsx
import { render, screen, fireEvent } from '@testing-library/react';
import { Button } from '../src/components/Button';

describe('Button Component', () => {
  test('renders button with text', () => {
    render(<Button variant="primary">Click me</Button>);
    expect(screen.getByText('Click me')).toBeInTheDocument();
  });

  test('calls onClick when clicked', () => {
    const handleClick = vi.fn();
    render(
      <Button variant="primary" onClick={handleClick}>
        Click me
      </Button>
    );
    
    fireEvent.click(screen.getByText('Click me'));
    expect(handleClick).toHaveBeenCalledTimes(1);
  });
});

Performance Optimization

Code Splitting

import { lazy, Suspense } from 'react';

const LazyComponent = lazy(() => import('./LazyComponent'));

function App() {
  return (
    <Suspense fallback={<div>Loading...</div>}>
      <LazyComponent />
    </Suspense>
  );
}

Memory Optimization

import { memo, useMemo, useCallback } from 'react';

const ExpensiveComponent = memo(({ data, onUpdate }) => {
  const processedData = useMemo(() => {
    return data.map(item => ({ ...item, processed: true }));
  }, [data]);

  const handleUpdate = useCallback((id) => {
    onUpdate(id);
  }, [onUpdate]);

  return (
    <div>
      {processedData.map(item => (
        <div key={item.id} onClick={() => handleUpdate(item.id)}>
          {item.name}
        </div>
      ))}
    </div>
  );
});

Deployment Configuration

Build Production Version

npm run build

Vite Configuration Optimization

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          vendor: ['react', 'react-dom'],
          router: ['react-router-dom'],
        },
      },
    },
  },
  server: {
    port: 3000,
    open: true,
  },
});

Common Issues

Issue 1: Vite Development Server Slow Startup

Solution:

• Check dependency pre-build cache
• Use npm run dev -- --force to force rebuild
• Optimize optimizeDeps configuration in vite.config.ts

Issue 2: TypeScript Type Errors

Solution:

• Ensure correct type definition packages are installed
• Check tsconfig.json configuration
• Use npm run type-check for type checking

Reference Resources

• React Official Documentation
• Vite Official Documentation
• TypeScript Official Documentation
• React Router Documentation
• Zustand Documentation