Cómo cargar y optimizar scripts

Scripts en Layouts

Para cargar un script de terceros para múltiples rutas, importa next/script e incluye el script directamente en tu componente de layout:

import Script from 'next/script'

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

El script de terceros se obtendrá cuando el usuario acceda a la ruta de la carpeta (ej. dashboard/page.js) o cualquier ruta anidada (ej. dashboard/settings/page.js). Next.js asegurará que el script solo se cargue una vez, incluso si el usuario navega entre múltiples rutas dentro del mismo layout.

Scripts de Aplicación

Para cargar un script de terceros para todas las rutas, importa next/script e incluye el script directamente en tu layout raíz:

import Script from 'next/script'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>{children}</body>
      <Script src="https://example.com/script.js" />
    </html>
  )
}

Este script se cargará y ejecutará cuando se acceda a cualquier ruta de tu aplicación. Next.js asegurará que el script solo se cargue una vez, incluso si el usuario navega entre múltiples páginas.

Recomendación: Recomendamos incluir scripts de terceros solo en páginas o layouts específicos para minimizar el impacto innecesario en el rendimiento.

Estrategias

Aunque el comportamiento predeterminado de next/script te permite cargar scripts de terceros en cualquier página o layout, puedes ajustar su comportamiento de carga usando la propiedad strategy:

beforeInteractive: Carga el script antes de cualquier código de Next.js y antes de que ocurra la hidratación de la página.
afterInteractive: (predeterminado) Carga el script temprano pero después de que ocurra algo de hidratación en la página.
lazyOnload: Carga el script más tarde durante el tiempo de inactividad del navegador.
worker: (experimental) Carga el script en un web worker.

Consulta la documentación de referencia de la API next/script para aprender más sobre cada estrategia y sus casos de uso.

Descargar Scripts a un Web Worker (experimental)

Advertencia: La estrategia worker aún no es estable y no funciona con el App Router. Úsala con precaución.

Los scripts que usan la estrategia worker se descargan y ejecutan en un web worker con Partytown. Esto puede mejorar el rendimiento de tu sitio dedicando el hilo principal al resto del código de tu aplicación.

Esta estrategia es aún experimental y solo puede usarse si la bandera nextScriptWorkers está habilitada en next.config.js:

next.config.js

module.exports = {
  experimental: {
    nextScriptWorkers: true,
  },
}

Luego, ejecuta next (normalmente npm run dev o yarn dev) y Next.js te guiará a través de la instalación de los paquetes necesarios para completar la configuración:

Terminal

npm run dev

Verás instrucciones como estas: Por favor instala Partytown ejecutando npm install @builder.io/partytown

Una vez completada la configuración, definir strategy="worker" instanciará automáticamente Partytown en tu aplicación y descargará el script a un web worker.

import Script from 'next/script'

export default function Home() {
  return (
    <>
      <Script src="https://example.com/script.js" strategy="worker" />
    </>
  )
}

Hay varias compensaciones que deben considerarse al cargar un script de terceros en un web worker. Consulta la documentación de compensaciones de Partytown para más información.

Scripts en línea

Los scripts en línea, o scripts no cargados desde un archivo externo, también son soportados por el componente Script. Se pueden escribir colocando el JavaScript entre llaves:

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

O usando la propiedad dangerouslySetInnerHTML:

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

Advertencia: Se debe asignar una propiedad id a los scripts en línea para que Next.js pueda rastrear y optimizar el script.

Ejecutar Código Adicional

Los manejadores de eventos se pueden usar con el componente Script para ejecutar código adicional después de que ocurra cierto evento:

onLoad: Ejecuta código después de que el script haya terminado de cargarse.
onReady: Ejecuta código después de que el script haya terminado de cargarse y cada vez que el componente se monte.
onError: Ejecuta código si el script falla al cargarse.

Estos manejadores solo funcionarán cuando next/script se importe y use dentro de un Componente Cliente donde "use client" esté definido como la primera línea de código:

'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')
        }}
      />
    </>
  )
}

Consulta la referencia de la API next/script para aprender más sobre cada manejador de eventos y ver ejemplos.

Atributos Adicionales

Hay muchos atributos DOM que se pueden asignar a un elemento <script> que no son usados por el componente Script, como nonce o atributos de datos personalizados. Incluir cualquier atributo adicional lo reenviará automáticamente al elemento <script> final y optimizado que se incluye en el HTML.

import Script from 'next/script'

export default function Page() {
  return (
    <>
      <Script
        src="https://example.com/script.js"
        id="example-script"
        nonce="XUENAJFW"
        data-test="script"
      />
    </>
  )
}

Script

Optimiza scripts de terceros en tu aplicación Next.js usando el componente integrado `next/script`.