Skip to main content
O desenvolvimento local de apps gira em torno da sincronização: a CLI reconstrói seu manifesto e o servidor aplica apenas a diferença entre ele e os metadados que já estão no seu workspace. Esta página cobre qual comando usar, como ler o que uma sincronização mudou e o que fazer — em ordem — quando o estado local parece inconsistente.

​
Qual comando usar e quando

Para a iteração local do dia a dia, quase sempre você vai querer yarn twenty dev. Fazer deploy e publicar servem para entregar releases, não para o ciclo local.
yarn twenty dev --once e yarn twenty dev --once --dry-run ainda funcionam como aliases obsoletos para yarn twenty apply e yarn twenty plan.

​
A sincronização local não precisa de incremento de versão

A regra de version estritamente crescente (VERSION_ALREADY_EXISTS no deploy, APP_ALREADY_INSTALLED / CANNOT_DOWNGRADE_APPLICATION na instalação) se aplica a app:publish / app:install — o caminho de release. yarn twenty dev sincroniza seu manifesto no lugar e nunca exige mudança de versão, então você não precisa mexer em package.json para iterar. Se você se pegar aumentando a versão para testar uma mudança local, está usando o caminho de release quando o que quer é o ciclo de desenvolvimento.

​
Lendo a saída da sincronização

Cada sincronização imprime as alterações de metadados que aplicou (ou aplicaria, com plan), no estilo do Terraform — um bloco por entidade com seus atributos, depois uma linha de resumo:
Este é seu primeiro diagnóstico: ele mostra exatamente quais objetos, campos e layouts mudaram, para que você possa confirmar que uma sincronização fez o que esperava antes de conferir na interface. Mudanças destrutivas (to destroy) são listadas com o que elas removem (por exemplo, objectMetadata "auditNote" — drops the table and all its rows) e exigem confirmação interativa, ou --force em scripts. Quando uma sincronização falha em uma única entidade, o erro nomeia a entidade com problema e seu universalIdentifier, por exemplo:
Use esse identificador para encontrar a entidade no seu manifesto (e, se necessário, no workspace), em vez de adivinhar qual está em conflito.

​
Visualizando mudanças (plan)

yarn twenty plan compila seu manifesto, pede ao servidor o plano de migração e o imprime — sem aplicar nada. É a forma segura de responder “o que esta sincronização mudaria?” antes de se comprometer com ela.
Um plano:
  • Não grava nada — nenhuma migração de metadados, nenhuma atualização de registro de aplicativo, nenhuma mudança de função/aba padrão e nenhuma geração de cliente de API.
  • Retorna o mesmo diff que uma sincronização real aplicaria, para que você possa revisar previamente as entidades criadas/atualizadas/excluídas.
  • É útil antes de uma mudança arriscada, ao revisar uma mudança gerada por IA ou em um script que deve falhar se uma mudança inesperada estiver prestes a ser aplicada.
Um plano só antevê mudanças de metadados, e exige que o app tenha sido sincronizado ao menos uma vez (para que o workspace o conheça). Se você rodar isso em um app que nunca foi sincronizado, o servidor informa que o app não está instalado — rode yarn twenty dev uma vez antes.

​
Escada de recuperação

Quando os metadados locais parecerem errados, aumente o nível nesta ordem e pare assim que estiver desbloqueado. Cada etapa é mais disruptiva que a anterior.
  1. Ressincronizar. Rode yarn twenty apply novamente. Sincronizações são idempotentes — rodar novamente um manifesto limpo é seguro e frequentemente resolve um problema transitório.
  2. Prever o plano. Rode yarn twenty plan para ver exatamente o que a próxima sincronização pretende mudar, sem aplicá-la.
  3. Leia o erro nomeado. Se uma sincronização falhar, anote o tipo de metadado e o universalIdentifier na mensagem (veja acima) e localize essa entidade no seu manifesto. Um conflito geralmente aponta para um identificador duplicado ou reutilizado.
  4. Desinstalar e reinstalar. yarn twenty app:uninstall, depois sincronize novamente (yarn twenty dev). Isso reconstrói os metadados do app a partir do zero, mantendo o restante do seu workspace intacto.
  5. Reset completo (último recurso). yarn twenty docker:reset, depois faça o seeding e a sincronização novamente.
yarn twenty docker:reset exclui todos os dados da sua instância local — todos os workspaces, registros e apps. Use isso somente depois que as etapas anteriores tiverem falhado.
Encontrou um erro de metadados? Por favor, abra uma issue e inclua a mensagem de migração que falhou (com seu tipo de metadado e universalIdentifier), a saída de Metadata changes da sincronização e os comandos que você rodou.

​
Evite sincronizações concorrentes em um único workspace

Sincronizar aplica migrações de metadados. Executar várias operações de sincronização, deploy ou instalação contra o mesmo workspace ao mesmo tempo — por exemplo, múltiplos terminais ou agentes de IA iterando em paralelo — pode intercalar essas migrações e deixar os metadados em um estado parcialmente aplicado. O servidor serializa sincronizações por workspace para evitar isso, mas você ainda deve direcionar operações sensíveis de metadados por um único processo em vez de dispará-las concorrentemente. Se você orquestra o desenvolvimento com múltiplos agentes, encaminhe as chamadas de sincronização/deploy/instalação deles por uma única fila, para que apenas uma rode por vez.

​
Diferenciando tipos de falha

Quando algo dá errado, o diff de metadados e os erros nomeados permitem localizar a falha:
  • Erro de build do manifesto — a CLI falha antes de sincronizar (MANIFEST_BUILD_FAILED, TYPECHECK_FAILED); corrija o código-fonte do seu app.
  • Erro de sincronização / migração — o build é bem-sucedido, mas aplicar o diff falha, nomeando a entidade e o universalIdentifier; corrija os metadados em conflito.
  • Erro de tempo de execução no código do app — a sincronização é concluída com êxito, mas suas funções de lógica ou componentes se comportam de forma incorreta em tempo de execução; verifique os logs de função.
  • Estado da instância local — nenhuma das opções acima e o espaço de trabalho ainda parece incorreto; prossiga descendo na escada de recuperação.