---
name: react-patterns
description: Modern React patterns and best practices. Implements hooks, context,
  composition, and performance optimization patterns. Use when user mentions "react
  patterns", "hooks", "react best practices", "component design", "react optimization".
author: Descomplicar® Crescimento Digital
version: 2.0.0
quality_score: 80
user_invocable: true
desk_task: 1478
---

# React Patterns

Skill para desenvolvimento React seguindo padrões modernos (React 18+/19).

> **Regra #48:** Projectos React (incluindo Next.js) devem ser desenvolvidos no **container dev** (`server:"dev"`, path `/root/Dev/<projecto>`). Sincroniza automaticamente com o PC local via Syncthing.

## Quando Usar

- Desenvolver componentes React
- Implementar state management
- Optimizar performance (memoization, lazy loading)
- Migrar de class components para hooks
- Usar Server Components (Next.js App Router)

## Regras Core

### Hooks Fundamentais

```jsx
// ✅ useState - estado simples
const [count, setCount] = useState(0)
const [user, setUser] = useState<User | null>(null)

// ✅ useEffect - side effects
useEffect(() => {
  fetchData()
  return () => cleanup() // cleanup function
}, [dependency]) // array dependências

// ✅ useCallback - memoizar funções
const handleClick = useCallback(() => {
  doSomething(id)
}, [id])

// ✅ useMemo - memoizar valores computados
const expensiveValue = useMemo(() => {
  return computeExpensive(data)
}, [data])

// ✅ useRef - referências mutáveis
const inputRef = useRef<HTMLInputElement>(null)
```

### Component Patterns

```jsx
// ✅ CORRECTO: Functional components
function UserCard({ user, onSelect }: Props) {
  return (
    <div onClick={() => onSelect(user.id)}>
      {user.name}
    </div>
  )
}

// ✅ CORRECTO: Composition over props drilling
function Layout({ children }) {
  return <main className="container">{children}</main>
}

// ❌ ERRADO: Class components (legacy)
class UserCard extends React.Component { ... }
```

### State Management

```jsx
// ✅ Local state: useState
// Para estado de um componente

// ✅ Shared state: Context + useReducer
const AppContext = createContext<AppState | null>(null)

function AppProvider({ children }) {
  const [state, dispatch] = useReducer(reducer, initialState)
  return (
    <AppContext.Provider value={{ state, dispatch }}>
      {children}
    </AppContext.Provider>
  )
}

// ✅ Server state: React Query / SWR
const { data, isLoading } = useQuery({
  queryKey: ['users'],
  queryFn: fetchUsers,
})

// ❌ ERRADO: Redux para tudo
// ❌ ERRADO: Estado global para estado local
```

### Server Components (Next.js 13+)

```jsx
// ✅ Server Component (default) - async, data fetching
async function UserList() {
  const users = await db.users.findMany() // Direct DB access
  return <ul>{users.map(u => <li key={u.id}>{u.name}</li>)}</ul>
}

// ✅ Client Component - interactividade
'use client'
function Counter() {
  const [count, setCount] = useState(0)
  return <button onClick={() => setCount(c => c + 1)}>{count}</button>
}

// ✅ Padrão: Server parent + Client children
// page.tsx (Server) → InteractiveSection.tsx ('use client')
```

### Performance

```jsx
// ✅ Lazy loading componentes
const HeavyComponent = lazy(() => import('./HeavyComponent'))

<Suspense fallback={<Loading />}>
  <HeavyComponent />
</Suspense>

// ✅ React.memo para componentes puros
const MemoizedCard = memo(function Card({ data }) {
  return <div>{data.title}</div>
})

// ✅ Virtualização para listas grandes
import { useVirtualizer } from '@tanstack/react-virtual'
```

## Anti-Patterns

| Anti-Pattern | Problema | Solução |
|--------------|----------|---------|
| useEffect para tudo | Complexidade | Server Components / React Query |
| Props drilling | Manutenção | Context ou Composition |
| Inline functions em JSX | Re-renders | useCallback |
| State em URL | Perda estado | URL state com hooks |
| Class components | Legacy | Functional + Hooks |
| Index como key | Bugs listas | ID único |

