For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /pt/docs/web/updating-the-kit.md (or send Accept: text/markdown).
Atualize a sua cópia quando o kit melhorar
Traga as melhorias do repositório de origem para a sua cópia — registre o seu ponto de partida, baixe a nova revisão, faça o merge numa branch e verifique antes de implantar.
1. Registre de onde você partiu
Trate uma atualização como um pequeno projeto, não como um copiar-e-colar: você compara a revisão do kit que tem com a mais nova, carrega as alterações e testa numa branch antes de implantar. Isso funciona tanto se o seu projeto é um fork de um repositório do kit — uma cópia que o GitHub mantém ligada à origem — quanto se é código que você copiou para dentro do seu próprio app.
Antes de qualquer coisa, escreva uma nota no seu projeto com três coisas: o commit do kit de onde você partiu — o SHA, o código curto do Git que identifica uma versão exata — o repositório que você recebeu (supastack-web, supastack-mobile, supastack-desktop ou o monorepo All Platforms) e as alterações que você já fez por conta própria.
Os repositórios do kit e o monorepo têm históricos diferentes, então nunca faça merge de uma branch de um num fork do outro. Se você nunca registrou um SHA de partida, encontre a versão compartilhada mais próxima com git merge-base num fork, ou identifique os últimos arquivos e testes que copiou numa adoção seletiva — e revise um diff mais amplo quando a base exata for incerta.
2. Baixe e faça merge da nova revisão
Execute os comandos abaixo num terminal dentro da pasta do seu projeto, com o trabalho salvo e commitado — uma working tree limpa, para que nada pela metade se misture ao merge. Palavras dentro de colchetes angulares são modelos de substituição: troque a <coisa> inteira pelos seus próprios valores. O endereço do GitHub mostrado é um placeholder; use o endereço do repositório do qual você fez fork.
O que as linhas fazem: git remote add ensina à sua cópia um segundo endereço chamado kit-upstream — o repositório do kit — e git fetch baixa o estado mais novo sem tocar nos seus arquivos. git switch -c cria uma branch de upgrade separada, para que a sua branch principal fique intacta enquanto você revisa. git log lista os commits que você está prestes a trazer e git diff --stat resume quais arquivos mudaram; leia o diff completo dos módulos que você usa, não só os títulos dos commits. git merge traz o código novo para a branch de upgrade.
Se o Git disser que o remote kit-upstream já existe, pule a linha remote add e siga com git fetch. <previous-kit-sha> é o SHA de partida que você registrou no passo 1.
# Upstream is the platform repository you forked — substitute its real URL
# (supastack-web shown; use supastack-mobile or supastack-desktop as fits).
git remote add kit-upstream https://github.com/<org>/supastack-web.git
git fetch kit-upstream
git switch -c upgrade/kit-update
git log --oneline <previous-kit-sha>..kit-upstream/main
git diff --stat <previous-kit-sha>..kit-upstream/main
git merge kit-upstream/main3. Resolva conflitos sem perder o seu trabalho
Um conflito significa que os dois lados alteraram as mesmas linhas: o kit avançou e você personalizou o mesmo lugar. O Git pausa o merge e marca o arquivo — está pedindo que você escolha, não relatando um dano.
Abra cada arquivo marcado no seu editor e decida linha por linha: mantenha os textos, nomes e configurações próprios do seu produto e aceite as correções e mudanças estruturais do kit. Nunca resolva um conflito substituindo um arquivo que você personalizou pela versão nova inteira do kit — isso apaga o seu trabalho. Resolva dentro da branch de upgrade e rode os testes de cada área resolvida antes de continuar.
Se o merge der errado, git merge --abort devolve a branch ao estado anterior ao merge. Nada neste fluxo muda a sua branch principal ou a sua implantação até você mesmo fazer o merge da branch de upgrade.
4. Atualize os dados e implante na ordem certa
Revisões novas do kit podem mudar o banco de dados. Leia os novos arquivos em packages/db/drizzle/ — a pasta de migrações — e faça backup dos dados de produção antes de aplicar migrações; teste-as primeiro numa cópia descartável. Implante as mudanças de esquema compatíveis antes do código que precisa delas: se uma migração remove ou remodela dados, reverter só o código do app não restaura o esquema antigo.
Compare o novo .env.example com as suas configurações e adicione os valores recém-obrigatórios no painel da sua hospedagem. Arquivos .env carregam segredos e nunca são commitados no Git — você os recria à mão em cada máquina e implantação, e eles ficam fora dos valores NEXT_PUBLIC_ e EXPO_PUBLIC_.
Antes de implantar, rode os portões de verificação do próprio kit. No monorepo All Platforms, corepack pnpm check:local executa lint, typecheck, os testes unitários e uma verificação de formato sem nenhuma credencial paga; corepack pnpm verify:local adiciona o build de produção e as suites de teste de navegador. Num fork de uma única superfície, rode os comandos de teste e build do próprio repositório. Depois faça uma passada de smoke em staging: entre, experimente um segundo espaço de trabalho e percorra a jornada principal do seu produto.
Quando tudo passar, anote o SHA de destino aceito e os conflitos que você resolveu — essa nota é a base de partida para a próxima atualização.
corepack pnpm check:local
# fuller gate: adds the production build and browser suites
corepack pnpm verify:local5. Se você copiou partes em vez de fazer fork
Uma adoção seletiva — copiar módulos do kit para um app existente — não compartilha histórico de Git com o kit, então git merge não ajuda. Em vez disso, compare o SHA antigo da origem com o SHA de destino e porte apenas as alterações que tocam a parte que você adotou.
Revise os tipos públicos do módulo, o esquema de persistência e as migrações, o chamador no servidor, a configuração, os testes e a documentação como uma unidade — uma mudança dentro de um pacote pode exigir uma rota correspondente ou uma mudança de ambiente em outro lugar, e copiar um único helper pode deixar o resto num contrato desatualizado. Mantenha uma nota curta de adaptação — quais arquivos do kit você pegou, quais pulou, o que mudou — para que a próxima atualização possa refazer as suas escolhas.
Se uma atualização quebrar algo na sua cópia em execução, percorra o guia de resolução de problemas antes de desfazer as suas próprias alterações.