Se você desenvolve com Lightning Web Components há algum tempo, já passou pela frustração de encadear propriedades de pai para filho, de filho para neto, e de neto para bisneto. Cada camada adiciona código repetitivo, eventos customizados e uma sensação crescente de que existe um jeito melhor de fazer as coisas. A boa notícia é que esse jeito melhor finalmente chegou de forma oficial.
O módulo @lwc/state, agora disponível de forma geral a partir do Summer ’26, traz ao LWC um padrão de gerenciamento de estado reativo que elimina o prop drilling, os eventos customizados e as gambiarras de pub/sub. É uma solução pensada desde o início para a arquitetura de componentes do Salesforce, com uma coleção de state managers prontos no namespace lightning que já conhecem seus dados de Salesforce por dentro.
O que é um State Manager no LWC?
Um state manager é um módulo JavaScript dedicado que encapsula um conjunto de dados relacionados — o “estado” — e as funções que operam sobre esses dados. Você cria um usando a função defineState do módulo @lwc/state, passando uma função de configuração. Essa função recebe como primeiro argumento um objeto com três blocos fundamentais: atom, computed e setAtom.
O atom é um valor atômico reativo, basicamente um wrapper em torno de um pedaço de dados que o LWC utiliza para tornar componentes e outros state managers reativos a mudanças. O computed é uma derivação avaliada de forma preguiçosa que recalcula apenas quando seus átomos dependentes mudam. E o setAtom é usado sempre que você precisa modificar o estado de forma controlada.
Veja como fica na prática um contador simples:
import { defineState } from '@lwc/state';
export const createCounter = defineState(({ atom, computed, setAtom }, initialCount = 0) => {
const count = atom(initialCount);
const doubled = computed([count], (countValue) => countValue * 2);
const increment = () => setAtom(count, count.value + 1);
return { count, doubled, increment };
});A mágica acontece nos bastidores. Qualquer componente que referencie count ou doubled em um contexto reativo é automaticamente re-renderizado quando increment roda. Os valores computados são recalculados de forma preguiçosa e apenas quando suas entradas mudam. Além disso, múltiplas chamadas ao setAtom no mesmo ciclo são agrupadas em uma única notificação, o que garante reatividade sem o custo de re-renderizações desnecessárias.
Compartilhando estado entre componentes com fromContext
O verdadeiro poder dos state managers vai além de um componente isolado. Você pode criar uma instância no topo de uma árvore de componentes e consumi-la em qualquer componente descendente usando fromContext, sem passar propriedades, sem manipular eventos e sem configurações de pub/sub.
No componente pai, você instancia o state manager normalmente:
import createShopStateManager from 'x/shopState';
export default class App extends LightningElement {
shopState = createShopStateManager();
}Em qualquer componente descendente, basta acessar a mesma instância via contexto:
import { LightningElement } from 'lwc';
import { fromContext } from '@lwc/state';
import createShopStateManager from 'x/shopState';
export default class Cart extends LightningElement {
shopState = fromContext(createShopStateManager);
get cartTotal() {
return `$${this.shopState.value.cartTotal.toFixed(2)}`;
}
}Perceba como o componente Cart não recebeu nenhuma propriedade do pai. Ele simplesmente declara que precisa do state manager da loja e o LWC cuida de conectá-lo à instância correta que já existe na árvore. Se outro componente como ProductList ou CheckoutButton também precisar do mesmo estado, basta repetir o mesmo padrão. Todos leem e escrevem nos mesmos dados reativos.
State managers prontos para dados do Salesforce
A Salesforce não entregou apenas a ferramenta para criar seus próprios state managers. Ela também disponibilizou uma coleção de state managers prontos no namespace lightning, construídos sobre os mesmos alicerces do Lightning Data Service e da UI API que você já conhece.
Cada state manager integrado apresenta uma forma uniforme com status (que pode ser "unconfigured", "loading", "loaded" ou "error"), data, error e funções setter para configuração. Essa consistência faz com que usar e compor diferentes state managers seja algo natural e previsível.
Os state managers disponíveis expõem dados de records, objectInfo, layout e related lists. Como state managers podem ser aninhados e conectados com computed, é possível construir cascadas de dados completamente reativas. Por exemplo: buscar um record para descobrir seu record type, depois buscar o layout correspondente, e então buscar o record completo usando os campos do layout. Tudo isso reagindo automaticamente a mudanças.
Veja um componente que consome o lightning/stateManagerRecord:
import { LightningElement, api } from 'lwc';
import { getFieldValue } from 'lightning/uiRecordApi';
import createRecordStateManager from 'lightning/stateManagerRecord';
import ACCOUNT_NAME_FIELD from '@salesforce/schema/Account.Name';
import ACCOUNT_INDUSTRY_FIELD from '@salesforce/schema/Account.Industry';
export default class AccountCard extends LightningElement {
_recordId;
state = createRecordStateManager({
fields: [ACCOUNT_NAME_FIELD, ACCOUNT_INDUSTRY_FIELD]
});
@api
set recordId(id) {
this._recordId = id;
this.state.value.setRecordId(id);
}
get recordId() {
return this._recordId;
}
get displayLabel() {
const { status, data } = this.state.value;
if (status !== 'loaded') return 'Carregando...';
const name = getFieldValue(data, ACCOUNT_NAME_FIELD) ?? 'Desconhecido';
const industry = getFieldValue(data, ACCOUNT_INDUSTRY_FIELD) ?? '';
return industry ? `${name} — ${industry}` : name;
}
}Note como o componente não usa @wire em nenhum momento. O state manager cuida de toda a comunicação com o Lightning Data Service, e o componente apenas lê os valores de forma reativa.
Caso prático: gerenciando carrinho de compras offline com Consumer Goods Cloud
Para mostrar como os state managers resolvem problemas reais, vamos pensar em um cenário comum no Consumer Goods Cloud. Imagine um representante de campo usando o aplicativo mobile offline para capturar pedidos em pontos de venda. Ele precisa adicionar produtos ao carrinho, ajustar quantidades e ver o total atualizado em tempo real, mesmo sem conexão com a internet.
Com o @lwc/state, você pode criar um state manager dedicado para o carrinho que funciona perfeitamente offline, usando o SmartStore do Mobile SDK para persistência local:
import { defineState } from '@lwc/state';
export const createCartState = defineState(({ atom, computed, setAtom }, storeName) => {
const items = atom([]);
const isLoading = atom(false);
const totalItems = computed([items], (itemList) =>
itemList.reduce((sum, item) => sum + item.quantity, 0)
);
const totalPrice = computed([items], (itemList) =>
itemList.reduce((sum, item) => sum + (item.price * item.quantity), 0)
);
const addItem = (product) => {
const currentItems = items.value;
const existing = currentItems.find(i => i.productId === product.productId);
if (existing) {
setAtom(items, currentItems.map(i =>
i.productId === product.productId
? { ...i, quantity: i.quantity + 1 }
: i
));
} else {
setAtom(items, [...currentItems, { ...product, quantity: 1 }]);
}
};
const updateQuantity = (productId, quantity) => {
if (quantity <= 0) {
setAtom(items, items.value.filter(i => i.productId !== productId));
} else {
setAtom(items, items.value.map(i =>
i.productId === productId ? { ...i, quantity } : i
));
}
};
const clearCart = () => setAtom(items, []);
return { items, isLoading, totalItems, totalPrice, addItem, updateQuantity, clearCart };
});No componente de exibição do carrinho, o consumo é limpo e direto:
import { LightningElement } from 'lwc';
import { fromContext } from '@lwc/state';
import { createCartState } from 'x/cartState';
export default class CartSummary extends LightningElement {
cart = fromContext(createCartState);
get displayTotal() {
return `R$ ${this.cart.value.totalPrice.toFixed(2)}`;
}
get itemCount() {
return this.cart.value.totalItems;
}
get hasItems() {
return this.cart.value.items.length > 0;
}
handleClear() {
this.cart.value.clearCart();
}
}Esse padrão funciona perfeitamente no aplicativo mobile offline do Consumer Goods Cloud. O state manager mantém o carrinho em memória de forma reativa, e quando a conectividade retorna, o MobileSync cuida de enviar os dados para o Salesforce. Os componentes não precisam saber se estão online ou offline — eles apenas leem e escrevem no estado, e a interface se atualiza sozinha.
Vantagens sobre as abordagens anteriores
Antes do @lwc/state, os desenvolvedores LWC tinham basicamente três opções para compartilhar estado entre componentes, e nenhuma delas era particularmente elegante.
A primeira era o prop drilling, passando dados de componente em componente através de atributos. Funciona para hierarquias simples, mas se torna um pesadelo quando você tem cinco ou seis níveis de profundidade. Cada componente intermediário precisa declarar @api setters que não usa para nada além de repassar o dado para o filho.
A segunda opção eram os eventos customizados, que resolvem o problema de comunicação ascendente mas adicionam boilerplate significativo. Para cada dado compartilhado, você precisa despachar o evento no filho, capturá-lo no pai, processar a lógica e atualizar o estado. Quando vários componentes precisam reagir ao mesmo dado, a complexidade cresce rápido.
A terceira eram as soluções de pub/sub com bibliotecas externas ou LightningMessagingService. Funcionam, mas adicionam uma camada de abstração extra que dificulta o debug e cria dependências implícitas difíceis de rastrear.
O @lwc/state resolve todos esses problemas de uma vez. O estado vive em um módulo JavaScript puro, sem dependência do DOM. Os componentes consomem o que precisam via contexto. E a reatividade é gerenciada pelo próprio framework, sem código manual de sincronização.
Testabilidade e reutilização
Um benefício que não pode ser ignorado é a testabilidade. Como state managers são módulos JavaScript puros sem dependência do DOM, você pode testá-los com Jest sem precisar montar componente nenhum. Crie uma instância do state manager, chame suas funções e verifique os valores. É rápido, limpo e determinístico.
A reutilização também melhora significativamente. O mesmo módulo de state manager pode ser consumido por componentes em árvores completamente diferentes. Um state manager de configurações de tema, por exemplo, pode alimentar tanto o sidebar quanto o header quanto o footer, sem nenhum acoplamento entre eles.
E como os consomentes leem valores da forma pública do state manager em vez de acessar seus detalhes internos, você pode refatorar como o estado é armazenado sem precisar atualizar cada componente que o utiliza.
Limitações atuais e próximos passos
É importante mencionar que, no momento, os state managers estão disponíveis no Lightning Experience mas ainda não são suportados no Experience Cloud. Se seu projeto depende de portais Experience Cloud, precisará continuar usando as abordagens tradicionais por enquanto.
Para começar a experimentar, a Salesforce disponibilizou dois exemplos completos no repositório forcedotcom/state-management no GitHub. O primeiro, chamado simple-store, é uma aplicação de carrinho de compras que demonstra como múltiplos componentes leem e modificam o mesmo state manager inteiramente via contexto. Ele inclusive foi demonstrado ao vivo no TDX em março de 2026 e pode ser executado diretamente no navegador pelo StackBlitz. O segundo, platform-state-managers, é um projeto Salesforce DX que constrói um painel de detalhes de record orientado por layout usando os state managers de record e layout integrados.
A documentação oficial está disponível na página de gerenciamento de estado do LWC, com referência completa de todos os state managers do namespace lightning.
Conclusão
O @lwc/state representa uma mudança de paradigma real no desenvolvimento com Lightning Web Components. Chega de prop drilling, de eventos customizados encadeados e de soluções de pub/sub que adicionam complexidade sem necessidade. Com defineState, atom, computed e fromContext, você tem um sistema de gerenciamento de estado reativo, testável e elegante que funciona da escala de um componente isolado até uma aplicação completa.
Se você ainda não experimentou, agora é o momento. Clone o repositório de exemplos, rode o simple-store no StackBlitz e veja como seus componentes ficam mais limpos e fáceis de manter. O futuro do state management no LWC já é presente, e ele funciona.