Scripts

Core Idea

O componente next/script otimiza o carregamento de scripts de terceiros, controlando quando e como eles executam em relação à hidratação da página.

Key Concepts

• Layout scripts: <Script> dentro de um layout carrega o script uma única vez para todas as rotas daquele layout e suas rotas aninhadas.
• Application scripts: <Script> no root layout carrega o script globalmente, uma única vez, em qualquer rota acessada.
• strategy: controla o timing de carregamento — beforeInteractive (antes de qualquer código Next.js/hidratação), afterInteractive (padrão, logo após hidratação parcial), lazyOnload (idle time do browser), worker (experimental, via web worker/Partytown).
• Inline scripts: precisam de um id explícito para o Next.js rastrear e otimizar; podem usar children com template string ou dangerouslySetInnerHTML.
• Event handlers (onLoad, onReady, onError): só funcionam em Client Component ('use client').
• Atributos adicionais: qualquer atributo DOM extra (nonce, data-*) é encaminhado automaticamente pro elemento <script> final.

Code Examples

import Script from 'next/script'

export default function DashboardLayout({ children }: { children: React.ReactNode }) {
  return (
    <>
      <section>{children}</section>
      <Script src="https://example.com/script.js" />
    </>
  )
}

• O que demonstra: script escopado a uma rota e suas subrotas, carregado apenas uma vez mesmo com navegação interna.

'use client'
import Script from 'next/script'

export default function Page() {
  return (
    <Script
      src="https://example.com/script.js"
      onLoad={() => console.log('Script has loaded')}
    />
  )
}

• O que demonstra: uso de onLoad exige 'use client'.

Reference Tables

Strategy	Quando carrega
beforeInteractive	Antes de qualquer código Next.js e hidratação
afterInteractive (padrão)	Logo após hidratação parcial
lazyOnload	Durante idle time do browser
worker (experimental)	Em web worker via Partytown, ainda não funciona no App Router

Anti-patterns

• Colocar scripts de terceiros no root layout por padrão: recomenda-se restringir a páginas/layouts específicos para minimizar impacto de performance desnecessário em rotas que não precisam do script.
• Inline script sem id: Next.js não consegue rastrear/otimizar o script sem esse atributo.

Key Takeaways

1. Prefira escopar o <Script> ao layout mais específico possível em vez do root layout.
2. strategy="worker" ainda é experimental e não funciona no App Router.
3. Handlers de evento (onLoad/onReady/onError) exigem Client Component.

Connects To

• Third Party Libraries (ch090): uso mais amplo de next/script e wrappers para libs de terceiros.