label-studio / rules

---
description: React coding standards and best practices for the LabelStudio clientside application
globs: **/*.jsx,**/*.tsx
---

# React Best Practices

## Project Structure
- All frontend code lives in the `web` directory
- Main application code is in `web/apps/labelstudio`
- Shared libraries are in `web/libs`
- Follow the established directory structure:
  - `components/`: Reusable UI components
  - `pages/`: Top-level page components
  - `utils/`: Utility functions
  - `hooks/`: Custom React hooks
  - `atoms/`: Jotai atom state definitions
  - `providers/`: Context providers
  - `services/`: API and other services
  - `types/`: TypeScript type definitions
  - `assets/`: Static assets

## Component Structure
- Use functional components over class components
- Keep components small and focused
- Extract reusable logic into custom hooks
- Use composition over inheritance
- Implement proper prop types with TypeScript
- Split large components into smaller, focused ones
- Follow a consistent file organization pattern:
  ```
  component-name/
    component-name.tsx
    component-name.module.css
    component-name.test.tsx
    index.ts
  ```

## Hooks
- Follow the Rules of Hooks
- Use custom hooks for reusable logic
- Keep hooks focused and simple
- Avoid useEffect unless absolutely required
- Use appropriate dependency arrays in useEffect
- Implement cleanup in useEffect when needed
- Avoid nested hooks

## State Management
- Use useState for local component state
- Use Jotai atoms and not the Context API for shared state
- Implement atomWithReducer for complex state logic
- Implement atomWithQuery for any API requests for data
- Keep state as close to where it's used as possible
- Avoid prop drilling through proper state management
- Only use Jotai as the single source of truth of global state management

## Performance
- Implement proper memoization (useMemo, useCallback)
- Use React.memo for expensive components
- Avoid unnecessary re-renders
- Implement proper lazy loading
- Use proper key props in lists
- Profile and optimize render performance

## Tooling
- Use Biome for code linting and formatting
- Follow CSS linting rules defined in biome.json (css section)
- Use TypeScript for type safety
- Keep bundle size in check by monitoring imports

## Forms
- Use controlled components for form inputs
- Implement proper form validation
- Handle form submission states properly
- Show appropriate loading and error states
- Use form libraries for complex forms
- Implement proper accessibility for forms

## Error Handling
- Implement Error Boundaries
- Handle async errors properly
- Show user-friendly error messages
- Implement proper fallback UI
- Log errors appropriately
- Handle edge cases gracefully

## Testing
- Write unit tests for components
- Implement integration tests for complex flows
- Use React Testing Library
- Test user interactions
- Test error scenarios
- Implement proper mock data

## Accessibility
- Ensure components meet WCAG 2.1 AA standards
- Use semantic HTML elements
- Implement proper ARIA attributes
- Ensure keyboard navigation
- Test with screen readers
- Handle focus management
- Provide proper alt text for images

## Code Organization
- Use proper file naming conventions which is kebab-case ie. ListItem -> `list-item.tsx`
- Prefer one component per folder, but group related components together when necessary, and ensure there is only one component per file.
- Component folders should have a CSS `.module.css` with the name of the component kebab-case ie. ListItem -> `list-item.module.css`
- Implement proper directory structure
- UI components live within `web/libs/ui`
- Application components that are shared across applications such as certain page-level blocks live within `web/libs/app-common`
- Code in `web/apps` can only import code from `web/libs` and `web/libs` cannot import from `web/apps`
- Code in `web/libs/app-common` can only import code from other `web/libs` or `web/apps`. No other `web/libs` can import from `web/libs/app-common`
- Keep atoms in a global atoms folder with the name of the file matching the entity or intent of state
- Add all components and their states to Storybook by co-locating the story file next to the component file ie. `list-item.stories.tsx`
- Use the `@humansignal/ui` package for UI components
- Use the `@humansignal/icons` package for icons
- Use the `@humansignal/core` package for core utilities/functions
- Use the `@humansignal/app-common` package for application components

## Best Practices
- No cyclic imports
- Use proper imports/exports
- Follow established import ordering
- Compose components rather than extending them
- Keep components focused on a single responsibility
- Document complex logic with clear comments
- Follow the project's folder structure and naming conventions
- Prefer controlled components over uncontrolled ones 

More agent context in HumanSignal/label-studio

8 other files this repository gives its agents.