Vorschau von Inhalten mit dem Preview Mode in Next.js

Hinweis: Diese Funktion wurde durch den Draft Mode ersetzt.

In der Pages-Dokumentation und der Data Fetching-Dokumentation haben wir besprochen, wie Sie eine Seite zur Build-Zeit (Static Generation) mit getStaticProps und getStaticPaths vorrendern können.

Static Generation ist nützlich, wenn Ihre Seiten Daten von einem Headless CMS abrufen. Es ist jedoch nicht ideal, wenn Sie einen Entwurf in Ihrem Headless CMS schreiben und diesen Entwurf sofort auf Ihrer Seite vorschauen möchten. In diesem Fall möchten Sie, dass Next.js diese Seiten zur Anfragezeit statt zur Build-Zeit rendert und den Entwurfsinhalt statt des veröffentlichten Inhalts abruft. Sie möchten, dass Next.js die Static Generation nur für diesen speziellen Fall umgeht.

Next.js verfügt über eine Funktion namens Preview Mode, die dieses Problem löst. Hier finden Sie Anleitungen zur Verwendung.

Schritt 1: Erstellen und Zugreifen auf eine Preview-API-Route

Werfen Sie zunächst einen Blick in die API Routes-Dokumentation, wenn Sie mit Next.js API Routes nicht vertraut sind.

Erstellen Sie zunächst eine Preview-API-Route. Sie kann beliebig benannt werden - z.B. pages/api/preview.js (oder .ts bei Verwendung von TypeScript).

In dieser API-Route müssen Sie setPreviewData auf das Response-Objekt aufrufen. Das Argument für setPreviewData sollte ein Objekt sein und kann von getStaticProps verwendet werden (mehr dazu später). Für jetzt verwenden wir {}.

export default function handler(req, res) {
  // ...
  res.setPreviewData({})
  // ...
}

res.setPreviewData setzt einige Cookies im Browser, die den Preview Mode aktivieren. Jede Anfrage an Next.js, die diese Cookies enthält, wird als Preview Mode betrachtet, und das Verhalten für statisch generierte Seiten ändert sich (mehr dazu später).

Sie können dies manuell testen, indem Sie eine API-Route wie unten erstellen und manuell über Ihren Browser darauf zugreifen:

// Einfaches Beispiel zum manuellen Testen über Ihren Browser.
export default function handler(req, res) {
  res.setPreviewData({})
  res.end('Preview mode enabled')
}

Wenn Sie die Entwicklertools Ihres Browsers öffnen und /api/preview aufrufen, werden Sie feststellen, dass die Cookies __prerender_bypass und __next_preview_data für diese Anfrage gesetzt werden.

Sicherer Zugriff von Ihrem Headless CMS

In der Praxis möchten Sie diese API-Route sicher von Ihrem Headless CMS aus aufrufen. Die genauen Schritte hängen davon ab, welches Headless CMS Sie verwenden, aber hier sind einige allgemeine Schritte, die Sie unternehmen könnten.

Diese Schritte setzen voraus, dass Ihr Headless CMS das Setzen von benutzerdefinierten Vorschau-URLs unterstützt. Falls nicht, können Sie diese Methode dennoch verwenden, um Ihre Vorschau-URLs zu sichern, aber Sie müssen die Vorschau-URL manuell erstellen und darauf zugreifen.

Erstens sollten Sie einen geheimen Token-String mit einem Token-Generator Ihrer Wahl erstellen. Dieses Geheimnis sollte nur Ihrer Next.js-App und Ihrem Headless CMS bekannt sein. Dies verhindert, dass Personen, die keinen Zugriff auf Ihr CMS haben, auf Vorschau-URLs zugreifen können.

Zweitens, wenn Ihr Headless CMS das Setzen von benutzerdefinierten Vorschau-URLs unterstützt, geben Sie Folgendes als Vorschau-URL an. Dies setzt voraus, dass sich Ihre Preview-API-Route unter pages/api/preview.js befindet.

https://<your-site>/api/preview?secret=<token>&slug=<path>

