<Script>

Diese API-Referenz hilft Ihnen zu verstehen, wie Sie die Props der 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 ist eine Übersicht der verfügbaren Props für die Script-Komponente:

Prop	Beispiel	Typ	Erforderlich
`src`	`src="http://example.com/script"`	String	Erforderlich, außer bei Inline-Skript
`strategy`	`strategy="lazyOnload"`	String	-
`onLoad`	`onLoad={onLoadFunc}`	Funktion	-
`onReady`	`onReady={onReadyFunc}`	Funktion	-
`onError`	`onError={onErrorFunc}`	Funktion	-

Erforderliche Props

Die <Script />-Komponente erfordert die folgenden Eigenschaften.

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

Optionale Props

Die <Script />-Komponente akzeptiert eine Reihe zusätzlicher Eigenschaften über die erforderlichen hinaus.

`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 die Hydration der Seite begonnen hat.
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 jedem Next.js-Modul heruntergeladen und ausgeführt, bevor irgendeine Hydration auf 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 im Root-Layout (app/layout.tsx) platziert werden und sind für Skripte gedacht, 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.

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

Gut zu wissen: Skripte mit beforeInteractive werden immer im head 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 geladen, nachdem die Hydration der Seite teilweise oder vollständig abgeschlossen ist. Dies ist die Standardstrategie der Script-Komponente und sollte für Skripte verwendet werden, die möglichst früh, aber nicht vor dem First-Party-Next.js-Code geladen werden müssen.

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 geladen, nachdem alle Ressourcen der Seite abgerufen wurden. Diese Strategie sollte für Hintergrund- oder niedrigprioritäre 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. Obwohl diese Strategie für jedes Skript verwendet werden kann, handelt es sich um einen fortgeschrittenen Anwendungsfall, der nicht garantiert alle Drittanbieter-Skripte unterstützt.

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 nach dem Laden des Skripts JavaScript-Code ausführen, um Inhalte zu instanziieren oder eine Funktion aufzurufen. Wenn Sie ein Skript mit der Lade-Strategie afterInteractive oder lazyOnload laden, können Sie Code nach dem Laden mit der onLoad-Eigenschaft ausführen.

Hier ist ein Beispiel für die Ausführung einer lodash-Methode erst nach dem Laden der Bibliothek:

'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 nach dem Laden des Skripts und bei jeder erneuten Einbindung der Komponente (z.B. nach einer Routennavigation) ausführen. Sie können Code nach dem Laden des Skripts und bei jeder erneuten Einbindung der Komponente mit der onReady-Eigenschaft ausführen.

Hier ist ein Beispiel für die erneute Instanziierung einer Google Maps JS-Einbettung bei jeder Einbindung der Komponente:

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`

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, Fehler beim Laden eines Skripts abzufangen. 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('Script 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`	`next/script` mit `beforeInteractive` darf in `_document` platziert werden.
`v11.0.0`	`next/script` eingeführt.