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

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}`	Function	-
`onReady`	`onReady={onReadyFunc}`	Function	-
`onError`	`onError={onErrorFunc}`	Function	-

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: (predeterminado) 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 antes de que ocurra cualquier hidratación en la página.

Los scripts con esta estrategia se precargan y se obtienen antes que 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 en el servidor).

Esta estrategia solo debe usarse para scripts críticos que necesitan obtenerse antes de que cualquier parte de la página se vuelva interactiva.

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 cargarse 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 predeterminada del componente Script y debe usarse para cualquier script que necesite cargarse lo antes posible pero no antes que cualquier código de primera parte de Next.js.

Los scripts afterInteractive pueden colocarse dentro de cualquier página o diseño 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 obtenido 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 diseño 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 obtenerse 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 directorio app. 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 actualmente solo pueden usarse en el directorio pages/:

import Script from 'next/script'

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

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 Componentes de Servidor y solo puede usarse en Componentes de Cliente. 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 las estrategias de carga afterInteractive o lazyOnload, 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]))
        }}
      />
    </>
  )
}

'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 Componentes de Servidor y solo puede usarse en Componentes de Cliente.

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 load 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 el componente se monta:

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 Componentes de Servidor y solo puede usarse en Componentes de Cliente. 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 que `next/script` con `beforeInteractive` se coloque en `_document`.
`v11.0.0`	Se introduce `next/script`.