logoNext.js Español
DocumentaciónBlogAprender
Introducción/Referencia de API/Componentes/<Script>

<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í tienes un resumen de las props disponibles para el componente Script:

PropEjemploTipoRequerido
srcsrc="http://example.com/script"StringRequerido a menos que se use un script inline
strategystrategy="lazyOnload"String-
onLoadonLoad={onLoadFunc}Función-
onReadyonReady={onReadyFunc}Función-
onErroronError={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 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.

beforeInteractive

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 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 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 diseño raíz (app/layout.tsx) 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 cargarse antes de que cualquier parte de la página se vuelva interactiva.

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 Next.js de primera parte.

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 de 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. Úsala 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 se procesen en él recursos críticos de primera parte. 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í tienes 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 monte (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 nuevo montaje del componente usando la propiedad onReady.

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

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

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

  return (
    <PagesOnly>
      <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 capturar cuando un script falla al cargarse. 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('Error al cargar el script', e)
        }}
      />
    </>
  )
}

Historial de Versiones

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

<Link>

Referencia de API para el componente <Link>.

Funciones

Referencia de API para funciones y hooks en el enrutador de páginas (Pages Router).