• <your-site> sollte Ihre Bereitstellungsdomäne sein.
• <token> sollte durch den generierten geheimen Token ersetzt werden.
• <path> sollte der Pfad der Seite sein, die Sie in der Vorschau anzeigen möchten. Wenn Sie /posts/foo in der Vorschau anzeigen möchten, sollten Sie &slug=/posts/foo verwenden.

Ihr Headless CMS erlaubt möglicherweise die Verwendung einer Variablen in der Vorschau-URL, sodass <path> dynamisch basierend auf den Daten des CMS gesetzt werden kann, z.B.: &slug=/posts/{entry.fields.slug}

Schließlich in der Preview-API-Route:

• Überprüfen Sie, ob der geheime Token übereinstimmt und ob der slug-Parameter vorhanden ist (falls nicht, sollte die Anfrage fehlschlagen).
• Rufen Sie res.setPreviewData auf.
• Leiten Sie dann den Browser zu dem durch slug angegebenen Pfad um (das folgende Beispiel verwendet eine 307-Umleitung).

export default async (req, res) => {
  // Überprüfen des geheimen Tokens und der Parameter
  // Dieser Token sollte nur dieser API-Route und dem CMS bekannt sein
  if (req.query.secret !== 'MY_SECRET_TOKEN' || !req.query.slug) {
    return res.status(401).json({ message: 'Invalid token' })
  }

  // Abrufen des Headless CMS, um zu überprüfen, ob der angegebene `slug` existiert
  // getPostBySlug würde die erforderliche Abruflogik für das Headless CMS implementieren
  const post = await getPostBySlug(req.query.slug)

  // Wenn der slug nicht existiert, verhindern Sie die Aktivierung des Preview Mode
  if (!post) {
    return res.status(401).json({ message: 'Invalid slug' })
  }

  // Aktivieren des Preview Mode durch Setzen der Cookies
  res.setPreviewData({})

  // Umleitung zum Pfad des abgerufenen Beitrags
  // Wir leiten nicht zu req.query.slug um, da dies zu Open-Redirect-Schwachstellen führen könnte
  res.redirect(post.slug)
}

Wenn dies erfolgreich ist, wird der Browser zu dem gewünschten Pfad umgeleitet, wobei die Preview-Mode-Cookies gesetzt sind.

Schritt 2: Aktualisieren von getStaticProps

Der nächste Schritt besteht darin, getStaticProps für den Preview Mode anzupassen.

Wenn Sie eine Seite anfordern, die getStaticProps enthält, während die Preview-Mode-Cookies gesetzt sind (über res.setPreviewData), wird getStaticProps zur Anfragezeit (statt zur Build-Zeit) aufgerufen.

Darüber hinaus wird es mit einem context-Objekt aufgerufen, bei dem:

• context.preview true sein wird.
• context.previewData identisch mit dem für setPreviewData verwendeten Argument sein wird.

export async function getStaticProps(context) {
  // Wenn Sie diese Seite mit den gesetzten Preview-Mode-Cookies anfordern:
  //
  // - context.preview wird true sein
  // - context.previewData wird identisch mit
  //   dem für `setPreviewData` verwendeten Argument sein.
}

Wir haben res.setPreviewData({}) in der Preview-API-Route verwendet, daher wird context.previewData {} sein. Sie können dies verwenden, um bei Bedarf Sitzungsinformationen von der Preview-API-Route an getStaticProps zu übergeben.

Wenn Sie auch getStaticPaths verwenden, ist context.params ebenfalls verfügbar.

Vorschaudaten abrufen

Sie können getStaticProps anpassen, um basierend auf context.preview und/oder context.previewData unterschiedliche Daten abzurufen.

Beispielsweise könnte Ihr Headless CMS einen anderen API-Endpunkt für Entwurfsbeiträge haben. In diesem Fall können Sie context.preview verwenden, um die API-Endpunkt-URL wie folgt zu modifizieren:

export async function getStaticProps(context) {
  // Wenn context.preview true ist, "/preview" an den API-Endpunkt anhängen
  // um Entwurfsdaten statt veröffentlichter Daten anzufordern. Dies variiert
  // je nach verwendetem Headless CMS.
  const res = await fetch(`https://.../${context.preview ? 'preview' : ''}`)
  // ...
}

