Scripts

Core Idea

next/script otimiza o carregamento de scripts de terceiros, controlando quando e como eles executam em relação à hidratação da página, incluindo offload para web worker.

Key Concepts

<Script src="..." />: componente que carrega script externo apenas uma vez, mesmo com navegação entre páginas.
strategy="beforeInteractive": carrega antes de qualquer código Next.js e antes da hidratação.
strategy="afterInteractive" (padrão): carrega cedo, mas após alguma hidratação.
strategy="lazyOnload": carrega durante idle time do browser.
strategy="worker" (experimental): offload para web worker via Partytown; não funciona no App Router; requer experimental.nextScriptWorkers: true.
Inline scripts: precisam de id obrigatório para o Next.js rastrear e otimizar.
onLoad / onReady / onError: handlers de evento, só funcionam em Client Component ("use client").
Atributos adicionais (nonce, data-*): repassados automaticamente para a tag <script> final.

Code Examples

import Script from 'next/script'

export default function MyApp({ Component, pageProps }) {
  return (
    <>
      <Component {...pageProps} />
      <Script src="https://example.com/script.js" />
    </>
  )
}

O que demonstra: carregar script de terceiro globalmente via _app, com dedupe automático entre navegações.

<Script id="show-banner">
  {`document.getElementById('banner').classList.remove('hidden')`}
</Script>

O que demonstra: script inline exige id para ser rastreado/otimizado pelo Next.js.

Reference Tables

Strategy	Quando carrega
`beforeInteractive`	Antes de qualquer código Next.js / hidratação
`afterInteractive` (default)	Cedo, após alguma hidratação
`lazyOnload`	Durante idle time do browser
`worker` (experimental)	Em web worker via Partytown, não estável, sem suporte no App Router

Anti-patterns

Incluir script de terceiro globalmente em _app por padrão: recomendação é restringir a páginas/layouts específicos para minimizar impacto de performance.
Usar strategy="worker" em produção sem avaliar trade-offs: ainda experimental e com limitações documentadas pelo Partytown.

Key Takeaways

next/script garante que o script carregue só uma vez mesmo com múltiplas navegações client-side.
A escolha de strategy é o principal controle de performance/prioridade.
Handlers de evento (onLoad, onReady, onError) exigem Client Component.
Configuração customizada do Partytown vai no <Head> do _document.js via data-partytown-config.

Connects To

Font Module / <Image>: outros componentes de otimização automática citados em Production.
Custom Document (_document.js): onde configurar Partytown.