<Script>

Diese API-Referenz hilft Ihnen zu verstehen, wie Sie die Eigenschaften der Script-Komponente verwenden können. Informationen zu Funktionen und Verwendung finden Sie auf der Seite Optimieren von Skripten.

app/dashboard/page.tsx

TypeScript

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

Eigenschaften

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

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

Erforderliche Eigenschaften

Die <Script /> Komponente erfordert die folgenden 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, es sei denn, es wird ein Inline-Skript verwendet.

Optionale Eigenschaften

Die <Script /> Komponente akzeptiert zusätzlich zu den erforderlichen Eigenschaften noch weitere.

`strategy`

Die Ladestrategie des Skripts. Es gibt vier verschiedene Strategien, die verwendet werden können:

beforeInteractive: Laden vor jedem Next.js-Code und vor jeder Seitenhydrierung.
afterInteractive: (Standard) Früh laden, aber nach einer teilweisen Hydration auf der Seite.
lazyOnload: Während der Leerlaufzeit des Browsers laden.
worker: (experimentell) In einem Web Worker laden.

`beforeInteractive`

Skripte, die mit der beforeInteractive-Strategie geladen werden, werden in die ursprüngliche HTML-Datei vom Server eingefügt, vor jedem Next.js-Modul heruntergeladen und in der Reihenfolge ihrer Platzierung vor jeder Hydration ausgeführt.

Skripte, die mit dieser Strategie gekennzeichnet sind, werden vorab geladen und abgerufen, bevor Code von Erstanbietern, aber ihre Ausführung blockiert die Seitenhydrierung nicht.

beforeInteractive-Skripte müssen im Root-Layout (app/layout.tsx) platziert werden und sind dafür konzipiert, Skripte zu laden, die von der gesamten Website benötigt werden (d.h. das Skript wird geladen, wenn eine beliebige Seite in der Anwendung serverseitig geladen wurde).

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

app/layout.tsx

TypeScript

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

Hinweis: Skripte mit beforeInteractive werden unabhängig von ihrer Platzierung in der Komponente immer innerhalb des head des HTML-Dokuments eingefügt.

Einige Beispiele für Skripte, die so schnell wie möglich mit beforeInteractive geladen werden sollten:

Bot-Erkennungssysteme
Cookie-Einwilligungsmanager

`afterInteractive`

Skripte, die die afterInteractive-Strategie verwenden, werden clientseitig in die HTML-Datei eingefügt und laden nach einer teilweisen (oder vollständigen) Hydration auf der Seite. Dies ist die Standardstrategie der Script-Komponente und sollte für jedes Skript verwendet werden, das so früh wie möglich, aber nicht vor dem Code von Erstanbietern 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 Seitengruppe) 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" />
    </>
  )
}

Einige Beispiele für Skripte, die gut für afterInteractive geeignet sind:

Tag-Manager
Analysen

`lazyOnload`

Skripte, die die lazyOnload-Strategie verwenden, werden während der Leerlaufzeit des Browsers clientseitig in die HTML-Datei eingefügt und laden, nachdem alle Ressourcen auf der Seite abgerufen wurden. Diese Strategie sollte für Hintergrund- oder Skripte mit niedriger Priorität 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 Seitengruppe) 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. Verwenden Sie sie mit Vorsicht.

Skripte, die die worker-Strategie verwenden, werden in einen Web Worker ausgelagert, um den Hauptthread zu entlasten und sicherzustellen, dass nur kritische Ressourcen von Erstanbietern verarbeitet werden. Während diese Strategie für jedes Skript verwendet werden kann, handelt es sich um einen fortgeschrittenen Anwendungsfall, der nicht alle Skripte von Drittanbietern 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:

pages/home.tsx

TypeScript

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

`onLoad`

Achtung: onLoad funktioniert derzeit noch nicht mit Server-Komponenten und kann nur in Client-Komponenten verwendet werden. Zudem kann onLoad nicht mit beforeInteractive verwendet werden – erwägen Sie stattdessen die Nutzung von onReady.

Einige Skripte von Drittanbietern erfordern, dass Benutzer JavaScript-Code ausführen, sobald das Skript fertig geladen ist, um Inhalte zu instanziieren oder eine Funktion aufzurufen. Wenn Sie ein Skript mit afterInteractive oder lazyOnload als Ladestrategien laden, können Sie Code nach dem Laden mithilfe der onLoad-Eigenschaft ausführen.

Hier ist ein Beispiel für die Ausführung einer Lodash-Methode, nachdem die Bibliothek geladen wurde.

app/page.tsx

TypeScript

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

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

Einige Skripte von Drittanbietern erfordern, dass Benutzer JavaScript-Code ausführen, nachdem das Skript geladen ist, und jedes Mal, wenn die Komponente gemountet wird (z.B. nach einer Routennavigation). Sie können Code nach dem Laden des Skripts ausführen, wenn es erstmals geladen wird, und dann nach jedem erneuten Mounten der Komponente mithilfe der onReady-Eigenschaft ausführen.

Hier ist ein Beispiel, wie man eine Google Maps JS-Einbettung jedes Mal neu instanziiert, wenn die Komponente gemountet wird:

app/page.tsx

TypeScript

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

Achtung: onError funktioniert derzeit noch nicht mit Server-Komponenten und kann nur in Client-Komponenten verwendet werden. onError kann nicht mit der beforeInteractive-Ladestrategie verwendet werden.

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

app/page.tsx

TypeScript

'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 modifiziert, um `app` zu unterstützen.
`v12.2.4`	`onReady`-Eigenschaft hinzugefügt.
`v12.2.2`	Erlaubt `next/script` mit `beforeInteractive` in `_document`.
`v11.0.0`	`next/script` eingeführt.