getStaticProps

Wenn Sie eine Funktion namens getStaticProps (Static Site Generation) aus einer Seite exportieren, wird Next.js diese Seite zur Build-Zeit mit den von getStaticProps zurückgegebenen Props vorrendern.

import type { InferGetStaticPropsType, GetStaticProps } from 'next'

type Repo = {
  name: string
  stargazers_count: number
}

export const getStaticProps = (async (context) => {
  const res = await fetch('https://api.github.com/repos/vercel/next.js')
  const repo = await res.json()
  return { props: { repo } }
}) satisfies GetStaticProps<{
  repo: Repo
}>

export default function Page({
  repo,
}: InferGetStaticPropsType<typeof getStaticProps>) {
  return repo.stargazers_count
}

export async function getStaticProps() {
  const res = await fetch('https://api.github.com/repos/vercel/next.js')
  const repo = await res.json()
  return { props: { repo } }
}

export default function Page({ repo }) {
  return repo.stargazers_count
}

Hinweis: Unabhängig vom Rendering-Typ werden alle props an die Seitenkomponente übergeben und können clientseitig im initialen HTML eingesehen werden. Dies dient dazu, die Seite korrekt hydrieren zu können. Stellen Sie sicher, dass Sie keine sensiblen Informationen in props übergeben, die nicht clientseitig verfügbar sein sollten.

Die getStaticProps-API-Referenz deckt alle Parameter und Props ab, die mit getStaticProps verwendet werden können.

Wann sollte ich getStaticProps verwenden?

Sie sollten getStaticProps verwenden, wenn:

• Die zum Rendern der Seite benötigten Daten zum Build-Zeitpunkt vor einer Benutzeranfrage verfügbar sind
• Die Daten von einem Headless-CMS stammen
• Die Seite für SEO-Zwecke vorgerendert werden muss und sehr schnell sein soll – getStaticProps generiert HTML- und JSON-Dateien, die beide von einem CDN zwischengespeichert werden können
• Die Daten öffentlich zwischengespeichert werden können (nicht benutzerspezifisch). Diese Bedingung kann in bestimmten Situationen durch Verwendung eines Middleware zur Pfadumleitung umgangen werden.

Wann wird getStaticProps ausgeführt

getStaticProps läuft immer auf dem Server und nie auf dem Client. Sie können überprüfen, dass der Code innerhalb von getStaticProps aus dem Client-Bundle entfernt wird, mit diesem Tool.

• getStaticProps wird immer während next build ausgeführt
• getStaticProps läuft im Hintergrund bei Verwendung von fallback: true
• getStaticProps wird vor dem initialen Rendering aufgerufen bei Verwendung von fallback: blocking
• getStaticProps läuft im Hintergrund bei Verwendung von revalidate
• getStaticProps läuft bedarfsgesteuert im Hintergrund bei Verwendung von revalidate()

In Kombination mit Inkrementeller Statischer Regenerierung wird getStaticProps im Hintergrund ausgeführt, während die veraltete Seite neu validiert wird, und die aktualisierte Seite an den Browser gesendet wird.

getStaticProps hat keinen Zugriff auf die eingehende Anfrage (wie Query-Parameter oder HTTP-Header), da es statisches HTML generiert. Wenn Sie Zugriff auf die Anfrage für Ihre Seite benötigen, sollten Sie zusätzlich zu getStaticProps eine Middleware verwenden.

Datenabruf aus einem CMS mit getStaticProps

Das folgende Beispiel zeigt, wie Sie eine Liste von Blog-Beiträgen aus einem CMS abrufen können.

// posts werden zur Build-Zeit durch getStaticProps() befüllt
export default function Blog({ posts }) {
  return (
    <ul>
      {posts.map((post) => (
        <li>{post.title}</li>
      ))}
    </ul>
  )
}

// Diese Funktion wird zur Build-Zeit serverseitig aufgerufen.
// Sie wird nicht clientseitig aufgerufen, sodass Sie sogar
// direkte Datenbankabfragen durchführen können.
export async function getStaticProps() {
  // Rufen Sie einen externen API-Endpunkt ab, um Posts zu erhalten.
  // Sie können jede Datenabruf-Bibliothek verwenden
  const res = await fetch('https://.../posts')
  const posts = await res.json()

  // Durch die Rückgabe von { props: { posts } } erhält die Blog-Komponente
  // `posts` als Prop zur Build-Zeit
  return {
    props: {
      posts,
    },
  }
}

// posts werden zur Build-Zeit durch getStaticProps() befüllt
export default function Blog({ posts }) {
  return (
    <ul>
      {posts.map((post) => (
        <li>{post.title}</li>
      ))}
    </ul>
  )
}

