<Script>

Diese API-Referenz hilft Ihnen zu verstehen, wie Sie die verfügbaren Props für die Script-Komponente verwenden können. Informationen zu Funktionen und Verwendung finden Sie auf der Seite Optimierung von Skripten.

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

Hier eine Übersicht der verfügbaren Props für die Script-Komponente:

Prop	Beispiel	Typ	Erforderlich
`src`	`src="http://example.com/script"`	String	Erforderlich, sofern kein Inline-Skript verwendet wird
`strategy`	`strategy="lazyOnload"`	String	-
`onLoad`	`onLoad={onLoadFunc}`	Funktion	-
`onReady`	`onReady={onReadyFunc}`	Funktion	-
`onError`	`onError={onErrorFunc}`	Funktion	-

Erforderliche Props

Die <Script />-Komponente erfordert folgende Eigenschaften.

`src`

Ein Pfad-String, der die URL eines externen Skripts angibt. Dies kann entweder eine absolute externe URL oder ein interner Pfad sein. Die src-Eigenschaft ist erforderlich, sofern kein Inline-Skript verwendet wird.

Optionale Props

Die <Script />-Komponente akzeptiert eine Reihe zusätzlicher Eigenschaften neben den erforderlichen.

`strategy`

Die Lade-Strategie des Skripts. Es gibt vier verschiedene Strategien:

beforeInteractive: Lädt vor jeglichem Next.js-Code und vor der Hydration der Seite.
afterInteractive: (Standard) Lädt früh, aber nachdem ein Teil der Hydration der Seite erfolgt ist.
lazyOnload: Lädt während der Leerlaufzeit des Browsers.
worker: (experimentell) Lädt in einem Web Worker.

`beforeInteractive`

Skripte, die mit der beforeInteractive-Strategie geladen werden, werden in das initiale HTML vom Server eingefügt, vor jeglichem Next.js-Modul heruntergeladen und in der Reihenfolge ausgeführt, in der sie platziert wurden, bevor irgendeine Hydration der Seite stattfindet.

Skripte mit dieser Strategie werden vorab geladen und vor jeglichem First-Party-Code abgerufen, ihre Ausführung blockiert jedoch nicht die Hydration der Seite.

beforeInteractive-Skripte müssen in der Document-Komponente (pages/_document.js) platziert werden und sind dafür ausgelegt, Skripte zu laden, die für die gesamte Website benötigt werden (d.h. das Skript wird geladen, wenn eine beliebige Seite der Anwendung serverseitig geladen wurde).

Diese Strategie sollte nur für kritische Skripte verwendet werden, die abgerufen werden müssen, bevor irgendein Teil der Seite interaktiv wird.

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

Wichtig zu wissen: Skripte mit beforeInteractive werden immer innerhalb des head-Elements des HTML-Dokuments eingefügt, unabhängig davon, wo sie in der Komponente platziert sind.

Beispiele für Skripte, die möglichst früh mit beforeInteractive geladen werden sollten:

Bot-Erkennung
Cookie-Consent-Manager

`afterInteractive`

Skripte, die die afterInteractive-Strategie verwenden, werden clientseitig in das HTML eingefügt und werden nach einem Teil (oder der gesamten) Hydration der Seite geladen. Dies ist die Standardstrategie der Script-Komponente und sollte für jedes Skript verwendet werden, das möglichst früh, aber nicht vor jeglichem First-Party-Next.js-Code geladen werden muss.

afterInteractive-Skripte können in jeder Seite oder jedem Layout platziert werden und werden nur geladen und ausgeführt, wenn diese Seite (oder Gruppe von Seiten) im Browser geöffnet wird.

app/page.js

import Script from 'next/script'

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

Beispiele für Skripte, die sich gut für afterInteractive eignen:

Tag-Manager
Analysetools

`lazyOnload`

