Vorschaumodus

Hinweis: Dieses Feature wird durch den Entwurfsmodus ersetzt.

In der Seiten-Dokumentation und der Daten-Fetching-Dokumentation haben wir besprochen, wie man eine Seite zur Bauzeit mit Statischer Generierung unter Verwendung von getStaticProps und getStaticPaths vorab rendert.

Statische Generierung ist nützlich, wenn Ihre Seiten Daten von einem Headless CMS abrufen. Allerdings ist es nicht ideal, wenn Sie einen Entwurf in Ihrem Headless CMS erstellen und den Entwurf sofort auf Ihrer Seite vorschauen möchten. Sie würden wollen, dass Next.js diese Seiten zur Anforderungszeit anstatt zur Bauzeit rendert und den Entwurfsinhalt anstelle des veröffentlichten Inhalts abruft. Sie würden wollen, dass Next.js die Statische Generierung nur für diesen speziellen Fall umgeht.

Next.js bietet eine Funktion namens Vorschaumodus, die dieses Problem löst. Hier sind Anweisungen zur Verwendung.

Schritt 1: Erstellen und Zugriff auf eine Vorschau-API-Route

Werfen Sie zuerst einen Blick in die API-Routen-Dokumentation, wenn Sie mit Next.js-API-Routen nicht vertraut sind.

Erstellen Sie zunächst eine Vorschau-API-Route. Sie kann einen beliebigen Namen haben - z.B. pages/api/preview.js (oder .ts bei Verwendung von TypeScript).

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

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

res.setPreviewData setzt einige Cookies im Browser, die den Vorschaumodus aktivieren. Alle Anfragen an Next.js, die diese Cookies enthalten, werden als Vorschaumodus 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 sie manuell in Ihrem Browser aufrufen:

// einfaches Beispiel zum manuellen Testen über Ihren Browser
export default function handler(req, res) {
  res.setPreviewData({})
  res.end('Vorschaumodus aktiviert')
}

Wenn Sie die Entwicklertools Ihres Browsers öffnen und /api/preview besuchen, werden Sie bemerken, dass die Cookies __prerender_bypass und __next_preview_data bei dieser Anfrage gesetzt werden.

Sicherer Zugriff von Ihrem Headless CMS

In der Praxis würden Sie diese API-Route sicher von Ihrem Headless CMS aus aufrufen wollen. Die spezifischen Schritte variieren je nach verwendetem Headless CMS, aber hier sind einige übliche Schritte.

Diese Schritte gehen davon aus, dass das verwendete Headless CMS das Setzen von benutzerdefinierten Vorschau-URLs unterstützt. Wenn nicht, können Sie diese Methode weiterhin zum Sichern Ihrer Vorschau-URLs verwenden, müssen die Vorschau-URL aber manuell konstruieren und aufrufen.

Erstens sollten Sie einen geheimen Token-String mithilfe eines Tokengenerators Ihrer Wahl erstellen. Dieses Geheimnis sollte nur von Ihrer Next.js-App und Ihrem Headless CMS bekannt sein. Dieses Geheimnis verhindert, dass Personen ohne Zugriff auf Ihr CMS auf Vorschau-URLs zugreifen.

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

https://<ihre-website>/api/preview?secret=<token>&slug=<pfad>

• <ihre-website> sollte Ihre Bereitstellungs-Domain sein.
• <token> sollte durch den generierten geheimen Token ersetzt werden.
• <pfad> sollte der Pfad für die Seite sein, die Sie vorschauen möchten. Wenn Sie /posts/foo vorschauen möchten, verwenden Sie &slug=/posts/foo.

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

Schließlich in der Vorschau-API-Route:

• Überprüfen Sie, ob das Geheimnis übereinstimmt und der slug-Parameter existiert (wenn nicht, sollte die Anfrage fehlschlagen).
• Rufen Sie res.setPreviewData auf.
• Leiten Sie dann den Browser zum angegebenen Pfad um. (Das folgende Beispiel verwendet eine 307-Weiterleitung).

