Já tentou copiar manualmente um tema do HubSpot de uma conta para outra? Frustrante, não é?

A HubSpot oferece várias maneiras de configurar temas – você pode usar um tema do Marketplace, criar um tema filho pelo Design Manager ou importar um tema existente. Mas quando precisamos transferir temas entre contas diferentes, o processo manual pode ser complexo e demorado.

É aqui que o HubSpot CLI se torna nossa ferramenta salvadora. Com alguns comandos simples, podemos importar tema HubSpot entre contas de forma rápida e eficiente. O melhor? Você não precisa ser um especialista técnico para fazer isso funcionar.

Neste guia, vamos mostrar como usar o HubSpot CLI upload para transferir temas entre contas, desde a configuração inicial até a resolução de problemas comuns. Vamos começar?

Preparando o ambiente para o HubSpot CLI

Para começar nossa jornada de importação de temas, precisamos primeiro preparar nosso ambiente de desenvolvimento. Vamos configurar tudo passo a passo para garantir um processo tranquilo.

Requisitos do sistema

Para trabalhar com o HubSpot CLI, precisamos ter alguns elementos básicos instalados em nossa máquina. O componente principal é o Node.js, que deve ser versão 18 ou superior. Recomendo usar um gerenciador de pacotes como Homebrew ou nvm para facilitar a instalação.

Além disso, é útil ter um editor de código como Visual Studio Code instalado, que tornará nossa experiência mais fácil ao trabalhar com os comandos e arquivos do tema.

Instalando o CLI

Com o Node.js instalado, podemos instalar o HubSpot CLI usando o seguinte comando no terminal:

npm install -g @hubspot/cli@latest

Este comando instala a versão mais recente do CLI globalmente em nosso sistema. Após a instalação, teremos acesso ao comando hs que usaremos para todas as operações relacionadas ao HubSpot.

Configurando as credenciais

A configuração das credenciais é um processo crucial. Vamos seguir estes passos:

1. Execute o comando hs init no terminal
2. Quando solicitado, pressione Enter para abrir a página de chave de acesso pessoal
3. Selecione sua conta HubSpot no navegador
4. Para desenvolvimento de projetos privados, selecione as permissões:
   • Developer projects
   • Sandboxes
   • Serverless functions

É importante mencionar que sua chave de acesso pessoal deve incluir algumas permissões mínimas para evitar erros durante o desenvolvimento local. As permissões essenciais incluem developer.projects.write, developer.app_functions.read, e developer.app_functions.write.

Após configurar as credenciais, o CLI criará um arquivo hubspot.config.yml em seu diretório. Este arquivo é fundamental, pois armazena suas configurações de autenticação e permite que você alterne entre diferentes contas HubSpot quando necessário.

Se você encontrar problemas durante a configuração, como erros de autenticação ou permissões insuficientes, não se preocupe – são situações comuns que podem ser facilmente resolvidas ajustando as permissões na sua chave de acesso pessoal.

Comandos essenciais do HubSpot CLI

Agora que temos nosso ambiente configurado, vamos explorar os comandos essenciais do CLI que nos ajudarão a transferir temas entre contas HubSpot. O CLI nos oferece uma interface poderosa para gerenciar nossos arquivos e temas de forma eficiente.

Navegando entre diretórios

Para começar, precisamos nos familiarizar com a navegação básica. O comando hs ls nos permite visualizar arquivos no sistema de arquivos do desenvolvedor, similar ao comando tradicional ls do terminal. Por exemplo:

hs ls /themes

Este comando lista todos os temas disponíveis em nossa conta HubSpot. Para acessar um diretório específico, usamos o comando cd normalmente.

Autenticação entre contas

O gerenciamento de múltiplas contas é simplificado com o CLI. Podemos adicionar várias contas ao nosso arquivo de configuração usando:

hs auth

Para listar todas as contas configuradas, utilizamos:

hs accounts

Este comando mostra o nome, ID e tipo de autenticação de cada conta em nosso arquivo de configuração.

Comandos básicos de tema

Para trabalhar com temas, temos três comandos fundamentais:

1. Baixar um tema

hs fetch <caminho-do-tema> <destino-local>

2. Fazer upload de um tema:

hs upload <pasta-local> <destino-hubspot>

3. Monitorar alterações:

hs watch <pasta-local> <destino-hubspot>

O comando watch é particularmente útil durante o desenvolvimento, pois carrega automaticamente as alterações para nossa conta HubSpot quando salvamos os arquivos.

Dica importante: Ao trabalhar com nomes de temas que contêm espaços, devemos usar aspas ou substituir os espaços por %20 no comando. Por exemplo:

hs upload "Meu Tema" /themes/meu-tema

ou

hs upload Meu%20Tema /themes/meu-tema

