Script

Esta referencia de API te ayudará a entender cómo usar las props disponibles para el componente Script. Para características y uso, consulta la página Optimización de Scripts.

import Script from 'next/script'

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

Props

Aquí hay un resumen de las props disponibles para el componente Script:

Prop	Ejemplo	Tipo	Requerido
`src`	`src="http://example.com/script"`	String	Requerido a menos que se use un script inline
`strategy`	`strategy="lazyOnload"`	String	-
`onLoad`	`onLoad={onLoadFunc}`	Función	-
`onReady`	`onReady={onReadyFunc}`	Función	-
`onError`	`onError={onErrorFunc}`	Función	-

Props Requeridas

El componente <Script /> requiere las siguientes propiedades.

`src`

Una cadena que especifica la URL de un script externo. Puede ser una URL externa absoluta o una ruta interna. La propiedad src es requerida a menos que se use un script inline.

Props Opcionales

El componente <Script /> acepta varias propiedades adicionales más allá de las requeridas.

`strategy`

La estrategia de carga del script. Hay cuatro estrategias diferentes que se pueden usar:

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

Los scripts que se cargan con la estrategia beforeInteractive se inyectan en el HTML inicial desde el servidor, se descargan antes de cualquier módulo de Next.js y se ejecutan en el orden en que se colocan.

Los scripts denotados con esta estrategia se precargan y se recuperan antes de cualquier código de primera parte, pero su ejecución no bloquea la hidratación de la página.

Los scripts beforeInteractive deben colocarse dentro del componente Document (pages/_document.js) y están diseñados para cargar scripts que son necesarios para todo el sitio (es decir, el script se cargará cuando cualquier página de la aplicación se haya cargado del lado del servidor).

Esta estrategia solo debe usarse para scripts críticos que necesitan recuperarse lo antes posible.

pages/_document.js

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

export default function Document() {
  return (
    <Html>
      <Head />
      <body>
        <Main />
        <NextScript />
        <Script
          src="https://example.com/script.js"
          strategy="beforeInteractive"
        />
      </body>
    </Html>
  )
}

Nota importante: Los scripts con beforeInteractive siempre se inyectarán dentro del head del documento HTML, independientemente de dónde se coloquen en el componente.

Algunos ejemplos de scripts que deberían recuperarse lo antes posible con beforeInteractive incluyen:

Detectores de bots
Gestores de consentimiento de cookies

`afterInteractive`

Los scripts que usan la estrategia afterInteractive se inyectan en el HTML del lado del cliente y se cargarán después de que ocurra algo (o toda) la hidratación en la página. Esta es la estrategia por defecto del componente Script y debe usarse para cualquier script que necesite cargarse lo antes posible pero no antes de cualquier código de primera parte de Next.js.

Los scripts afterInteractive pueden colocarse dentro de cualquier página o layout y solo se cargarán y ejecutarán cuando esa página (o grupo de páginas) se abra en el navegador.

app/page.js

import Script from 'next/script'

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

Algunos ejemplos de scripts que son buenos candidatos para afterInteractive incluyen:

Gestores de etiquetas
Analíticas

`lazyOnload`

Los scripts que usan la estrategia lazyOnload se inyectan en el HTML del lado del cliente durante el tiempo de inactividad del navegador y se cargarán después de que se hayan recuperado todos los recursos en la página. Esta estrategia debe usarse para cualquier script de fondo o de baja prioridad que no necesite cargarse temprano.

Los scripts lazyOnload pueden colocarse dentro de cualquier página o layout y solo se cargarán y ejecutarán cuando esa página (o grupo de páginas) se abra en el navegador.

app/page.js

import Script from 'next/script'

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

Ejemplos de scripts que no necesitan cargarse inmediatamente y pueden recuperarse con lazyOnload incluyen:

Plugins de soporte de chat
Widgets de redes sociales

`worker`

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

Los scripts que usan la estrategia worker se descargan a un web worker para liberar el hilo principal y asegurar que solo los recursos críticos de primera parte se procesen en él. Aunque esta estrategia puede usarse para cualquier script, es un caso de uso avanzado que no garantiza soportar todos los scripts de terceros.

Para usar worker como estrategia, la bandera nextScriptWorkers debe estar habilitada en next.config.js:

next.config.js

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

Los scripts worker solo pueden usarse actualmente en el directorio pages/:

import Script from 'next/script'

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

`onLoad`

Advertencia: onLoad aún no funciona con Server Components y solo puede usarse en Client Components. Además, onLoad no puede usarse con beforeInteractive – considera usar onReady en su lugar.

Algunos scripts de terceros requieren que los usuarios ejecuten código JavaScript una vez después de que el script haya terminado de cargarse para instanciar contenido o llamar a una función. Si estás cargando un script con afterInteractive o lazyOnload como estrategia de carga, puedes ejecutar código después de que se haya cargado usando la propiedad onLoad.

Aquí hay un ejemplo de cómo ejecutar un método de lodash solo después de que la biblioteca se haya cargado.

'use client'

import Script from 'next/script'

export default function Page() {
  return (
    <>
      <Script
        src="https://cdnjs.cloudflare.com/ajax/libs/lodash.js/4.17.20/lodash.min.js"
        onLoad={() => {
          console.log(_.sample([1, 2, 3, 4]))
        }}
      />
    </>
  )
}

`onReady`

Advertencia: onReady aún no funciona con Server Components y solo puede usarse en Client Components.

Algunos scripts de terceros requieren que los usuarios ejecuten código JavaScript después de que el script haya terminado de cargarse y cada vez que el componente se monta (después de una navegación de ruta, por ejemplo). Puedes ejecutar código después del evento de carga del script cuando se carga por primera vez y luego después de cada re-montaje posterior del componente usando la propiedad onReady.

Aquí hay un ejemplo de cómo reinstanciar un embed de Google Maps JS cada vez que se monta el componente:

import { useRef } from 'react'
import Script from 'next/script'

export default function Page() {
  const mapRef = useRef()

  return (
    <>
      <div ref={mapRef}></div>
      <Script
        id="google-maps"
        src="https://maps.googleapis.com/maps/api/js"
        onReady={() => {
          new google.maps.Map(mapRef.current, {
            center: { lat: -34.397, lng: 150.644 },
            zoom: 8,
          })
        }}
      />
    </>
  )
}

`onError`

Advertencia: onError aún no funciona con Server Components y solo puede usarse en Client Components. onError no puede usarse con la estrategia de carga beforeInteractive.

A veces es útil detectar cuando un script no se carga correctamente. Estos errores pueden manejarse con la propiedad onError:

import Script from 'next/script'

export default function Page() {
  return (
    <>
      <Script
        src="https://example.com/script.js"
        onError={(e: Error) => {
          console.error('El script no se pudo cargar', e)
        }}
      />
    </>
  )
}

Historial de Versiones

Versión	Cambios
`v13.0.0`	`beforeInteractive` y `afterInteractive` se modifican para soportar `app`.
`v12.2.4`	Se añade la prop `onReady`.
`v12.2.2`	Permite colocar `next/script` con `beforeInteractive` en `_document`.
`v11.0.0`	Se introduce `next/script`.