## Checklist Componente

- [ ] Functional component (não class)
- [ ] TypeScript types/interfaces
- [ ] Props destructuring com defaults
- [ ] Hooks no topo (não condicionais)
- [ ] Keys únicos em listas
- [ ] Error boundaries para erros
- [ ] Loading states considerados

## Estrutura Ficheiros

```
components/
├── ui/           # Componentes base (Button, Input, Card)
├── features/     # Componentes feature-specific
├── layouts/      # Layout components
└── providers/    # Context providers

hooks/
├── useAuth.ts
├── useLocalStorage.ts
└── useDebounce.ts
```

## Custom Hooks Úteis

### useDebounce

```tsx
function useDebounce<T>(value: T, delay: number): T {
  const [debouncedValue, setDebouncedValue] = useState(value);

  useEffect(() => {
    const timer = setTimeout(() => setDebouncedValue(value), delay);
    return () => clearTimeout(timer);
  }, [value, delay]);

  return debouncedValue;
}

// Uso
const searchTerm = useDebounce(input, 500);
```

### useLocalStorage

```tsx
function useLocalStorage<T>(key: string, initialValue: T) {
  const [storedValue, setStoredValue] = useState<T>(() => {
    try {
      const item = window.localStorage.getItem(key);
      return item ? JSON.parse(item) : initialValue;
    } catch {
      return initialValue;
    }
  });

  const setValue = (value: T | ((val: T) => T)) => {
    const valueToStore = value instanceof Function ? value(storedValue) : value;
    setStoredValue(valueToStore);
    window.localStorage.setItem(key, JSON.stringify(valueToStore));
  };

  return [storedValue, setValue] as const;
}
```

### useFetch

```tsx
function useFetch<T>(url: string) {
  const [data, setData] = useState<T | null>(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<Error | null>(null);

  useEffect(() => {
    fetch(url)
      .then(res => res.json())
      .then(setData)
      .catch(setError)
      .finally(() => setLoading(false));
  }, [url]);

  return { data, loading, error };
}
```

## Padrões Avançados

### Compound Components

```tsx
// Tab.tsx
const TabsContext = createContext<{
  activeTab: string;
  setActiveTab: (id: string) => void;
} | null>(null);

function Tabs({ children, defaultTab }: Props) {
  const [activeTab, setActiveTab] = useState(defaultTab);
  return (
    <TabsContext.Provider value={{ activeTab, setActiveTab }}>
      {children}
    </TabsContext.Provider>
  );
}

Tabs.List = function TabList({ children }: Props) {
  return <div className="tab-list">{children}</div>;
};

Tabs.Tab = function Tab({ id, children }: Props) {
  const { activeTab, setActiveTab } = useContext(TabsContext)!;
  return (
    <button
      className={activeTab === id ? 'active' : ''}
      onClick={() => setActiveTab(id)}
    >
      {children}
    </button>
  );
};

Tabs.Panel = function TabPanel({ id, children }: Props) {
  const { activeTab } = useContext(TabsContext)!;
  return activeTab === id ? <div>{children}</div> : null;
};

// Uso
<Tabs defaultTab="home">
  <Tabs.List>
    <Tabs.Tab id="home">Home</Tabs.Tab>
    <Tabs.Tab id="profile">Profile</Tabs.Tab>
  </Tabs.List>
  <Tabs.Panel id="home">Home content</Tabs.Panel>
  <Tabs.Panel id="profile">Profile content</Tabs.Panel>
</Tabs>
```

### Render Props (legacy, preferir hooks)

```tsx
// Evitar - usar custom hook
<DataFetcher url="/api/users" render={data => <UserList users={data} />} />

// Preferir
const { data } = useFetch('/api/users');
return <UserList users={data} />;
```

## Composition Patterns (Vercel Engineering)

Padrões de composição para componentes React escaláveis. Fonte: Vercel composition-patterns.

### Regra #1: Evitar Boolean Props (CRITICAL)

