mystuff_frontend/AGENTS.md

name, description, category, author, authorUrl, tags, lastUpdated

name	description	category	author	authorUrl	tags	lastUpdated
Modern React Project Template	A comprehensive development guide for modern frontend projects based on React 18 + TypeScript + Vite, including complete development standards and best practices	Frontend Framework	Agents.md Collection	https://github.com/gakeez/agents_md_collection	react typescript vite frontend spa	2024-12-19

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 4 with shadcn/ui component library
• Testing Framework: Vitest + React Testing Library
• Code Quality: ESLint + Prettier + Husky
• UI Components: Complete shadcn/ui component set (New York style) with Lucide icons

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,
  },
});

Styling

1. Use the shadcn/ui library unless the user specifies otherwise.
2. Avoid using indigo or blue colors unless specified in the user's request.
3. MUST generate responsive designs.
4. The Code Project is rendered on top of a white background. If a different background color is needed, use a wrapper element with a background color Tailwind class.

---

UI/UX Design Standards

Visual Design

• Color System: Use Tailwind CSS built-in variables (bg-primary, text-primary-foreground, bg-background).
• Color Restriction: NO indigo or blue colors unless explicitly requested.
• Theme Support: Implement light/dark mode with next-themes.
• Typography: Consistent hierarchy with proper font weights and sizes.

Responsive Design (MANDATORY)

• Mobile-First: Design for mobile, then enhance for desktop.
• Breakpoints: Use Tailwind responsive prefixes (sm:, md:, lg:, xl:).
• Touch-Friendly: Minimum 44px touch targets for interactive elements.

Layout (MANDATORY)

• Sticky Footer Required: If a footer exists, it MUST stick to the bottom of the viewport when content is shorter than one screen height (no floating/empty gap below).
• Natural Push on Overflow: When content exceeds the viewport height, the footer MUST be pushed down naturally (never overlay or cover content).
• Recommended Implementation (Tailwind): Use a root wrapper with min-h-screen flex flex-col, and apply mt-auto to the footer.
• Mobile Safe Area: On devices with safe areas (e.g., iOS), the footer MUST respect bottom safe area insets when applicable.

Accessibility (MANDATORY)

• Semantic HTML: Use main, header, nav, section, article.
• ARIA Support: Proper roles, labels, and descriptions.
• Screen Readers: Use sr-only class for screen reader content.
• Alt Text: Descriptive alt text for all images.
• Keyboard Navigation: Ensure all elements are keyboard accessible.

Interactive Elements

• Loading States: Show spinners/skeletons during async operations.
• Error Handling: Clear, actionable error messages.
• Feedback: Toast notifications for user actions.
• Animations: Subtle Framer Motion transitions (hover, focus, page transitions).
• Hover Effects: Interactive feedback on all clickable elements.

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