export default async (req, res) => {
  // Geheimnis und nächste Parameter prüfen
  // Dieses Geheimnis 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: 'Ungültiges Token' })
  }
 
  // Headless CMS abrufen, um zu prüfen, ob der angegebene `slug` existiert
  // getPostBySlug würde die erforderliche Abruf-Logik für das Headless CMS implementieren
  const post = await getPostBySlug(req.query.slug)
 
  // Wenn der Slug nicht existiert, Vorschaumodus verhindern
  if (!post) {
    return res.status(401).json({ message: 'Ungültiger Slug' })
  }
 
  // Vorschaumodus aktivieren durch Setzen der Cookies
  res.setPreviewData({})
 
  // Zum Pfad des abgerufenen Beitrags weiterleiten
  // Wir leiten nicht zu req.query.slug weiter, da dies zu offenen Weiterleitungs-Schwachstellen führen könnte
  res.redirect(post.slug)
}

Bei Erfolg wird der Browser zum Pfad weitergeleitet, den Sie vorschauen möchten, wobei die Vorschaumodus-Cookies gesetzt werden.

Schritt 2: getStaticProps aktualisieren

Der nächste Schritt ist es, getStaticProps zu aktualisieren, um den Vorschaumodus zu unterstützen.

Wenn Sie eine Seite anfordern, die getStaticProps mit den Vorschaumodus-Cookies hat (über res.setPreviewData), wird getStaticProps zum Zeitpunkt der Anfrage aufgerufen (anstatt zur Erstellungszeit).

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

• context.preview true sein wird.
• context.previewData das Gleiche sein wird wie das Argument, das für setPreviewData verwendet wurde.

export async function getStaticProps(context) {
  // Wenn Sie diese Seite mit den Vorschaumodus-Cookies anfordern:
  //
  // - context.preview wird true sein
  // - context.previewData wird das Gleiche sein wie
  //   das Argument, das für `setPreviewData` verwendet wurde.
}

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

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

Vorschadaten abrufen

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

Zum Beispiel 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 zu modifizieren, wie unten gezeigt:

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

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

Legen Sie dies als Vorschau-URL in Ihrem Headless-CMS fest oder greifen Sie manuell zu, und Sie sollten die Vorschau sehen können.

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

Weitere Details

Hinweis: Während des Renderns stellt next/router ein isPreview-Flag bereit, weitere Informationen finden Sie in der Router-Objekt-Dokumentation.

Dauer des Vorschaumodus festlegen

setPreviewData akzeptiert einen optionalen zweiten Parameter, bei dem es sich um ein Optionsobjekt handeln sollte. Es akzeptiert folgende Schlüssel:

• maxAge: Gibt die Anzahl der Sekunden an, für die die Vorschau-Sitzung gelten soll.
• path: Gibt den Pfad an, unter dem das Cookie angewendet werden soll. Standardmäßig /, wodurch der Vorschaumodus für alle Pfade aktiviert wird.

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

Vorschaumodus-Cookies löschen

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

Um die Vorschaumodus-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-Prefetching aufgerufen wird.

Wenn ein Pfad im setPreviewData-Aufruf 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 Vorschadaten auf 2 KB begrenzt.

Funktioniert mit getServerSideProps

Der Vorschaumodus funktioniert auch bei getServerSideProps. Er wird ebenfalls im context-Objekt mit preview und previewData verfügbar sein.

Hinweis: Sie sollten den Cache-Control-Header nicht verwenden, wenn Sie den Vorschaumodus nutzen, da er nicht umgangen werden kann. Stattdessen empfehlen wir ISR.

Funktioniert mit API-Routen

API-Routen haben Zugriff auf preview und previewData unter dem Anfrageobjekt. Beispiel:

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

Eindeutig pro next build

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

Hinweis: Um den Vorschaumodus lokal über HTTP zu testen, muss Ihr Browser Drittanbieter-Cookies und lokalen Speicherzugriff erlauben.