```tsx
// ❌ ERRADO: Booleans duplicam estados possíveis
<Composer isThread isEditing={false} showAttachments showFormatting={false} />

// ✅ CORRECTO: Variantes explícitas
<ThreadComposer channelId="abc" />
<EditMessageComposer messageId="xyz" />
<ForwardMessageComposer messageId="123" />
```

Cada boolean duplica os estados possíveis. 5 booleans = 32 combinações, maioria impossível.

### Regra #2: Compound Components com Context (HIGH)

```tsx
// ✅ Compound Components: context partilhado, composição explícita
const ComposerContext = createContext<ComposerContextValue | null>(null)

function ComposerFrame({ children }: { children: React.ReactNode }) {
  return <form>{children}</form>
}

function ComposerInput() {
  const { state, actions: { update }, meta } = use(ComposerContext)
  return (
    <TextInput
      ref={meta.inputRef}
      value={state.input}
      onChangeText={(text) => update(s => ({ ...s, input: text }))}
    />
  )
}

// Exportar como compound
const Composer = {
  Frame: ComposerFrame,
  Input: ComposerInput,
  Submit: ComposerSubmit,
  Footer: ComposerFooter,
}

// Uso: composição clara do que cada variante renderiza
<Composer.Frame>
  <Composer.Input />
  <Composer.Footer>
    <Composer.Submit />
  </Composer.Footer>
</Composer.Frame>
```

### Regra #3: State em Providers (HIGH)

```tsx
// ❌ ERRADO: Estado preso dentro do componente
function ForwardComposer() {
  const [state, setState] = useState(initialState)
  return <Composer.Frame>...</Composer.Frame>
}
// Como ForwardButton acede ao state? useEffect sync? Refs? Prop drilling?

// ✅ CORRECTO: State lifted para Provider
function ForwardProvider({ children }: { children: React.ReactNode }) {
  const [state, setState] = useState(initialState)
  const submit = useForwardMessage()
  const inputRef = useRef(null)
  return (
    <Composer.Provider
      state={state}
      actions={{ update: setState, submit }}
      meta={{ inputRef }}
    >
      {children}
    </Composer.Provider>
  )
}

// Agora QUALQUER componente dentro do Provider acede ao state
function ForwardDialog() {
  return (
    <ForwardProvider>
      <Dialog>
        <ForwardComposer />
        <MessagePreview />  {/* acede state via context */}
        <ForwardButton />   {/* acede submit via context */}
      </Dialog>
    </ForwardProvider>
  )
}

// Botão FORA do Composer.Frame mas DENTRO do Provider
function ForwardButton() {
  const { actions } = use(ComposerContext)
  return <Button onPress={actions.submit}>Forward</Button>
}
```

**Princípio chave:** O boundary do Provider é o que importa, não o nesting visual.

### Regra #4: Interface Genérica para Dependency Injection (HIGH)

```tsx
// ✅ Definir interface genérica: state + actions + meta
interface ComposerContextValue {
  state: { input: string; attachments: Attachment[]; isSubmitting: boolean }
  actions: { update: (fn: (s: State) => State) => void; submit: () => void }
  meta: { inputRef: React.RefObject<TextInput> }
}

// ✅ Múltiplos providers implementam a MESMA interface
function ChannelProvider({ channelId, children }) {
  const { state, update, submit } = useGlobalChannel(channelId)
  return <Composer.Provider state={state} actions={{ update, submit }}>{children}</Composer.Provider>
}

function ForwardProvider({ children }) {
  const [state, setState] = useState(initialState)
  return <Composer.Provider state={state} actions={{ update: setState, submit: forward }}>{children}</Composer.Provider>
}

// O mesmo Composer.Input funciona com AMBOS os providers!
```

**Princípio:** UI = pedaços reutilizáveis compostos. State = injectado pelo provider. Trocar provider, manter UI.

### Regra #5: Children > Render Props (MEDIUM)

```tsx
// ❌ Render props (inflexível, difícil de ler)
<Composer
  renderHeader={() => <Header />}
  renderFooter={() => <><Formatting /><Emojis /></>}
/>

// ✅ Children (composição natural)
<Composer.Frame>
  <Header />
  <Composer.Input />
  <Composer.Footer>
    <Formatting />
    <Emojis />
  </Composer.Footer>
</Composer.Frame>

// Excepção: render props quando parent passa dados
<List data={items} renderItem={({ item }) => <Item item={item} />} />
```

