Script

Cette référence d'API vous aidera à comprendre comment utiliser les props disponibles pour le composant Script. Pour les fonctionnalités et l'utilisation, veuillez consulter la page Optimisation des scripts.

import Script from 'next/script'

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

Props

Voici un récapitulatif des props disponibles pour le composant Script :

Prop	Exemple	Type	Requis
`src`	`src="http://example.com/script"`	String	Requis sauf si script inline utilisé
`strategy`	`strategy="lazyOnload"`	String	-
`onLoad`	`onLoad={onLoadFunc}`	Function	-
`onReady`	`onReady={onReadyFunc}`	Function	-
`onError`	`onError={onErrorFunc}`	Function	-

Props Requises

Le composant <Script /> nécessite les propriétés suivantes.

`src`

Une chaîne de caractères spécifiant l'URL d'un script externe. Cela peut être une URL externe absolue ou un chemin interne. La propriété src est requise sauf si un script inline est utilisé.

Props Optionnelles

Le composant <Script /> accepte un certain nombre de propriétés supplémentaires au-delà de celles qui sont requises.

`strategy`

La stratégie de chargement du script. Il existe quatre stratégies différentes qui peuvent être utilisées :

beforeInteractive : Charge avant tout code Next.js et avant toute hydratation de page.
afterInteractive : (par défaut) Charge tôt mais après une certaine hydratation de la page.
lazyOnload : Charge pendant les temps d'inactivité du navigateur.
worker : (expérimental) Charge dans un web worker.

`beforeInteractive`

Les scripts qui se chargent avec la stratégie beforeInteractive sont injectés dans le HTML initial depuis le serveur, téléchargés avant tout module Next.js, et exécutés dans l'ordre où ils sont placés.

Les scripts marqués avec cette stratégie sont préchargés et récupérés avant tout code propriétaire, mais leur exécution ne bloque pas l'hydratation de la page.

Les scripts beforeInteractive doivent être placés dans le composant Document (pages/_document.js) et sont conçus pour charger des scripts nécessaires à l'ensemble du site (c'est-à-dire que le script se chargera lorsque n'importe quelle page de l'application a été chargée côté serveur).

Cette stratégie ne doit être utilisée que pour les scripts critiques qui doivent être récupérés dès que possible.

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

Bon à savoir : Les scripts avec beforeInteractive seront toujours injectés dans le head du document HTML, peu importe où ils sont placés dans le composant.

Quelques exemples de scripts qui devraient être récupérés dès que possible avec beforeInteractive :

Détecteurs de bots
Gestionnaires de consentement aux cookies

`afterInteractive`

Les scripts qui utilisent la stratégie afterInteractive sont injectés dans le HTML côté client et se chargeront après qu'une partie (ou la totalité) de l'hydratation se soit produite sur la page. C'est la stratégie par défaut du composant Script et devrait être utilisée pour tout script qui doit se charger dès que possible mais pas avant tout code Next.js propriétaire.

Les scripts afterInteractive peuvent être placés dans n'importe quelle page ou mise en page et ne se chargeront et s'exécuteront que lorsque cette page (ou groupe de pages) est ouverte dans le navigateur.

app/page.js

import Script from 'next/script'

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

Quelques exemples de scripts qui sont de bons candidats pour afterInteractive :

Gestionnaires de tags
Analytics

`lazyOnload`

Les scripts qui utilisent la stratégie lazyOnload sont injectés dans le HTML côté client pendant les temps d'inactivité du navigateur et se chargeront après que toutes les ressources de la page ont été récupérées. Cette stratégie devrait être utilisée pour tout script en arrière-plan ou de faible priorité qui n'a pas besoin de se charger tôt.

Les scripts lazyOnload peuvent être placés dans n'importe quelle page ou mise en page et ne se chargeront et s'exécuteront que lorsque cette page (ou groupe de pages) est ouverte dans le navigateur.

app/page.js

import Script from 'next/script'

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

Exemples de scripts qui n'ont pas besoin de se charger immédiatement et peuvent être récupérés avec lazyOnload :

Plugins de support chat
Widgets de réseaux sociaux

`worker`

Avertissement : La stratégie worker n'est pas encore stable et ne fonctionne pas encore avec le routeur App. À utiliser avec prudence.

Les scripts qui utilisent la stratégie worker sont déchargés dans un web worker afin de libérer le thread principal et de s'assurer que seules les ressources propriétaires critiques sont traitées sur celui-ci. Bien que cette stratégie puisse être utilisée pour n'importe quel script, c'est un cas d'utilisation avancé qui ne garantit pas la prise en charge de tous les scripts tiers.

Pour utiliser worker comme stratégie, le flag nextScriptWorkers doit être activé dans next.config.js :

next.config.js

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

Les scripts worker peuvent actuellement uniquement être utilisés dans le répertoire pages/ :

import Script from 'next/script'

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

`onLoad`

Avertissement : onLoad ne fonctionne pas encore avec les composants serveur et ne peut être utilisé que dans les composants client. De plus, onLoad ne peut pas être utilisé avec beforeInteractive - envisagez d'utiliser onReady à la place.

Certains scripts tiers nécessitent que les utilisateurs exécutent du code JavaScript une fois que le script a fini de charger afin d'instancier du contenu ou d'appeler une fonction. Si vous chargez un script avec afterInteractive ou lazyOnload comme stratégie de chargement, vous pouvez exécuter du code après son chargement en utilisant la propriété onLoad.

Voici un exemple d'exécution d'une méthode lodash uniquement après que la bibliothèque a été chargée.

'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`

Avertissement : onReady ne fonctionne pas encore avec les composants serveur et ne peut être utilisé que dans les composants client.

Certains scripts tiers nécessitent que les utilisateurs exécutent du code JavaScript après que le script a fini de charger et à chaque fois que le composant est monté (après une navigation de route par exemple). Vous pouvez exécuter du code après l'événement de chargement du script lors de son premier chargement, puis après chaque remontage ultérieur du composant en utilisant la propriété onReady.

Voici un exemple de comment ré-instancier un embed Google Maps JS à chaque fois que le composant est monté :

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`

Avertissement : onError ne fonctionne pas encore avec les composants serveur et ne peut être utilisé que dans les composants client. onError ne peut pas être utilisé avec la stratégie de chargement beforeInteractive.

Il est parfois utile de détecter quand un script échoue à se charger. Ces erreurs peuvent être gérées avec la propriété onError :

import Script from 'next/script'

export default function Page() {
  return (
    <>
      <Script
        src="https://example.com/script.js"
        onError={(e: Error) => {
          console.error('Échec du chargement du script', e)
        }}
      />
    </>
  )
}

Historique des Versions

Version	Changements
`v13.0.0`	`beforeInteractive` et `afterInteractive` modifiés pour supporter `app`.
`v12.2.4`	Ajout de la prop `onReady`.
`v12.2.2`	Autorisation de `next/script` avec `beforeInteractive` dans `_document`.
`v11.0.0`	Introduction de `next/script`.

On this page