Última modificação: 11 de setembro de 2025
A versão mais recente (2025.2) da plataforma para desenvolvedores apresenta um novo framework de compilação e implantação baseado em arquivo. Este framework contém a configuração de um aplicativo, ativos e outros códigos-fonte. Se você tiver um aplicativo público existente que criou antes de se inscrever na nova versão beta da plataforma para desenvolvedores, este guia irá orientá-lo sobre como migrar para a versão mais recente do framework de projetos. Antes de prosseguir com a migração, leia as duas seções a seguir sobre os recursos compatíveis e limitações.

​
Recursos e extensões de aplicativo compatíveis

Quaisquer recursos compatíveis com os projetos serão incluídos na migração, incluindo:
  • Configuração do aplicativo
  • Webhooks
  • Ações de fluxo de trabalho personalizados

​
Antes de começar

Se o projeto existente tiver um cartão com objetos personalizados conectados, confirme se você tem o escopo crm.objects.custom.read em seu aplicativo antes da migração. Para projetos compilados antes da versão mais recente de 2025.2, os cartões de objeto personalizado podiam ser compilados apenas com o escopo crm.schemas.custom.read necessário. Na última versão (2025.2) da plataforma de desenvolvedor, crm.objects.custom.read é necessário para que seu cartão acesse os dados de objeto personalizado.

​
Limitações

Os seguintes recursos ainda não são suportados durante o período da versão beta privada atual:
  • O suporte para a Integração com o GitHub, que dispara carregamentos e compilações automáticos do GitHub, ainda não está disponível. Se seu projeto estiver vinculado ao GitHub, desabilite a integração antes de iniciar a migração. Para desabilitar a integração do GitHub e configurar as Ações do GitHub para automatizar CI/CD, confira as instruções neste artigo.
  • Se você criou uma página de configurações para seu aplicativo, você precisará refatorar suas configurações usando o novo recurso de extensões de interface. É recomendado que você anote todos os elementos da interface na versão de produção atual do seu aplicativo antes de migrar para a versão mais recente. Após a conclusão do processo de migração, você poderá usar os novos recursos de extensão de interface para recriar a página de configurações.
  • A funcionalidade de cartão do CRM clássico não é compatível com aplicativos que usam a versão mais recente dos projetos do desenvolvedor. Você precisará refatorar qualquer esquema de cartão de aplicativo existente.
  • A arquitetura de permissão subjacente do seu aplicativo será atualizada para oferecer suporte a permissões específicas de usuário mais granulares. Como parte dessa transição, novas instalações de clientes agora terão um usuário de conta de serviço associado criado em sua conta, que está vinculada ao seu aplicativo.
    • Agora, cada conta receberá apenas um token de atualização, independentemente de quantos usuários individuais reautorizarem o aplicativo.
    • Pontos de extremidade OAuth existentes que recuperam os metadados do token de atualização e acesso ainda retornarão o usuário que os instalou como userId e retornarão agora um serviceAccountId após a migração do aplicativo.

​
Migrar seu aplicativo

Depois de revisar as considerações na seção acima, você pode continuar a migrar seu aplicativo. Esse processo preservará as credenciais de autenticação originais, os recursos do aplicativo e as instalações do aplicativo. Nenhuma alteração é necessária na infraestrutura do seu aplicativo.
  • Verifique se você instalou a versão beta mais recente da CLI do HubSpot executando o comando npm i -g @hubspot/cli@next e se o conectou à sua conta usando os comandos hs auth e hs accounts use.
A CLI precisa ter a versão 7.5.4 ou posterior. Você pode verificar qual versão da CLI você tem executando hs --version.
  • Para iniciar o processo de migração, use um dos seguintes comandos com base no aplicativo existente que você está migrando:
  • Se você estiver migrando um aplicativo antigo que não faça parte de um projeto, execute o seguinte comando:
hs app migrate
Se você estiver migrando um aplicativo baseado em projeto, execute o comando hs project migrate.
  • Você será solicitado a escolher o aplicativo que deseja migrar. Isso criará um novo projeto em seu sistema de arquivos local contendo um aplicativo, juntamente com seus recursos que representam seu estado configurado atual.
  • Depois de selecionar o aplicativo, você será solicitado a confirmar os componentes que serão migrados. Certifique-se de compreender totalmente o processo de migração antes de confirmar a próxima etapa.
  • Em seguida, você será solicitado a fornecer um nome de projeto, um caminho local para o novo projeto e quaisquer UIDs necessários.
Os UIDs devem ser usados como um identificador exclusivo para todos os recursos do seu aplicativo. Uma vez que um UID é definido para um recurso específico, alterá-lo ou modificá-lo em compilações subsequentes forçará a plataforma a reconhecê-lo como “novo” ou diferente de compilações anteriores, o que pode não ser o pretendido.
Instruções para migrar um aplicativo existente
  • Depois de confirmar os detalhes do projeto, o processo de migração executará automaticamente as seguintes ações em uma única operação:
    • Criar um projeto para seu aplicativo na página Projetos da conta, que inclui um componente aplicativo e qualquer recurso compatível.
    • Converter qualquer recurso existente do aplicativo em arquivos de código-fonte, que você poderá atualizar para revisar a configuração no futuro.
    • Compilar e implantar o novo projeto (rotulado como Compilação #1), o que completa a associação entre o aplicativo e seu projeto. Isso preservará as credenciais de autenticação originais, os recursos do aplicativo e as instalações.
    • Descarregar os novos arquivos de código-fonte do projeto para o diretório local especificado anteriormente quando solicitado no terminal.
    • Se um projeto existente tiver sido migrado, mova os arquivos do diretório src/ original para archive/ e preencha /src/ com o novo código-fonte do projeto.
Página de detalhes do aplicativo migrado na exibição de projetos
A Compilação #1 do novo projeto captura o estado de configuração do aplicativo para todos os recursos compatíveis como uma referência à qual você pode retornar. Se necessário, você pode reverter com segurança qualquer alteração futura nesse projeto (por exemplo, adicionando cartões de aplicativo baseados em React) reimplantando a Compilação #1.
Após a migração, os recursos definidos no código-fonte do projeto não poderão mais ser editados por meio da interface de gerenciamento de aplicativos no HubSpot, nem usando APIs de desenvolvedor anteriores. Outros recursos (por exemplo, ações de fluxo de trabalho personalizadas ou eventos de linha do tempo) continuarão a ser mantidos usando suas respectivas APIs.
  • Com a migração concluída (conforme refletido pelo "platformVersion": "2025.2" no seu hsproject.json), agora você pode começar a desenvolver recursos novos ou existentes, usando a CLI da HubSpot e os arquivos de código-fonte do seu projeto.