Lembre-se que todas as alterações feitas através destes comandos serão aplicadas imediatamente em sua conta HubSpot. Por isso, é sempre recomendado fazer um backup antes de realizar operações importantes.

Processo de exportação do tema

Vamos explorar o processo de exportação do tema, uma etapa crucial para transferir seus designs entre contas HubSpot. Com o CLI configurado, podemos começar o processo de forma sistemática.

Localizando o tema fonte

No Design Manager do HubSpot, encontramos nossos temas na pasta @hubspot. Esta pasta contém todos os temas e módulos padrão disponíveis em nossa conta. Para localizar um tema específico:

hs ls @hubspot/themes

Este comando nos mostra todos os temas disponíveis em nossa conta. Se o tema estiver em outra pasta, podemos navegar até ele usando o comando cd.

Baixando para ambiente local

Com o tema localizado, vamos baixá-lo para nossa máquina. Usamos o comando:

hs fetch @hubspot/[nome-do-tema] ./meu-tema-local

Dica importante: Se o nome do tema contiver espaços, precisamos usar aspas ou substituir os espaços por %20. Por exemplo:

Baixando para ambiente local

Com o tema localizado, vamos baixá-lo para nossa máquina. Usamos o comando:

hs fetch @hubspot/[nome-do-tema] ./meu-tema-local

Dica importante: Se o nome do tema contiver espaços, precisamos usar aspas ou substituir os espaços por %20. Por exemplo:

hs fetch "@hubspot/Meu Tema" ./meu-tema-local

Verificando a estrutura do tema

Após o download, é fundamental verificar se todos os componentes do tema foram baixados corretamente. Um tema HubSpot completo deve conter:

• theme.json – Arquivo de configuração principal
• fields.json – Controla os campos disponíveis no editor
• Pasta templates – Contém os modelos de página
• Pasta modules – Módulos personalizados do tema
• Pasta css – Arquivos de estilo
• Pasta js – Scripts JavaScript

É importante notar que temas comprados do Template Marketplace têm algumas restrições específicas. Por exemplo, eles não podem ser clonados diretamente. Nestes casos, recomendamos criar um tema filho antes de fazer a exportação.

Se encontrarmos o erro “The path is not a path to a file or folder”, geralmente significa que há um problema com o caminho especificado no comando. Verifique se:

1. O nome do tema está escrito corretamente
2. Não há espaços extras no comando
3. O caminho de destino existe em sua máquina

Para verificar se todos os arquivos foram baixados corretamente, podemos usar o comando:

hs watch ./meu-tema-local

Este comando não só verifica a estrutura, mas também nos permite ver alterações em tempo real.

Importando o tema para nova conta

Com nosso tema já baixado localmente, chegou o momento de fazer o upload para a nova conta. Este processo requer atenção aos detalhes, mas é mais simples do que parece.

Comando de upload

Para fazer o upload do tema, utilizamos o comando hs upload. A sintaxe básica é:

hs upload <pasta-local> <destino-hubspot>

Por exemplo, para fazer upload do tema que baixamos anteriormente:

hs upload ./meu-tema-local /temas/novo-tema

Qualquer alteração enviada através deste comando será aplicada imediatamente em sua conta HubSpot.

Alguns problemas comuns que podem ocorrer durante a importação:

• Erros de caminho quando há espaços no nome do tema
• Dependências externas faltando
• Arquivos CSS/JS não vinculados corretamente
• Imagens não transferidas (elas mantêm URLs da conta original)

Configurando como tema padrão

Para ativar o tema recém-importado:

1. Acesse Marketing > Website > Website Pages
2. Clique em Create e selecione Website page
3. No seletor de temas, clique no menu dropdown e escolha Change theme
4. Localize seu tema importado
5. Passe o mouse sobre ele e clique em Set as active theme

Importante: Ao definir um tema como padrão, todas as configurações de estilo serão aplicadas às páginas que utilizam este tema.

Se você estiver trabalhando com múltiplas contas, pode alternar entre elas usando o parâmetro --account no comando de upload:

hs upload ./meu-tema-local /temas/novo-tema --account=principal

Este recurso é particularmente útil quando precisamos alternar entre uma conta sandbox e a conta principal.

Lembre-se que temas na pasta @hubspot ou @marketplace não podem ser copiados diretamente entre contas. Nestes casos, primeiro faça o download para sua máquina local e depois faça o upload para a nova conta.

Conclusão

Espero que seguindo os passos apresentados neste guia – desde a configuração do ambiente até o upload final do tema – você economize um pouco de tempo e evite alguma dor de cabeça com o processo.

É importante lembrar que caso você encontrar dificuldades durante o processo, a comunidade HubSpot está sempre disponível para ajudar através da base de conhecimento.