guidelines.md

Code Review Guidelines for TypeScript (TS) and React (TSX)

1. Type Safety & Typings

• Always use explicit types for function arguments, return values, and variables.
• Avoid using any. Use unknown or proper generics if type is uncertain.
• Prefer interfaces over types for object shapes, especially for props and state.
• Use enums or union types for fixed sets of values.

2. React Component Best Practices

• Use functional components and React hooks. Avoid class components unless necessary.
• Destructure props and state at the top of the component.
• Define prop types with TypeScript interfaces and use React.FC<Props>.
• Avoid inline functions in JSX; define handlers outside render.
• Memoize expensive computations and callbacks with useMemo and useCallback.
• Use useEffect dependencies correctly; never leave the dependency array empty unless intentional.

3. Code Structure & Readability

• Keep components small and focused; one component per file.
• Extract reusable logic into custom hooks or utility functions.
• Group related files (component, styles, tests) together.
• Use clear, descriptive names for variables, functions, and components.
• Remove dead code, commented-out code, and unused imports.

4. State Management

• Prefer local state for UI logic; use context or state libraries (Apollo) for shared/global state.
• Avoid prop drilling; use context or composition.
• Keep state minimal and normalized.

5. Error Handling & Edge Cases

• Handle all async errors with try/catch or error boundaries.
• Validate all external data (API responses, user input).
• Provide fallback UI for loading and error states.

6. Performance

• Avoid unnecessary re-renders (memoize components, use keys correctly).
• Use lazy loading for heavy components and code splitting for routes.
• Avoid deep prop chains and large prop objects.

7. Testing

• Write unit tests for all logic-heavy functions and components.
• Use React Testing Library for component tests; avoid testing implementation details.
• Mock external dependencies and APIs.

8. Accessibility (a11y)

• Use semantic HTML elements and ARIA attributes where needed.
• Ensure all interactive elements are keyboard accessible.
• Provide alt text for images and labels for form fields.

9. Styling

• Use CSS modules, styled-components, or emotion for scoped styles.
• Avoid global styles unless necessary.
• Prefer className over inline styles for maintainability.

10. Code Consistency

• Follow project linting and formatting rules (Prettier, ESLint).
• Keep imports ordered and grouped (external, internal, styles).
• Use single quotes and trailing commas as per project conventions.

---

Review every PR for these points. Leave actionable, specific feedback.