TanStack DB Core: coleções e consultas reativas com revisão humana

ANÁLISE EDITORIAL

Uma lista de tarefas chega de uma API, outra tela precisa filtrá-la e uma edição deve aparecer imediatamente, sem fingir que o servidor já confirmou a gravação. A Skill oficial db-core, mantida no repositório TanStack/db, organiza esse problema em três partes: coleções que recebem dados, consultas reativas sobre elas e mutações otimistas com persistência definida pela aplicação. Ela é documentação para um agente de programação, não um banco instalado, um serviço de sincronização ou prova de que uma implementação funciona.

O que a Skill faz

O núcleo publicado pela TanStack funciona como índice de decisão. Ele encaminha o agente para documentos específicos ao criar uma coleção, escrever uma consulta com filtros ou junções, tratar inserções e edições otimistas, construir um adaptador, persistir dados ou trabalhar com um framework. O ganho prático é reduzir a chance de aplicar uma receita de React em uma aplicação Vue, ou de tratar uma atualização local como confirmação do backend.

A visão geral oficial descreve TanStack DB como uma camada reativa do lado do cliente. Dados podem vir de TanStack Query, de uma API, de armazenamento local ou de um motor de sincronização. Uma coleção normaliza esses registros; consultas vivas derivam a visão que a interface precisa; mutações permitem mostrar o estado pretendido antes de terminar a persistência. A Skill ajuda o agente a escolher e combinar essas peças. Ela não escolhe por você a política de conflitos, a autorização da API ou a durabilidade que o produto exige.

O arquivo principal aponta para doze sub-Skills. Por isso, o ZIP preserva os 13 arquivos SKILL.md oficiais e nove referências Markdown internas, incluindo orientações de React, Vue, Svelte, Solid e Angular, além das seções de offline e meta-framework. Isso mantém os caminhos documentados disponíveis, mas não é uma recomendação de instalar todos esses pacotes. Leia apenas o núcleo e a referência pertinente ao caso real.

Para quem serve e quando não usar

A curadoria serve a desenvolvedores que já têm uma aplicação JavaScript ou TypeScript e querem avaliar TanStack DB com um agente, ou que precisam revisar uma integração existente. Um caso adequado é pedir ao agente que identifique onde uma lista é carregada, como uma coleção é criada, qual consulta alimenta a tela e quem confirma uma alteração no servidor. O resultado útil é um mapa de arquivos e um pequeno plano de mudança verificável, não uma resposta promocional sobre velocidade.

Não use a Skill como ordem para substituir o banco de dados do servidor. TanStack DB não elimina controles de acesso, transações de negócio ou validação de entrada na API. Também não presuma que uma coleção local ofereça sincronização offline: persistência em IndexedDB, persistência SQLite e fila de transações offline são caminhos diferentes, com pré-requisitos distintos. Se uma aplicação simples já resolve o estado da tela de modo claro, uma camada adicional pode aumentar o trabalho de manutenção. A decisão depende de consultas, frequência de atualização, fonte de dados e necessidade de sincronização.

Compatibilidade e pré-requisitos

A instalação oficial lista pacotes para React, Solid, Svelte, Vue, Angular e JavaScript sem framework. Ela informa React 18 ou superior e Vue 3.3 ou superior para os respectivos adaptadores. O frontmatter da Skill principal neste commit declara alvo @tanstack/db v0.6.17. Isso descreve a referência copiada, não garante compatibilidade com a versão instalada no seu projeto. Confira package.json, lockfile e documentação correspondente antes de aceitar um diff.

Para ler o ZIP, basta um cliente de agente que aceite instruções locais em SKILL.md e preserve a árvore de diretórios. Para testar a biblioteca, o projeto precisa das dependências apropriadas ao framework e à fonte de dados escolhida. A opção com TanStack Query, por exemplo, usa um pacote de coleção próprio; armazenamento local e persistência SQLite seguem instruções diferentes. O pacote do Bastidores não contém essas dependências e não faz instalação automática.

Instalação e configuração

Primeiro, baixe o ZIP documental hospedado no Bastidores e compare seu SHA-256 com o valor abaixo. Abra ORIGEM.md, confira o commit, os hashes individuais e a licença. Extraia mantendo packages/db/skills/db-core/SKILL.md e os subdiretórios. Aponte o cliente de agente para esse arquivo principal, conforme a configuração do próprio cliente. Se ele copiar apenas um arquivo para uma pasta plana, os caminhos indicados pelo núcleo deixam de corresponder à árvore original; nesse caso, ajuste a instalação local e teste os caminhos antes de trabalhar.

Depois, em uma branch de teste, escolha a integração da biblioteca a partir da página oficial de instalação. Para uma aplicação React que já usa TanStack Query, a introdução oficial mostra os pacotes e uma coleção de tarefas. Não copie comandos de um framework para outro. Peça ao agente que indique quais pacotes já existem, quais seriam novos e quem seria responsável pelos manipuladores de inserção, atualização e exclusão na API. Só aprove a instalação após revisar esse plano e as permissões do ambiente.

