react

# React Development Guide This skill provides a comprehensive guide for building React components in the project, focusing on performance, state management thresholds, and modular organization. ## 1. Component Architecture ### 1.1 Standard Component Pattern Every component should follow the standard export pattern to ensure responsiveness (MobX) and performance (Memoization). ```typescript import { observer } from 'mobx-react-lite' const Index = (props: IProps) => { const { data } = props return ( <div className='flex flex-col p-4'> {/* Content */} </div> ) } // ✅ Mandatory: For components needing state responsiveness or performance optimization, use $app.handle wrapper export default new $app.handle(Index).by(observer).by($app.memo).get() // ✅ Optional: For simple presentational components, directly use $app.memo export default $app.memo(Index) ``` ### 1.2 Module Splitting (Fractal Architecture) Large modules must be split according to fractal patterns to maintain high maintainability and clear scope. - **Local Components**: Use `components/` folder within the module directory. Component names should be concise (e.g., `Item.tsx`, `Header.tsx`). - **Loop Extraction**: Components rendered in loops (e.g., content inside `.map()`) must be extracted to separate component files to optimize diff rendering performance. - **File Organization**: ``` module/ ├── index.tsx # Entry and layout ├── types.ts # Local type definitions ├── components/ # Local sub-components │ ├── List.tsx │ ├── Item.tsx # Loop item component extraction │ └── index.ts # Internal unified export ├── models/ # (Optional) Local MobX models │ └── Local.ts └── styles/ # (Optional) CSS Modules └── index.module.css ``` ### 1.3 Props Management Pattern To maintain component cleanliness and reference stability, follow these patterns for declaring and passing Props: - **Performance-sensitive Props**: For props that trigger heavy operations (e.g., Ant Design theme configuration, large data trees), use `useMemo`. - **Standard Props**: If they don't trigger expensive re-renders, simple objects can be declared directly. - **Naming**: Always use `props_*` prefix as the naming convention for internal props objects. ## 2. Performance Optimization ### 2.1 Function Reference Management To prevent unnecessary re-renders of child components, all functions (event handlers, callbacks) must have stable references. ```typescript import { useMemoizedFn } from 'ahooks' // ✅ Mandatory: wrap all component-internal functions with useMemoizedFn const handleClick = useMemoizedFn(() => { // Logic handling }) // ✅ Pass stable references to child components <Child onClick={handleClick} /> ``` ### 2.2 Props Comparison Optimization `$app.memo` performs deep comparison. To cooperate with its work and avoid unnecessary checks on heavy objects: - **Reference Type Values**: For non-primitive data type props (objects, arrays), use global `$copy(value)` to pass value-based copies. - **Principle**: Using `$copy` ensures that even if the parent component re-renders and creates new object references, as long as the data content hasn't changed, the child component won't re-render. ```typescript // ✅ Mandatory: pass non-primitive data types through $copy <LargeComponent config={$copy(config_object)} items={$copy(data_array)} /> ``` ### 2.3 Conditional Style Classes Use the global `$cx` (classix) utility for efficient, readable conditional CSS class merging. ```typescript <div className={$cx( 'base-class', isActive && 'active-class', isError ? 'text-red' : 'text-gray' )} /> ``` ## 3. State Management Thresholds ### 3.1 State Hierarchy 1. **Shared State**: Managed by top-level models (e.g., `GlobalModel`), injected via `tsyringe`, obtained using `useGlobal`. 2. **Simple Component State**: If reactive variables/logic blocks are **less than or equal to 4**, manage with standard Hooks (`useState`, `useMemo`). 3. **Complex Component State**: If a component's internal logic exceeds **4 reactive variables**, you must create a standalone MobX model (Local Model) coexisting with that component. ### 3.2 Local Model Implementation Local models also use `tsyringe` dependency injection. ```typescript // module/models/Local.ts import { makeAutoObservable } from 'mobx' import { injectable } from 'tsyringe' @injectable() export class LocalModel { v1 = '' v2 = 0 v3 = [] v4 = false v5 = {} // 5th variable, triggers mandatory Model usage rule constructor() { makeAutoObservable(this, {}, { autoBind: true }) } action() { /* ... */ } } // module/index.tsx const Index = () => { const [local] = useState(() => container.resolve(LocalModel)) return <div onClick={local.action}>{local.v1}</div> } ``` ## 4. Summary Checklist - [ ] Are components exported via `$app.handle` or `$app.memo`? - [ ] Are all component-internal functions wrapped with `useMemoizedFn`? - [ ] Are large object/array props passed using `$copy`? - [ ] Are loop-rendered list items extracted to separate component files? - [ ] Do local component state variables exceed 4? (If yes, transfer to MobX Model) - [ ] Does the directory structure follow fractal patterns?