### Regra #6: React 19 APIs (MEDIUM)

```tsx
// ✅ React 19: ref como prop normal (sem forwardRef)
function Input({ ref, ...props }: Props & { ref?: React.Ref<HTMLInputElement> }) {
  return <input ref={ref} {...props} />
}

// ✅ React 19: use() em vez de useContext()
const value = use(MyContext) // pode ser chamado condicionalmente!
```

### Checklist Composição

- [ ] Zero boolean props para variantes (usar componentes explícitos)
- [ ] Compound components com context partilhado
- [ ] State em Provider (não dentro do componente UI)
- [ ] Interface genérica (state/actions/meta)
- [ ] Children para composição, render props só para data passthrough
- [ ] React 19: `use()` e ref como prop

---

## Datasets Dify (Consulta Obrigatória)

Em caso de dúvidas ou para aprofundar conhecimento, consultar os seguintes datasets via MCP:

| Dataset | ID | Prioridade |
|---------|----|-----------:|
| **TI (Tecnologia da Informação)** | `7f63ec0c-6321-488c-b107-980140199850` | 1 |
| **Desenvolvimento de Software** | `e7c7decc-0ded-4351-ab14-b110b3c38ec9` | 1 |
| **Desenvolvimento de WebSites** | `c8489151-de94-42b2-8cee-c0b961cfac6d` | 2 |
| **UX e Usabilidade** | `e14ab89e-8910-43b6-becf-d57c78afd62d` | 3 |

### Como Consultar

```javascript
// Pesquisar padrões React
mcp__notebooklm__notebook_query, mcp__dify-kb__dify_kb_retrieve_segments({
  dataset_id: "e7c7decc-0ded-4351-ab14-b110b3c38ec9",
  query: "react hooks state management"
})

// Server Components Next.js
mcp__dify-kb__dify_kb_retrieve_segments({
  dataset_id: "7f63ec0c-6321-488c-b107-980140199850",
  query: "nextjs server components app router"
})

// UX e performance
mcp__dify-kb__dify_kb_retrieve_segments({
  dataset_id: "e14ab89e-8910-43b6-becf-d57c78afd62d",
  query: "performance loading states"
})
```

### Quando Consultar

- Implementar hooks customizados
- Escolher state management
- Optimizar performance (memoization, lazy loading)
- Server Components vs Client Components
- Padrões de UX em React

---
**Versão**: 1.0.0 | **Autor**: Descomplicar®

---


## Quando NÃO Usar

- Para tarefas fora do domínio de especialização desta skill
- Quando outra skill mais específica está disponível
- Para operações que requerem aprovação manual obrigatória
- Quando os requisitos não estão claramente definidos


## Protocolo de Execução

1. **Análise Inicial**
   - Verificar requisitos e contexto
   - Identificar ferramentas necessárias

2. **Preparação**
   - Validar acesso a recursos
   - Preparar ambiente de trabalho

3. **Execução**
   - Executar operações de forma incremental
   - Validar cada passo antes de prosseguir

4. **Validação**
   - Verificar resultados obtidos
   - Confirmar sucesso da operação

5. **Conclusão**
   - Documentar alterações realizadas
   - Reportar status final e próximos passos


## Exemplos de Uso

### Exemplo 1: Caso Básico
```
User: [requisição simples relacionada com react-patterns]
Skill: [execução directa com validação]
Output: [resultado conciso e accionável]
```

### Exemplo 2: Caso Complexo
```
User: [requisição multi-passo ou complexa]
Skill:
  1. Análise dos requisitos
  2. Planeamento da abordagem
  3. Execução faseada
  4. Validação contínua
Output: [resultado detalhado com próximos passos]
```

### Exemplo 3: Caso com Dependências
```
User: [requisição que depende de outros sistemas]
Skill:
  1. Verificar dependências disponíveis
  2. Coordenar com skills/MCPs necessários
  3. Executar workflow integrado
Output: [resultado completo com referências]
```