Se você trabalha com o HubSpot CMS, os módulos personalizados são a habilidade mais importante que você pode aprender. Eles dão aos editores de conteúdo controle total sobre o conteúdo da página, mantendo o código limpo, rápido e fácil de manter.
Mas aqui está o problema — a maioria dos desenvolvedores HubSpot constrói módulos da maneira errada. Eles escrevem CSS inchado, ignoram o agrupamento de campos, inserem tags de cabeçalho diretamente no código (hardcode) e ignoram completamente a performance. O resultado? Páginas lentas, editores frustrados e um código bagunçado que ninguém quer manter.
Este guia cobre tudo o que você precisa para construir módulos personalizados prontos para produção no HubSpot — do jeito certo. Com exemplos de código reais, estrutura de campos adequada, melhores práticas de HubL e dicas de performance que realmente importam.
Um módulo personalizado é um bloco de conteúdo reutilizável composto por quatro arquivos dentro do Gerenciador de Design (Design Manager):
Pense nisso como construir um bloco de Lego. Você o projeta uma vez com todos os pontos de conexão corretos e, em seguida, os editores de conteúdo podem usá-lo em qualquer lugar — em qualquer página, em qualquer seção — sem nunca tocar no código.
Antes de construir qualquer coisa, configure seu módulo adequadamente. Aqui está um meta.json limpo para um módulo de Seção Hero:
Duas coisas a notar aqui. Primeiro, host_template_types controla onde este módulo pode ser usado. Defina como PAGE para módulos exclusivos de páginas, ou inclua BLOG_POST se ele também deve funcionar em templates de blog. Nunca deixe aberto para templates de e-mail se o seu módulo usa CSS ou JS — e-mails não têm suporte para eles. Segundo, adicione sempre um help_text (texto de ajuda) significativo. Isso aparece no Gerenciador de Design e ajuda sua equipe a entender o que o módulo faz sem precisar ler o código.
O arquivo fields.json é onde a maioria dos desenvolvedores erra. Uma lista plana com mais de 15 campos torna a experiência de edição dolorosa. Agrupar campos relacionados cria uma interface limpa e intuitiva.
Antes de qualquer campo de conteúdo, todo módulo deve ter um grupo de Configurações da Seção. Isso dá aos editores de conteúdo controle sobre o ID da seção, classes personalizadas e visibilidade:
Por que isso é importante? Os editores de conteúdo frequentemente precisam ocultar uma seção temporariamente, adicionar um link âncora para navegação ou aplicar uma classe personalizada para uma estilização especial. Sem esses campos, eles precisam pedir a um desenvolvedor para cada pequena mudança. Com eles, eles são autossuficientes.
Nunca insira a tag de cabeçalho diretamente no código (hardcode). Sempre forneça um campo de escolha para que os editores possam controlar a hierarquia de SEO:
Note que a tag de título padrão está definida como h2, e não h1. Isso é intencional. A maioria das páginas deve ter apenas um H1, e isso geralmente é tratado pelo primeiro módulo. Todo módulo subsequente deve ter o padrão H2. Se o editor colocar este módulo como a primeira seção de uma página, ele mesmo pode mudar para H1.
Um erro comum é usar o módulo CTA do HubSpot para cada botão. CTAs são poderosos, mas adicionam sobrecarga de rastreamento e deixam o carregamento da página mais lento quando usados em excesso. Para a maioria dos botões, um simples campo de link com um campo de texto é tudo o que você precisa:
O tipo de campo de link oferece automaticamente aos editores opções para URL, nova aba e nofollow — tudo sem nenhum trabalho extra de sua parte.
Como você nomeia os campos importa mais do que você imagina. Os editores de conteúdo veem esses rótulos toda vez que editam uma página. Seja específico:
Adicione também help_text (texto de ajuda) a cada campo. Uma descrição de 10 palavras agora economiza uma conversa de 10 minutos no Slack mais tarde.
Agora vamos construir o module.html em si. É aqui que todos os campos se juntam em um componente renderizado.
Vamos analisar os padrões críticos usados neste código.
Cada tag HubL no código acima usa a sintaxe de traço: em vez de . Essa única mudança faz uma diferença enorme no seu HTML renderizado.
Sem os traços, o HubL insere linhas em branco onde quer que ele processe uma tag. O código-fonte da sua página acaba cheio de espaços em branco desnecessários — linhas vazias entre cada elemento. Isso torna o HTML mais pesado, mais difícil de depurar e um pouco mais lento para ser analisado.
Com traços, o HubL remove esse espaço em branco de forma limpa. O HTML renderizado é enxuto, mínimo e exatamente o que o navegador precisa. Em uma página com mais de 20 módulos, isso pode reduzir o tamanho do seu arquivo HTML de forma perceptível.
O mesmo se aplica à saída de variáveis: use em vez de para evitar espaços em branco ao redor de valores dinâmicos.
O título usa o valor do campo diretamente como a tag HTML:
Se o editor selecionar "H2" na lista suspensa, isso será renderizado como uma tag <h2> adequada. Se ele selecionar "H1", será renderizado como <h1>. O editor tem controle total do SEO sem precisar de um desenvolvedor.
Cada seção de conteúdo é envolvida em uma verificação if. Se o campo de título estiver vazio, nenhuma tag <h2> será renderizada. Se o texto do botão estiver vazio, nenhum botão aparecerá. Se a imagem não tiver origem (source), a coluna da imagem desaparecerá completamente.
Isso impede que elementos HTML vazios apareçam na página — sem layouts quebrados, sem divs vazias ocupando espaço, sem problemas de acessibilidade devido a tags de título vazias.
Ao usar o tipo de campo de imagem do HubSpot, sempre exiba os valores do campo diretamente — src, alt, width e height. O campo de imagem do HubSpot já é otimizado para SEO. Ele fornece atributos de imagem responsivos e um tratamento adequado do texto alternativo (alt) nativamente.
Não substitua esses valores por atributos inseridos diretamente no código (hardcoded). Apenas adicione loading="lazy" para imagens abaixo da dobra (below-the-fold) para melhorar a performance da página.
Se todo módulo precisa de configurações de seção (ID, classe, visibilidade), você não deveria copiar esse código em todo module.html. Em vez disso, crie um arquivo de macro uma vez e importe-o em todos os lugares.
Escreva uma vez. Importe em 50 módulos. Quando você precisar mudar como os IDs das seções funcionam, atualize um arquivo e todo módulo receberá a atualização. É assim que os temas profissionais do HubSpot são construídos.
Esta pode ser a seção mais importante de todo este guia. A maioria dos desenvolvedores HubSpot escreve CSS dentro do arquivo module.css de cada módulo. Isso cria uma bagunça — estilos duplicados entre módulos, espaçamento inconsistente, tamanhos de arquivos crescentes e páginas que carregam mais devagar a cada novo módulo.
Olhe para o module.html acima. Não há nenhum CSS personalizado. Cada estilo é aplicado através das classes utilitárias do Tailwind diretamente no HTML:
Benefícios dessa abordagem:
A única vez que se deve escrever no module.css é para coisas que o Tailwind genuinamente não consegue lidar — tipicamente animações personalizadas ou padrões complexos de pseudo-elementos:
Todo o resto deve estar no CSS global do seu tema ou ser tratado pelos utilitários do Tailwind. Ponto final.
A mesma regra se aplica ao module.js. A maioria dos módulos não precisa de JavaScript.
Módulos que não precisam de JS: seções hero, blocos de texto e imagem, grades de recursos, cartões de depoimentos, tabelas de preços, seções de rodapé. Estes são puramente visuais — o HTML e o CSS cuidam de tudo.
Módulos que precisam de JS: acordeões, carrosséis/sliders, componentes de abas, pop-ups modais, validação de formulários, animações acionadas por rolagem (scroll).
Quando você escrever JavaScript, mantenha-o 'vanilla' (puro). Nada de jQuery em 2026. O HubSpot carrega o module.js apenas uma vez por tipo de módulo, mesmo que o módulo apareça várias vezes em uma página — mas isso ainda adiciona peso à sua página. Seja intencional sobre cada script que você incluir.
O Google considera os sinais de acessibilidade nos rankings de pesquisa. Construir módulos acessíveis não é apenas uma boa prática — impacta diretamente o seu SEO.
Se você está usando o Tailwind CSS, já tem uma vantagem. A paleta de cores padrão do Tailwind foi projetada com proporções de contraste adequadas. Atenha-se a essas combinações seguras:
Evite texto claro em fundos claros. Uma taxa de contraste abaixo de 4.5:1 falha no WCAG AA e pode prejudicar seus rankings de pesquisa.
Antes de publicar qualquer módulo, revise esta checklist:
Escrever CSS em cada módulo. Isso cria estilos duplicados e carregamentos de página mais pesados. Use as classes utilitárias do Tailwind ou escreva o CSS global na folha de estilos do seu tema. O CSS do módulo deve ser seu último recurso.
Adicionar JavaScript desnecessariamente. Módulos de conteúdo estático como seções hero, grades de recursos e depoimentos não precisam de JavaScript. Cada script adiciona peso à página.
Inserir tags de título diretamente no código (hardcoding). Se você escrever <h2> diretamente no seu HTML, os editores de conteúdo não poderão controlar a hierarquia de SEO. Sempre use um campo de escolha e renderize a tag dinamicamente.
Ignorar o espaço em branco do HubL. Usar em vez deenche seu HTML renderizado de linhas em branco. A sintaxe com traço remove os espaços em branco e produz um resultado mais limpo e leve.
Listas de campos planas sem grupos. Vinte campos não agrupados no editor de páginas é um pesadelo para os editores de conteúdo. Agrupe campos relacionados — Conteúdo, Imagem, Botão, Configurações da Seção — para que a interface fique limpa e navegável.
Ignorar as configurações da seção. Sem um campo de ID, os editores não podem criar links âncora. Sem um botão de alternância de visibilidade, eles não podem ocultar uma seção temporariamente. Sem um campo de classe personalizada, eles precisam de um desenvolvedor para cada ajuste de estilo. Adicione esses três campos a cada módulo como prática padrão.
Substituir o snippet de imagem do HubSpot. O tipo de campo de imagem do HubSpot já gera um HTML otimizado para SEO com os atributos src, alt, width, height e responsividade adequados. Não substitua isso por código personalizado — basta exibir os valores dos campos diretamente e adicionar loading="lazy" quando apropriado.
Usar CTAs para todos os botões. Os CTAs do HubSpot têm uma sobrecarga de rastreamento. Para botões simples que vinculam a uma página, use uma tag de âncora com um campo de texto e um campo de link em vez disso. Reserve os CTAs para botões que genuinamente precisam de rastreamento e análise.
Construir módulos personalizados no HubSpot não se trata apenas de fazer com que as coisas pareçam certas — trata-se de construir componentes que sejam rápidos, acessíveis, otimizados para SEO e fáceis de usar para os editores de conteúdo.
As técnicas cobertas neste guia — campos agrupados, tags de título dinâmicas, controle de espaços em branco do HubL, classes utilitárias do Tailwind, macros reutilizáveis e o tratamento adequado de imagens — são o que separa o desenvolvimento profissional no HubSpot de um trabalho amador.
Comece a aplicar essas práticas no seu próximo módulo. Seus editores de conteúdo agradecerão, suas páginas carregarão mais rápido e suas pontuações de SEO irão melhorar.
Construir módulos HubSpot do zero leva tempo. O Rapid permite que você faça upload de qualquer captura de tela de interface (UI) e gera um módulo HubSpot completo e pronto para produção — com fields.json, vinculações HubL e a estrutura correta — em menos de 60 segundos. Experimente grátis →