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

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, ein Inline-Skript wird verwendet.

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 jedem Next.js-Code und vor der Hydratation der Seite.
afterInteractive: (Standard) Lädt früh, aber nachdem eine teilweise Hydratation 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 jedem Next.js-Modul heruntergeladen und in der Reihenfolge ihrer Platzierung ausgeführt.

Skripte mit dieser Strategie werden vorab geladen und vor erstparteiigem Code abgerufen, aber ihre Ausführung blockiert nicht die Hydratation 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 Site 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 so schnell wie möglich abgerufen werden müssen.

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

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 mit beforeInteractive so schnell wie möglich geladen werden sollten:

Bot-Erkennung
Cookie-Consent-Manager

`afterInteractive`

Skripte, die die afterInteractive-Strategie verwenden, werden clientseitig in das HTML eingefügt und nach einer (oder vollständigen) Hydratation der Seite geladen. Dies ist die Standardstrategie der Script-Komponente und sollte für jedes Skript verwendet werden, das so schnell wie möglich, aber nicht vor erstparteiigem 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 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 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-Router. 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, erstparteiige 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 ist.

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

`onLoad`

Warnung: onLoad funktioniert noch nicht mit Server-Komponenten und kann nur in Client-Komponenten 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 einmal ausführen, nachdem das Skript fertig geladen wurde, 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]))
        }}
      />
    </>
  )
}

`onReady`

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

Einige Drittanbieter-Skripte erfordern, dass Benutzer JavaScript-Code nach dem Laden des Skripts und bei jedem erneuten Mounten der Komponente (z.B. nach einer Routennavigation) ausführen. Sie können Code nach dem Lade-Ereignis des Skripts beim ersten Laden und dann nach jedem nachfolgenden erneuten Mounten der Komponente mit der onReady-Eigenschaft ausführen.

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

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

Warnung: onError funktioniert noch nicht mit Server-Komponenten und kann nur in Client-Komponenten 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:

'use client'

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.