Das war's! Wenn Sie die Preview-API-Route (mit secret und slug) von Ihrem Headless CMS oder manuell aufrufen, sollten Sie nun den Vorschauinhalt sehen können. Und wenn Sie Ihren Entwurf aktualisieren, ohne ihn zu veröffentlichen, sollten Sie den Entwurf in der Vorschau sehen können.

Setzen Sie dies als Vorschau-URL in Ihrem Headless CMS oder rufen Sie sie manuell auf, und Sie sollten die Vorschau sehen können.

https://<your-site>/api/preview?secret=<token>&slug=<path>

Weitere Details

Gut zu wissen: Während des Renderings stellt next/router ein isPreview-Flag bereit, siehe die Router-Objekt-Dokumentation für weitere Informationen.

Dauer des Preview Mode festlegen

setPreviewData akzeptiert einen optionalen zweiten Parameter, der ein Optionsobjekt sein sollte. Es akzeptiert die folgenden Schlüssel:

• maxAge: Gibt die Anzahl (in Sekunden) an, wie lange die Preview-Sitzung dauern soll.
• path: Gibt den Pfad an, unter dem der Cookie gelten soll. Standardmäßig /, wodurch der Preview Mode für alle Pfade aktiviert wird.

setPreviewData(data, {
  maxAge: 60 * 60, // Die Preview-Mode-Cookies laufen nach 1 Stunde ab
  path: '/about', // Die Preview-Mode-Cookies gelten für Pfade mit /about
})

Preview-Mode-Cookies löschen

Standardmäßig ist für Preview-Mode-Cookies kein Ablaufdatum festgelegt, sodass die Preview-Sitzung endet, wenn der Browser geschlossen wird.

Um die Preview-Mode-Cookies manuell zu löschen, erstellen Sie eine API-Route, die clearPreviewData() aufruft:

export default function handler(req, res) {
  res.clearPreviewData({})
}

Senden Sie dann eine Anfrage an /api/clear-preview-mode-cookies, um die API-Route aufzurufen. Wenn Sie diese Route mit next/link aufrufen, müssen Sie prefetch={false} übergeben, um zu verhindern, dass clearPreviewData während des Link-Prefetchings aufgerufen wird.

Wenn in dem setPreviewData-Aufruf ein Pfad angegeben wurde, müssen Sie denselben Pfad an clearPreviewData übergeben:

export default function handler(req, res) {
  const { path } = req.query

  res.clearPreviewData({ path })
}

Größenbeschränkungen für previewData

Sie können ein Objekt an setPreviewData übergeben und es in getStaticProps verfügbar machen. Da die Daten jedoch in einem Cookie gespeichert werden, gibt es eine Größenbeschränkung. Derzeit sind Preview-Daten auf 2KB begrenzt.

Funktioniert mit getServerSideProps

Der Preview Mode funktioniert auch mit getServerSideProps. Er ist ebenfalls im context-Objekt mit preview und previewData verfügbar.

Gut zu wissen: Sie sollten den Cache-Control-Header nicht setzen, wenn Sie den Preview Mode verwenden, da er nicht umgangen werden kann. Stattdessen empfehlen wir die Verwendung von ISR.

Funktioniert mit API Routes

API Routes haben Zugriff auf preview und previewData unter dem Request-Objekt. Zum Beispiel:

export default function myApiRoute(req, res) {
  const isPreview = req.preview
  const previewData = req.previewData
  // ...
}

Einzigartig pro next build

Sowohl der Bypass-Cookie-Wert als auch der private Schlüssel zur Verschlüsselung der previewData ändern sich, wenn next build abgeschlossen ist. Dies stellt sicher, dass der Bypass-Cookie nicht erraten werden kann.

Gut zu wissen: Um den Preview Mode lokal über HTTP zu testen, muss Ihr Browser Cookies von Drittanbietern und den Zugriff auf den lokalen Speicher zulassen.