Skripte, die die lazyOnload-Strategie verwenden, werden clientseitig während der Leerlaufzeit des Browsers in das HTML eingefügt und werden nachdem alle Ressourcen der Seite abgerufen wurden geladen. Diese Strategie sollte für Hintergrund- oder niedrig priorisierte Skripte verwendet werden, die nicht früh geladen werden müssen.

lazyOnload-Skripte können in jeder Seite oder jedem Layout platziert werden und werden nur geladen und ausgeführt, wenn diese Seite (oder Gruppe von Seiten) im Browser geöffnet wird.

app/page.js

import Script from 'next/script'

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

Beispiele für Skripte, die nicht sofort geladen werden müssen und mit lazyOnload abgerufen werden können:

Chat-Support-Plugins
Social-Media-Widgets

`worker`

Warnung: Die worker-Strategie ist noch nicht stabil und funktioniert noch nicht mit dem app-Verzeichnis. Mit Vorsicht verwenden.

Skripte, die die worker-Strategie verwenden, werden in einen Web Worker ausgelagert, um den Hauptthread zu entlasten und sicherzustellen, dass nur kritische First-Party-Ressourcen darauf verarbeitet werden. Während diese Strategie für jedes Skript verwendet werden kann, handelt es sich um einen fortgeschrittenen Anwendungsfall, der nicht für alle Drittanbieter-Skripte garantiert funktioniert.

Um worker als Strategie zu verwenden, muss das nextScriptWorkers-Flag in next.config.js aktiviert werden:

next.config.js

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

worker-Skripte können derzeit nur im pages/-Verzeichnis verwendet werden:

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`

Warnung: onLoad funktioniert noch nicht mit Server Components und kann nur in Client Components verwendet werden. Außerdem kann onLoad nicht mit beforeInteractive verwendet werden – erwägen Sie stattdessen die Verwendung von onReady.

Einige Drittanbieter-Skripte erfordern, dass Benutzer JavaScript-Code ausführen, sobald das Skript fertig geladen wurde, um Inhalte zu instanziieren oder eine Funktion aufzurufen. Wenn Sie ein Skript mit den Lade-Strategien afterInteractive oder lazyOnload laden, können Sie Code nach dem Laden mit der onLoad-Eigenschaft ausführen.

Hier ein Beispiel für die Ausführung einer lodash-Methode, nachdem die Bibliothek geladen wurde:

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

Warnung: onReady funktioniert noch nicht mit Server Components und kann nur in Client Components verwendet werden.

Einige Drittanbieter-Skripte erfordern, dass Benutzer JavaScript-Code ausführen, nachdem das Skript fertig geladen wurde und jedes Mal, wenn die Komponente eingebunden wird (z.B. nach einer Routennavigation). Sie können Code nach dem load-Event des Skripts beim ersten Laden und dann nach jedem erneuten Einbinden der Komponente mit der onReady-Eigenschaft ausführen.

Hier ein Beispiel, wie ein Google Maps JS-Embed bei jedem Einbinden der Komponente neu instanziiert wird:

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`

Warnung: onError funktioniert noch nicht mit Server Components und kann nur in Client Components verwendet werden. onError kann nicht mit der beforeInteractive-Lade-Strategie verwendet werden.

Manchmal ist es hilfreich, zu erkennen, wenn ein Skript nicht geladen werden kann. Diese Fehler können mit der onError-Eigenschaft behandelt werden:

import Script from 'next/script'

export default function Page() {
  return (
    <>
      <Script
        src="https://example.com/script.js"
        onError={(e: Error) => {
          console.error('Skript konnte nicht geladen werden', e)
        }}
      />
    </>
  )
}

Versionsverlauf

Version	Änderungen
`v13.0.0`	`beforeInteractive` und `afterInteractive` wurden für `app` angepasst.
`v12.2.4`	`onReady`-Prop hinzugefügt.
`v12.2.2`	Ermöglicht die Platzierung von `next/script` mit `beforeInteractive` in `_document`.
`v11.0.0`	`next/script` eingeführt.

On this page