receita

Receita: adiar scripts de terceiros

Use defer, async e carregamento na primeira interação para tirar JavaScript não essencial do caminho da página.

resposta curtaAdiar JavaScript significa tirá-lo do caminho crítico. Em WordPress há três níveis: o parâmetro strategy de wp_enqueue_script (defer ou async, desde a versão 6.3), o filtro script_loader_tag para scripts que o tema ou plugins registram sem estratégia e a carga na primeira interação para widgets não essenciais. Cada script precisa de teste, porque adiar o errado quebra a página.
Neste texto

Que problema esta receita resolve?

Scripts de chat, pixels, mapas incorporados e widgets sociais costumam ser os maiores consumidores de tempo da thread principal. Enquanto eles executam, o navegador demora para responder a toques e cliques, o que prejudica o INP e atrasa a renderização. Adiar o que não precisa estar pronto no início libera a thread para o conteúdo e para a primeira interação.

A lógica vem de plugins de atraso de scripts e de gerenciamento de scripts externos que Camillo Dantas desenvolveu. Eles não estão à venda; esta receita ensina como decidir e como implementar.

Quando usar e quando não usar

Use para scripts que não afetam o que aparece na primeira tela nem a funcionalidade crítica: chat, mapas, vídeos incorporados, botões de compartilhamento, pixels de medição não essenciais ao carregamento.

Não use:

  • em scripts que o conteúdo inicial exige para funcionar (menu, carrossel acima da dobra, formulário de checkout);
  • em ferramentas de consentimento (cookies). Atrasá-las pode quebrar a regra de só carregar outros scripts depois da autorização;
  • sem ter medido antes. Adiar às cegas troca um problema por outro.

Pré-requisitos

  • Lista de scripts da página: o painel Rede do Chrome (filtro JS) mostra todos, com o tempo de cada um. O painel Desempenho mostra quem ocupa a thread.
  • WordPress 6.3 ou mais recente para o parâmetro strategy.
  • Ambiente de homologação.
  • Nível: intermediário.

Passo a passo

  1. 01Liste os scripts e classifique: crítico, necessário depois da carga, ou só sob interação.
  2. 02Para scripts seus, use strategy defer ou async ao registrar.
  3. 03Para scripts de outros, aplique defer pelo filtro script_loader_tag, por handle.
  4. 04Para widgets pesados, carregue na primeira interação ou depois de um tempo limite.
  5. 05Teste cada página-modelo; reverta o que quebrar.

Nível 1: strategy no núcleo

A função wp_enqueue_script() aceita, no quinto parâmetro, um array com a chave strategy. Pela documentação oficial, o valor pode ser defer ou async; o parâmetro foi introduzido na versão 6.3.0 e a árvore de dependências é considerada: o WordPress pode relaxar a estratégia pedida, mas nunca a torna mais restrita.

add_action( 'wp_enqueue_scripts', function () {
	wp_enqueue_script(
		'meu-widget',
		get_stylesheet_directory_uri() . '/js/widget.js',
		array(),
		'1.0.0',
		array(
			'strategy'  => 'defer',
			'in_footer' => true,
		)
	);
} );

defer executa depois que o documento foi analisado e preserva a ordem. async executa assim que baixa, sem ordem garantida; só use em scripts independentes.

Nível 2: scripts já registrados

Para scripts de tema ou plugin que você não controla, use o filtro script_loader_tag, que recebe a tag, o handle e a URL:

add_filter( 'script_loader_tag', function ( $tag, $handle, $src ) {
	$adiar = array( 'chat-widget', 'mapa-incorporado' ); // handles que você verificou.
	if ( in_array( $handle, $adiar, true ) && false === strpos( $tag, ' defer' ) ) {
		return str_replace( ' src=', ' defer src=', $tag );
	}
	return $tag;
}, 10, 3 );

Para descobrir os handles, rode em homologação add_action( 'wp_print_scripts', function(){ global $wp_scripts; error_log( implode( ',', $wp_scripts->queue ) ); } ); e leia o log. Retire o código depois.