A configuração da coleção precisa deixar explícitos o identificador, uma chave estável para cada registro, a função de carregamento e o comportamento de escrita. Se os dados forem sensíveis, verifique o que fica na memória, no navegador ou em armazenamento persistente. A existência da Skill não autoriza o agente a acessar credenciais, produção ou dados pessoais reais.

Primeiro uso e resultado esperado

Comece com um pedido somente de leitura: “Leia db-core e collection-setup. Neste repositório, encontre a tela de tarefas, a chamada à API e o estado que ela mantém. Diga se TanStack DB ajudaria a separar carregamento e consulta. Mostre arquivos, versões e um plano mínimo; não edite nada.” Uma resposta boa aponta o código existente e admite o que ainda não sabe. Se o agente não encontrar o projeto, ele deve pedir o caminho correto, não inventar componentes.

Após revisão humana, experimente uma coleção pequena em dados de teste. Faça uma consulta viva que filtre um campo conhecido e observe se a tela muda quando o registro muda. A documentação de consultas vivas explica filtros, projeções e junções, além da diferença entre dados já carregados e uma consulta que realmente inicia sincronização. Para escrita, teste separadamente sucesso, erro e atraso do backend. A documentação de mutações deixa claro que a confirmação depende do comportamento do manipulador; uma mudança otimista na tela, sozinha, não demonstra gravação remota.

O resultado esperado do primeiro ciclo é um diff pequeno, typecheck e testes pertinentes executados no projeto, com as respostas de rede inspecionadas. Não executamos um aplicativo, um benchmark ou uma sincronização real para esta publicação. Auditamos a documentação, o pacote e as referências de origem. Desempenho e correção precisam ser medidos na aplicação do leitor.

Permissões, privacidade e riscos

O ZIP contém Markdown e licença, sem scripts ou binários. O risco vem das ferramentas que um agente pode usar ao seguir as instruções: terminal, instalação de pacotes, leitura de arquivos e edição do código. Dê primeiro acesso somente de leitura e restrito ao projeto. Autorize escrita, rede e instalação em etapas separadas, depois de avaliar o plano. Não compartilhe .env, tokens, bases de clientes ou respostas reais de API no prompt.

Uma coleção do lado do cliente não é barreira de segurança. O servidor deve validar identidade, autorização e campos permitidos em cada operação. Uma atualização otimista pode ser revertida ou reconciliada depois de um erro; a interface deve comunicar esse estado sem prometer sucesso cedo demais. Armazenamento persistente exige análise de retenção, dados pessoais e limpeza. A opção offline, quando necessária, deve ter testes de reconexão, duplicação de comandos e conflitos antes de chegar a produção.

Erros comuns e limites

Se o agente não localizar collection-setup, confira a árvore extraída e o caminho da Skill principal. Se sugerir uma API de outro framework, compare imports e dependências com o package.json antes de editar. Se a consulta voltar vazia, determine se a coleção fonte já foi carregada e se há assinatura ou pré-carregamento; uma consulta local não busca, por si só, qualquer dado remoto que ainda não chegou.

Se uma edição aparece e desaparece, inspecione o manipulador de persistência, a resposta do servidor e a política de reconciliação. Não esconda o erro apenas para manter a interface aparentemente rápida. Se registros se duplicam ou uma atualização atinge a linha errada, verifique a função de chave e a identidade das coleções. Se a API do exemplo não corresponder à instalação, confira a versão fixada no lockfile e a documentação dessa versão; atualizar dependências é uma decisão separada. Problemas com offline, SSR ou adaptadores personalizados merecem a sub-Skill específica, não improviso a partir do índice.

Versão, licença e download local

A cópia foi fixada no commit 013275035116e015d27b56bc58ce21531e82bc5a do repositório TanStack/db. Em 16 de outubro de 2026, a API pública do GitHub registrou 3.945 estrelas; é um dado da consulta, não um teste de qualidade. O arquivo principal declara @tanstack/db v0.6.17. A licença MIT oficial permite redistribuição com o aviso preservado.

O download local contém 13 arquivos SKILL.md oficiais, nove referências Markdown, LICENSE e ORIGEM.md. Não contém a biblioteca, scripts, executáveis, dependências ou credenciais. SHA-256 do ZIP: e7136be285960b120b0ca4f26d74b5d78b6538af19ce9581f803edbc3094bade. Compare o arquivo recebido com esse hash; o manifesto lista os hashes de cada documento copiado.

Fontes primárias

Foram consultados o SKILL.md principal, a referência de coleções, a documentação de instalação, os guias de consultas e a licença. O card separa o download hospedado do botão que abre o repositório oficial.