Neste artigo
Adicionar JavaScript no tema WordPress é registrar o script pela API de enfileiramento do core, não colar a tag no cabeçalho. A forma certa usa a função wp_enqueue_script no arquivo functions.php de um child theme, o que preserva o código quando o tema recebe uma atualização. Esse caminho resolve três problemas de uma vez: evita a perda do código na atualização, declara a dependência do jQuery de forma explícita e controla se o arquivo carrega no rodapé com defer. Para quem está montando o site, vale revisar antes como escolher o tema WordPress certo, porque a base define o resto. Este guia faz parte do hub de conteúdos de temas WordPress da FULL.
Diagnóstico rápido: Por que adicionar JavaScript no tema WordPress quebra
A maioria dos sites que chegam ao suporte com “o script sumiu depois da atualização” tem a mesma origem: o código foi colado direto no header.php do tema pai. Quando o tema recebe uma versão nova, o WordPress sobrescreve esse arquivo e o JavaScript desaparece sem nenhum aviso para o administrador.
A tabela abaixo cruza o sintoma com a causa raiz e a ação certa, para você identificar o seu caso em segundos antes de tocar em qualquer arquivo do tema.
| Sintoma | Causa raiz | Ação corretiva |
|---|---|---|
| Script some após atualizar o tema | Código colado no header.php do tema pai | Mover para wp_enqueue_script no child theme |
| Erro “jQuery is not defined” no console | Dependência jQuery não declarada | Passar array(‘jquery’) no 3º parâmetro |
| Página trava enquanto o script carrega | Arquivo no header sem defer | Usar strategy defer e carregar no rodapé |
Os três casos têm a mesma origem: ignorar a API de enfileiramento que o core oferece desde o WordPress 2.6.
A maneira certa de adicionar JavaScript no tema WordPress
A maneira certa de adicionar JavaScript no tema WordPress passa por uma única função do core: wp_enqueue_script. Segundo a documentação oficial, a assinatura é wp_enqueue_script( $handle, $src, $deps, $ver, $in_footer ), e a chamada deve ficar dentro de uma função enganchada no gancho wp_enqueue_scripts do core.
Esse caminho entrega quatro garantias que colar a tag no template nunca dá: um identificador único por script, o controle de dependência, o número de versão para cache busting e a escolha do local de carregamento. O core ainda evita carregar a mesma biblioteca duas vezes quando dois recursos pedem o jQuery, o que elimina conflito de versão. Ferramentas como Astra, GeneratePress e Kadence já seguem esse padrão internamente, e o seu código precisa conversar com ele em vez de brigar com a fila de scripts que o WordPress monta a cada requisição.
Onde o código vive: Functions.php, child theme ou plugin de snippet
Existem três lugares legítimos para adicionar JavaScript no tema WordPress, e a escolha muda conforme o seu risco e o seu nível técnico. O functions.php do child theme é o destino recomendado para quem mexe em código, porque sobrevive às atualizações do tema pai e mantém tudo versionado em um único arquivo.
Um plugin de snippet, como o Code Snippets, executa o mesmo PHP sem editar arquivo e isola o erro, então um ponto e vírgula esquecido não derruba o site inteiro. Já editar o functions.php do tema pai pela tela do painel é o pior caminho: um erro de sintaxe gera a tela branca da morte e a alteração some na próxima atualização do tema. Para os hooks envolvidos, o functions.php é só o arquivo onde o gancho mora; quem dispara o enqueue é sempre o wp_enqueue_scripts.
Passo a passo: Adicionar JavaScript no tema WordPress com wp_enqueue_script
Configurar o enqueue corretamente leva cinco passos e cerca de 15 minutos em um ambiente de testes. A sequência abaixo assume um child theme já ativo e um arquivo .js salvo na pasta do tema. Cada passo é independente: você pode parar no terceiro se o script não usa jQuery e não precisa de defer. Faça a primeira execução sempre em homologação, nunca direto na produção.
Passo 1: Crie a função e enganche no wp_enqueue_scripts
Abra o functions.php do child theme e crie uma função com prefixo do seu tema, por exemplo meutema_scripts(). Dentro dela vai a chamada de enfileiramento. Logo abaixo, conecte essa função ao evento certo com add_action( 'wp_enqueue_scripts', 'meutema_scripts' ). Esse é o gancho que o WordPress dispara no momento de montar o frontend, garantindo que o script entre na fila antes do <head> fechar.
Passo 2: Registre o arquivo com wp_enqueue_script e get_stylesheet_directory_uri
Dentro da função, chame wp_enqueue_script( 'meutema-main', get_stylesheet_directory_uri() . '/js/main.js', array(), '1.0.0', true ). O get_stylesheet_directory_uri() aponta para a pasta do child theme, não do tema pai, o que evita caminho quebrado. O quarto argumento, ‘1.0.0’, é a versão usada para cache busting: ao trocar esse número você força o navegador a baixar a versão nova em vez da cacheada.
Passo 3: Declare a dependência do jQuery no terceiro parâmetro
Se o seu script usa o cifrão do jQuery, o terceiro parâmetro precisa receber array('jquery') no lugar do array vazio. Sem isso, o navegador tenta rodar o $ antes da biblioteca existir e dispara o erro “jQuery is not defined” no console, deixando a função morta no frontend. Declarar a dependência faz o core carregar o jQuery primeiro e o seu arquivo depois, na ordem garantida.
Passo 4: Carregue no rodapé e aplique a estratégia defer
Para não travar a renderização, mande o script para o rodapé. O quinto parâmetro controla isso, e a partir do WordPress 6.3 ele aceita um array como array( 'strategy' => 'defer', 'in_footer' => true ). O defer baixa o arquivo em paralelo e só o executa após o HTML estar pronto, o que protege as Core Web Vitals do site. Use async apenas para scripts independentes, como tags de analytics.
Passo 5: Passe dados do PHP para o JavaScript com wp_localize_script
Quando o script precisa de uma URL ou de um valor do servidor, use wp_localize_script( 'meutema-main', 'meutemaDados', array( 'ajaxurl' => admin_url('admin-ajax.php') ) ) logo após o enqueue. Isso cria um objeto JavaScript global com os dados, sem que você precise escrever a URL na mão no arquivo .js. É o caminho oficial para integrar PHP e JavaScript no tema sem hardcode.
Erros comuns ao adicionar JavaScript no tema WordPress
Três erros respondem pela maioria dos chamados que vemos no suporte sobre scripts no tema WordPress. O primeiro é colar a tag de script direto no header.php, que funciona até a atualização sobrescrever o arquivo e apagar tudo de uma vez, sem deixar rastro.
O segundo erro é esquecer a dependência do jQuery e travar a função no frontend, com o console apontando o cifrão indefinido. O terceiro é registrar o mesmo handle duas vezes, uma no plugin e outra no tema, gerando conflito de versão e comportamento imprevisível na página. Um quarto, mais sutil, aparece quando a minificação agressiva embaralha a ordem de carregamento e o defer já não basta sozinho. A regra que evita os quatro ao adicionar JavaScript no tema WordPress é simples: um handle único por script, dependência sempre declarada e nenhuma linha de código solta fora do enqueue.
Cache, versão e otimização do JavaScript no tema
Depois de adicionar JavaScript no tema WordPress pelo enqueue, a próxima camada é o desempenho, e ela depende de três alavancas diretas. A versão no quarto parâmetro do wp_enqueue_script resolve o cache do navegador: cada deploy com número novo invalida o arquivo antigo sem você limpar nada na mão.
A minificação remove espaços e comentários e costuma cortar de 20% a 40% do peso do arquivo final. E o defer de JavaScript tira o script do caminho crítico de renderização, o que move o LCP para baixo em páginas pesadas. Ferramentas como WP Rocket, Perfmatters e Autoptimize automatizam minificação e defer, mas elas só funcionam bem quando o script já foi enfileirado pela API do core. Código colado no header escapa de quase toda otimização automática e ainda fura o cache do plugin.
Acelere o WordPress com os plugins certos no plano da FULL
Quem mantém vários sites economiza tempo e dinheiro centralizando os plugins de performance num único plano. O plano PRO da FULL custa R$849 por ano e libera WP Rocket, Perfmatters e mais 15 plugins premium para usar em até 10 sites, o que dá cerca de R$85 por site ao ano.
A gente vê no suporte que muita gente paga licença avulsa de três ou quatro plugins e acaba gastando mais do que pagaria pelo bundle inteiro da FULL. Em vez de comprar cada licença separada e renovar em datas diferentes, você ativa tudo com um clique e mantém os scripts enfileirados, minificados e com defer sem montar a stack na mão. É justamente o trabalho repetitivo que o enqueue manual exige site a site. Veja os detalhes do bundle em FULL.services/planos.
Perguntas frequentes sobre adicionar JavaScript no tema WordPress
Por que o JavaScript some depois que eu atualizo o tema WordPress?
Some porque o código foi colado direto no header.php ou no functions.php do tema pai, e a atualização sobrescreve esses arquivos. O WordPress baixa a versão nova do tema e apaga qualquer edição manual feita no tema original. A correção definitiva é mover o script para o functions.php de um child theme com wp_enqueue_script, já que o child theme não é tocado nas atualizações do tema pai.
É possível adicionar JavaScript no tema WordPress sem editar o functions.php?
Sim, dá para adicionar JavaScript no tema WordPress com um plugin de snippet como o Code Snippets, que executa o mesmo PHP do enqueue sem você abrir o functions.php. Ele isola o erro: um ponto e vírgula esquecido não derruba o site, ao contrário da edição direta no arquivo do tema. Para um único script simples também dá para usar a tela de scripts do próprio tema, quando o tema oferece esse campo no personalizador.
Qual a diferença entre colar o script no header e usar wp_enqueue_script?
A diferença é controle. Colar no header insere a tag de forma cega, sem versão, sem dependência e sem opção de carregar no rodapé. O wp_enqueue_script registra o arquivo na fila do core com handle único, declara que ele depende do jQuery, define a versão para cache busting e escolhe o local de carregamento. O core ainda evita carregar a mesma biblioteca duas vezes, algo impossível com a tag colada no template.
Como carregar um script que depende do jQuery sem dar erro?
Passe array(‘jquery’) no terceiro parâmetro do wp_enqueue_script, que é a lista de dependências. Isso obriga o WordPress a carregar o jQuery antes do seu arquivo, na ordem certa. Sem essa declaração, o navegador tenta executar o cifrão do jQuery antes da biblioteca existir e dispara “jQuery is not defined” no console, deixando a função sem efeito no frontend do site.
O que muda ao usar defer ou async no wp_enqueue_script?
O defer baixa o script em paralelo e só o executa depois que o HTML termina de montar, preservando a ordem dos arquivos. O async baixa e executa assim que possível, sem garantir ordem, então serve para scripts independentes como analytics. A partir do WordPress 6.3, você passa array com a chave strategy no 5º parâmetro do wp_enqueue_script. O defer é a escolha segura para scripts que dependem do DOM pronto.
Próximos passos para deixar os scripts do tema redondos
Adicionar JavaScript no tema WordPress da forma certa se resume a uma decisão: parar de colar tags no template e passar tudo pela função wp_enqueue_script dentro de um child theme. Com isso você ganha versão para cache busting, dependência declarada e defer no rodapé, os três pilares que mantêm o script vivo após cada atualização e leve nas Core Web Vitals. Comece criando o child theme, mova o código existente para o enqueue e teste em homologação antes de subir. Para continuar aprendendo WordPress, o FULL Academy reúne tutoriais, guias e reviews num só lugar.
Legenda: o enqueue no functions.php do child theme garante que o script sobreviva às atualizações do tema.
Saúde e Bem-Estar
Restaurantes & Alimentação
Hotelaria & Turismo
Imobiliárias & Construção
Negócios Locais & Franquias
E-commerce & Lojas Virtuais
Educação & Cursos
Profissionais Liberais & Serviços
Agências Digitais & Freelancers
MEIs e Autônomos
Agências e Freelancers
Pequenas Empresas
Startups
Franquias
Elementor PRO
Rank Math
SEOPress
Happy Addons
Tutor LMS
WP Optimize
Crocoblock
WP Rocket
Ultimate Addons
Perfmatter
Funnel Kit
AIOS
Astra PRO
ACF
Essential Addons
WP Forms
UpdraftPlus
Ver mais
FULL CRM 
FULL Widget
FULL Woo
FULL Pop-up
FULL Security
FULL NPS
FULL Update
FULL Social Proof
FULL Analytics
FULL Templates
FULL Creator AI
FULL Backup
FULL Safe Login
FULL SMTP
FULL Monitor
FULL Speed
FULL Cache
FULL Whitelabel