Atenção: se o script depende de outro executado em linha (wp_add_inline_script), adiar só um deles pode quebrar a ordem. Teste.

Nível 3: carregar na primeira interação

Para um widget de chat, por exemplo, não adianta carregar antes de o visitante interagir. O padrão: um pequeno script próprio escuta o primeiro sinal de interação e então injeta o script real.

<script>
(function () {
  var URL_DO_WIDGET = "https://exemplo.com/widget.js"; // substitua pela URL real
  var carregado = false;
  function carregar() {
    if (carregado) return;
    carregado = true;
    var s = document.createElement("script");
    s.src = URL_DO_WIDGET;
    s.async = true;
    document.head.appendChild(s);
    ["pointerdown", "keydown", "scroll", "touchstart"].forEach(function (t) {
      window.removeEventListener(t, carregar);
    });
  }
  ["pointerdown", "keydown", "scroll", "touchstart"].forEach(function (t) {
    window.addEventListener(t, carregar, { once: true, passive: true });
  });
  // Plano B: carrega depois de 8 segundos mesmo sem interação.
  window.setTimeout(carregar, 8000);
})();
</script>

Imprima este bloco com wp_footer, no lugar da tag original do widget (remova a tag original para não carregar duas vezes). Quatro observações:

  • o tempo limite de 8 segundos é uma escolha; para pixels de medição que precisam registrar a visita, use um prazo bem menor ou carregue normalmente;
  • o primeiro clique no chat pode demorar um instante, porque o script começa a baixar quando o visitante toca;
  • nada disso vale para scripts condicionados a consentimento: carregue-os somente após a escolha do visitante, conforme a política de privacidade do site;
  • não adie o script que mede o INP (veja a receita de monitor de INP), senão a medição perde interações iniciais.

Como testar

Critério de sucesso: nenhuma funcionalidade crítica quebra, o tempo de bloqueio da thread principal cai no Lighthouse e o INP de campo não piora.

  1. Meça antes: rode o Lighthouse três vezes e anote Total Blocking Time e LCP.
  2. Aplique uma mudança por vez. Navegue pela página: menu, busca, formulário, botão de compra.
  3. Abra o console: erros "x is not defined" indicam dependência quebrada.
  4. Repita o Lighthouse. Compare a mediana.
  5. Após duas a quatro semanas, confira o INP no relatório de Core Web Vitals do Search Console. O limite considerado bom é de 200 ms no percentil 75, segundo o web.dev.

Erros comuns e como desfazer

ErroSintomaCorreção
Adiar o jQuery sem adiar o que depende dele"$ is not defined"adie os dois ou nenhum
async em scripts dependentesfalha intermitenteuse defer
Widget duplicadodois chats na telaremova a tag original
Adiar a ferramenta de consentimentoscripts rodam antes da autorizaçãonão adie
Sem teste em mobilequebra só no celularteste com emulação e aparelho real

Para desfazer, remova o código do filtro ou o bloco de wp_footer e limpe os caches de página e de minificação.

Checklist final

  • Lista de scripts com classificação.
  • Mudança por vez, com medição.
  • Consentimento fora do atraso.
  • Testes de formulário, menu e busca.
  • INP monitorado depois.
  • Plano de reversão anotado.

Seguindo adiante

Esta receita funciona junto com preload de fontes e imagem e com lazy load inteligente. O curso Core Web Vitals trata a otimização completa. O termo INP está no glossário. Os plugins de origem estão descritos em camillodantas.com.br/plugins.

Fontes

  1. wp_enqueue_script(), WordPress Developer Resources (2026-10-14)
  2. script_loader_tag, WordPress Developer Resources (2026-10-14)
  3. Interaction to Next Paint (INP), web.dev (2025-09-02)

Não sabe por onde começar?

Compare as opções e escolha a trilha pelo seu objetivo.