ADR-0009: Gerenciamento de Estado — TanStack Query + Zustand
Status
Accepted
Context and Problem Statement
Os frontends Next.js precisam gerenciar dois tipos de estado: dados remotos (server state) e estado de UI local (client state), com o mínimo de boilerplate e máxima previsibilidade.
Decision Drivers
- Server state precisa de cache, invalidação e refetch automático
- Client state deve ser leve — App Router com Server Components reduz necessidade
- Integração com REST (TanStack Query é agnóstico de fetch)
Considered Options
- TanStack Query + Zustand
- TanStack Query + Jotai
- SWR + Context API
- Redux Toolkit Query
Decision Outcome
Chosen option: TanStack Query (server state) + Zustand (client state), porque TanStack Query é o padrão de mercado para REST com cache declarativo, e Zustand oferece store global simples para UI state (modais, sidebar, filtros) sem boilerplate de reducers.
Positive Consequences
- TanStack Query: cache automático, invalidação por query key, loading/error states
- Zustand: store global sem Provider wrapping, API simples
- Separação clara: dados remotos vs estado de UI
- Server Components do Next.js reduzem Zustand ao mínimo necessário
Negative Consequences
- Dois sistemas de estado para aprender
- Cuidado com duplicação: não armazenar server state no Zustand
More Information
- Projetos:
atenvi-admin,atenvi-web - Query keys seguem estrutura da URL REST:
['users', userId] - Zustand stores por domínio de UI:
useLayoutStore,useFilterStore