twake-react-conventions

---
name: twake-react-conventions
description: Use when writing, reviewing, or refactoring React components in Twake/Cozy frontend projects. Enforces functional components, React.memo usage, event handler naming, no inline styles, and twake-mui first with cozy-ui as fallback (never raw Material-UI).
license: MIT
---

# React Conventions (Twake / Cozy)

Apply these rules whenever you are writing or modifying React code in a Twake or Cozy frontend project.

## Components

- **Use functional components only** for any new code. Do not write class components.
- **One component per file** when the component is non-trivial.

Export, async, naming, and other language-level rules follow `twake-javascript-conventions` (and `twake-typescript-conventions` for `.tsx`) — including **named exports only, never `export default`**.

## Performance

- Use `React.memo` **only** for medium-to-large components that render frequently with identical props. Don't memo everything — it adds cost and complexity.
- Prefer `useMemo` / `useCallback` only when profiling shows a need, or when passing stable references to memoized children.

## Event handlers

- **Named handlers** over inline arrow functions in JSX when the handler is non-trivial.
  ```jsx
  // ✅ Good
  const handleSubmit = () => { ... }
  return <form onSubmit={handleSubmit} />

  // ❌ Avoid for non-trivial logic
  return <form onSubmit={() => { /* lots of logic */ }} />
  ```
- Name handlers `handleX` or `onX` consistently within a file.

## UI library

Twake / Cozy React projects use two in-house component libraries. **Never import Material-UI (`@mui/material`) directly in application code** — always go through one of these design systems.

| Library | Based on | Status | Role |
|---|---|---|---|
| [`twake-mui`](https://github.com/linagora/twake-ui) | MUI **v7** | Modern, early stage (limited catalogue) | **First choice** — use whenever the component you need exists here |
| [`cozy-ui`](https://github.com/cozy/cozy-ui) | MUI **v4** | Mature, outdated, very complete | **Fallback** when `twake-mui` does not yet provide the component or variant |

This order reflects the soft migration toward MUI v7: reach for `twake-mui` first, and only drop back to `cozy-ui` when `twake-mui` is missing what you need.

### When neither library has what you need

**Do not** reach for raw MUI, do not invent a workaround, do not copy-paste a stripped-down version, and do not fall back to inline styles.

**Stop and ask the user** what to do. Typical options they may choose:
- Add the missing component/variant to `twake-mui` (preferred) or `cozy-ui` first, then use it
- Use a close-enough existing component with documented trade-offs
- Escalate to the design-system maintainers

Phrase the question concretely: name the component you need, the variant or prop that is missing, whether you already checked both libraries, and the place where you would use it.

## Styling

**No inline styles.** Do not use the `style={{...}}` prop in JSX and do not inline CSS strings. Styling must go through the design system:

```jsx
// ❌ Forbidden
<div style={{ padding: 16, color: 'red' }}>...</div>

// ✅ Good — use a cozy-ui / twake-mui component with its documented props
<Stack spacing={2}>
  <Typography color="error">...</Typography>
</Stack>
```

Same rule as the UI library section: if `cozy-ui` / `twake-mui` does not expose the style variant you need, **ask the user** — do not fall back to inline styles or raw MUI `sx`.

## Testing

See the dedicated `twake-frontend-testing` skill for testing rules (testing-library, `data-testid`, `queryBy` patterns, colocated `*.spec.jsx` files, no snapshots).

## Dependency rules for libraries

If you are working inside a shared library (not an app):
- `react` and `react-dom` go in `devDependencies` **and** `peerDependencies` — never in `dependencies`.
- Do not import Material-UI at all.
- Do not add cross-dependencies between `cozy-*` libraries.
- **Never import `cozy-flags` in a library.** Feature flags (`flag('...')`) are an app-level concern. A library component that needs flag-gated behavior must expose a boolean prop with a sensible default; the app reads the flag and passes it as the prop value.

```jsx
// ❌ Library reads the flag directly
import flag from 'cozy-flags'
const FederatedModal = () =>
  flag('drive.federated') ? <A /> : <B />

// ✅ Library exposes a boolean prop
const FederatedModal = ({ isFederatedMode = false }) =>
  isFederatedMode ? <A /> : <B />

// ✅ App consumes the flag and feeds the prop
import flag from 'cozy-flags'
<FederatedModal isFederatedMode={flag('drive.federated')} />
```