Cómo cargar y optimizar scripts

Scripts de Aplicación

Para cargar un script de terceros para todas las rutas, importa next/script e incluye el script directamente en tu _app personalizado:

pages/_app.js

import Script from 'next/script'

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

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.

Usar configuración personalizada de Partytown

Aunque la estrategia worker no requiere configuración adicional para funcionar, Partytown soporta el uso de un objeto de configuración para modificar algunos de sus ajustes, incluyendo habilitar el modo debug y reenviar eventos y triggers.

Si deseas agregar opciones de configuración adicionales, puedes incluirlas dentro del componente <Head /> usado en un _document.js personalizado:

_pages/document.jsx

import { Html, Head, Main, NextScript } from 'next/document'

export default function Document() {
  return (
    <Html>
      <Head>
        <script
          data-partytown-config
          dangerouslySetInnerHTML={{
            __html: `
              partytown = {
                lib: "/_next/static/~partytown/",
                debug: true
              };
            `,
          }}
        />
      </Head>
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  )
}

Para modificar la configuración predeterminada de Partytown, se deben cumplir las siguientes condiciones:

Se debe usar el atributo data-partytown-config para sobrescribir la configuración predeterminada usada por Next.js
A menos que decidas guardar los archivos de la biblioteca de Partytown en un directorio separado, la propiedad lib: "/_next/static/~partytown/" debe incluirse en el objeto de configuración para que Partytown sepa dónde Next.js almacena los archivos estáticos necesarios.

Nota: Si estás usando un asset prefix y deseas modificar la configuración predeterminada de Partytown, debes incluirlo como parte de la ruta lib.

Revisa las opciones de configuración de Partytown para ver la lista completa de otras propiedades que se pueden agregar.

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:

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