React & Frontend Engineering

React & Frontend Engineering Standards

This skill governs development within ReactComponents/ and the ga-client application. It standardizes the usage of React, TypeScript, Material UI, and React Three Fiber.

1. Technology Stack Compliance

• Framework: React 18+ (Functional Components only).
• Language: TypeScript 5.0+ (Strict mode).
• Build System: Vite.
• UI Library: Material UI (MUI) v5.
• 3D Visualization: React Three Fiber (R3F) / Three.js.
• State Management: React Context or Zustand (Avoid Redux unless necessary).
• Testing: Playwright (E2E/UI).

2. Component Architecture

2.1 File Structure

• Paths: src/components/<Feature>/<ComponentName>.tsx
• Exports: Use named exports. export const MyComponent = ...
• Props Interface: Define props interface immediately above the component.

// DO:
interface FretboardProps {
    tuning: number[];
    showNotes: boolean;
}

export const Fretboard: React.FC<FretboardProps> = ({ tuning, showNotes }) => { ... };

2.2 Hooks & Logic

• Custom Hooks: Extract complex logic into src/hooks/use<Feature>.ts.
• Side Effects: Isolate useEffect calls. Avoid deep dependency chains.
• Memoization: Use useMemo for expensive calculations (e.g., generating fretboard geometry or theory analysis).

3. 3D & Visualization (React Three Fiber)

3.1 Separation of Concerns

• Scene Graph: Declarative R3F components for structural objects.
• Animation: Use useFrame for per-frame updates. Never put state updates or heavy logic inside useFrame.
• References: Use useRef to manipulate Three.js objects directly for performance (avoiding React re-renders for simple transforms).

// DO:
const ref = useRef<THREE.Mesh>(null);
useFrame(() => {
    if (ref.current) ref.current.rotation.x += 0.01;
});

3.2 Performance

• Instancing: Use <InstancedMesh> for repetitive elements like frets or markers.
• Geometry/Materials: Reuse geometries and materials globally or memoize them.