// Diese Funktion wird zur Build-Zeit serverseitig aufgerufen.
// Sie wird nicht clientseitig aufgerufen, sodass Sie sogar
// direkte Datenbankabfragen durchführen können.
export async function getStaticProps() {
  // Rufen Sie einen externen API-Endpunkt ab, um Posts zu erhalten.
  // Sie können jede Datenabruf-Bibliothek verwenden
  const res = await fetch('https://.../posts')
  const posts = await res.json()

  // Durch die Rückgabe von { props: { posts } } erhält die Blog-Komponente
  // `posts` als Prop zur Build-Zeit
  return {
    props: {
      posts,
    },
  }
}

Die getStaticProps-API-Referenz deckt alle Parameter und Props ab, die mit getStaticProps verwendet werden können.

Serverseitigen Code direkt schreiben

Da getStaticProps nur serverseitig läuft, wird es nie clientseitig ausgeführt. Es wird nicht einmal im JS-Bundle für den Browser enthalten sein, sodass Sie direkte Datenbankabfragen schreiben können, ohne dass diese an Browser gesendet werden.

Das bedeutet, dass Sie anstelle des Abrufs einer API-Route von getStaticProps (die selbst Daten von einer externen Quelle abruft), den serverseitigen Code direkt in getStaticProps schreiben können.

Betrachten Sie das folgende Beispiel. Eine API-Route wird verwendet, um Daten von einem CMS abzurufen. Diese API-Route wird dann direkt von getStaticProps aufgerufen. Dies erzeugt einen zusätzlichen Aufruf und reduziert die Leistung. Stattdessen kann die Logik für den Datenabruf aus dem CMS durch Verwendung eines lib/-Verzeichnisses gemeinsam genutzt werden. Dann kann sie mit getStaticProps geteilt werden.

// Die folgende Funktion wird gemeinsam
// mit getStaticProps und API-Routen
// aus einem `lib/`-Verzeichnis genutzt
export async function loadPosts() {
  // Rufen Sie einen externen API-Endpunkt ab, um Posts zu erhalten
  const res = await fetch('https://.../posts/')
  const data = await res.json()

  return data
}

// pages/blog.js
import { loadPosts } from '../lib/load-posts'

// Diese Funktion läuft nur serverseitig
export async function getStaticProps() {
  // Anstatt Ihre `/api`-Route abzurufen, können Sie dieselbe
  // Funktion direkt in `getStaticProps` aufrufen
  const posts = await loadPosts()

  // Zurückgegebene Props werden an die Seitenkomponente übergeben
  return { props: { posts } }
}

Alternativ können Sie, wenn Sie keine API-Routen zum Datenabruf verwenden, die fetch()-API direkt in getStaticProps verwenden.

Um zu überprüfen, was Next.js aus dem Client-Bundle entfernt, können Sie das next-code-elimination-Tool verwenden.

Statische Generierung von HTML und JSON

Wenn eine Seite mit getStaticProps zur Build-Zeit vorgerendert wird, generiert Next.js neben der HTML-Datei der Seite auch eine JSON-Datei mit dem Ergebnis der Ausführung von getStaticProps.

Diese JSON-Datei wird beim clientseitigen Routing über next/link oder next/router verwendet. Wenn Sie zu einer Seite navigieren, die mit getStaticProps vorgerendert wurde, ruft Next.js diese JSON-Datei (die zur Build-Zeit vorberechnet wurde) ab und verwendet sie als Props für die Seitenkomponente. Das bedeutet, dass clientseitige Seitenübergänge nicht getStaticProps aufrufen, da nur das exportierte JSON verwendet wird.

Bei Verwendung der Inkrementellen Statischen Generierung wird getStaticProps im Hintergrund ausgeführt, um das für clientseitige Navigation benötigte JSON zu generieren. Sie können dies in Form mehrerer Anfragen für dieselbe Seite beobachten, jedoch ist dies beabsichtigt und hat keine Auswirkungen auf die Endbenutzerleistung.

Wo kann ich getStaticProps verwenden

getStaticProps kann nur von einer Seite exportiert werden. Sie können es nicht von Nicht-Seiten-Dateien, _app, _document oder _error exportieren.

Einer der Gründe für diese Einschränkung ist, dass React alle benötigten Daten vor dem Rendern der Seite benötigt.

Außerdem müssen Sie getStaticProps als eigenständige Funktion exportieren – es wird nicht funktionieren, wenn Sie getStaticProps als Eigenschaft der Seitenkomponente hinzufügen.

Gut zu wissen: Wenn Sie eine benutzerdefinierte App erstellt haben, stellen Sie sicher, dass Sie die pageProps wie im verlinkten Dokument gezeigt an die Seitenkomponente übergeben, da die Props sonst leer sein werden.

Läuft bei jeder Anfrage in der Entwicklung

In der Entwicklung (next dev) wird getStaticProps bei jeder Anfrage aufgerufen.

Vorschaumodus

Sie können die statische Generierung vorübergehend umgehen und die Seite zur Anfragezeit statt zur Build-Zeit rendern, indem Sie den Vorschaumodus verwenden. Beispielsweise könnten Sie ein Headless-CMS verwenden und Entwürfe vor der Veröffentlichung ansehen wollen.