logoNext.js Français
DocumentationBlogApprendre
Introduction/Référence API/Composants/<Script>

<Script>

Cette référence 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" />
    </>
  )
}
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 :

PropExempleTypeRequis
srcsrc="http://example.com/script"StringRequis sauf si script inline utilisé
strategystrategy="lazyOnload"String-
onLoadonLoad={onLoadFunc}Function-
onReadyonReady={onReadyFunc}Function-
onErroronError={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 avant toute hydratation de la page.

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

Les scripts beforeInteractive doivent être placés dans la mise en page racine (app/layout.tsx) 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 avant qu'une partie quelconque de la page ne devienne interactive.

import Script from 'next/script'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script
          src="https://example.com/script.js"
          strategy="beforeInteractive"
        />
      </body>
    </html>
  )
}
import Script from 'next/script'

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        {children}
        <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 chargés dès que possible avec beforeInteractive incluent :

  • 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 certaine (ou toute) 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 first-party.

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 incluent :

  • 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 aient é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 incluent :

  • 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 répertoire app. À utiliser avec prudence.

Les scripts qui utilisent la stratégie worker sont déchargés vers un web worker afin de libérer le thread principal et de s'assurer que seules les ressources first-party critiques y sont traitées. Bien que cette stratégie puisse être utilisée pour n'importe quel script, il s'agit d'un cas d'utilisation avancé qui ne garantit pas de supporter 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 ne peuvent actuellement être utilisés que dans le répertoire 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

Avertissement : onLoad ne fonctionne pas encore avec les Server Components et ne peut être utilisé que dans les Client Components. 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 après que le script a fini de charger afin d'instancier du contenu ou d'appeler une fonction. Si vous chargez un script avec soit afterInteractive soit 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]))
        }}
      />
    </>
  )
}
'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 Server Components et ne peut être utilisé que dans les Client Components.

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é :

'use client'

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,
          })
        }}
      />
    </>
  )
}
'use client'

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 Server Components et ne peut être utilisé que dans les Client Components. onError ne peut pas être utilisé avec la stratégie de chargement beforeInteractive.

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

'use client'

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)
        }}
      />
    </>
  )
}
'use client'

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

VersionChangements
v13.0.0beforeInteractive et afterInteractive modifiés pour supporter app.
v12.2.4Ajout de la prop onReady.
v12.2.2Permet à next/script avec beforeInteractive d'être placé dans _document.
v11.0.0Introduction de next/script.

Composant <Link>

Activez une navigation côté client rapide avec le composant intégré `next/link`.

Conventions de fichiers

Référence API pour les fichiers spéciaux de Next.js.