Vercel

Die Vercel-App von Contentful hilft Ihrem Team, auf einfache Weise funktionierende Vorschau-Umgebungen für Ihre Next.js-Anwendung zu konfigurieren und zu warten, die auf Vercel gehostet und von Contentful unterstützt werden.

Mit ein wenig Konfiguration im Voraus können Ihre Content-Ersteller*innen eine Vorschau der Content-Änderungen anzeigen, bevor sie diese direkt im „Side-by-Side“-Vorschau-Editor von Contentful veröffentlichen. Mit etwas mehr Aufwand kann Ihr Team auch das Live-Vorschau-SDK von Contentful implementieren, das eine noch leistungsfähigere Reihe von Vorschaufunktionen wie Live-Updates und direkte Bearbeitung ermöglicht.

• Nach der Installation und Konfiguration ermöglicht die Vercel-App Content-Vorschauen im „Side-by-Side“-Vorschau-Editor von Contentful für jeden von Ihnen angegebenen Contenttyp.

• Die Vercel-App bietet auch gemeinsam nutzbare Vorschau-URLs, auf die Ihre Teammitglieder zugreifen können, die möglicherweise keinen direkten Zugriff auf Ihr Vercel-Projekt haben.

• Die Vercel-App vereinfacht den Prozess zum Konfigurieren und Verwalten von funktionierenden Vorschau-URLs, die mit den Vorschaufunktionen von Contentful kompatibel sind, erheblich.

Um die Vercel-App einzurichten, benötigen Sie:

• Space-Admin-Zugriff auf den Contentful Space, in dem Sie die App installieren

• Projekt-Admin-Zugriff auf das Vercel-Projekt, in dem Ihre mit Contentful verbundene Next.js-Anwendung bereitgestellt wird

• Eine/n Entwickler*in aus Ihrem Team, der/die Ihnen hilft, Ihre Next.js-Anwendung an die Vorschaufunktionen von Contentful anzupassen

Hinweis: In diesem Leitfaden wird davon ausgegangen, dass Sie bereits über eine funktionierende Next.js-Anwendung verfügen, die auf Vercel bereitgestellt und mit einem Contentful Space verbunden ist. Wenn Sie ein Projekt von Grund auf neu starten, können Sie eine Anleitung für den Einstieg lesen, um schnell ein neues Projekt zu starten.

Bevor Ihr Team überhaupt mit der Verwendung der Vercel-App beginnen kann, muss Ihre Next.js-Anwendung so eingerichtet werden, dass sie den „Entwurfsmodus“ unterstützt. Der Entwurfsmodus ist eine Next.js-Funktion, mit der Ihr Team zwischen der Anzeige von Seiten auf Ihrer Website im „Produktionsmodus“ (d. h. wie Ihre Endbenutzer*innen sie sehen würden) und der Anzeige von Seiten im „Vorschau-Modus“ (wie Ihre Content-Ersteller*innen sie beim Bearbeiten von unveröffentlichtem Content sehen möchten) wechseln kann.

Sie müssen entweder selbst Entwickler*in sein oder die Hilfe eines Entwicklers/einer Entwicklerin für Ihr Projekt in Anspruch nehmen, um die Änderungen in Ihrer Codebasis vorzunehmen, die erforderlich sind, um sowohl die Aktivierung des Entwurfsmodus als auch die Anzeige von Vorschau-Content zu unterstützen, wenn der Entwurfsmodus aktiviert ist.

Dieser erste Schritt ist zwar nicht trivial, aber Contentful bietet einen Entwicklerleitfaden sowie Entwicklertools, um die Implementierung des Entwurfsmodus in Ihrem Projekt zu erleichtern. In diesem Leitfaden werden die folgenden wichtigen Themen ausführlich behandelt:

• Einrichten eines Routenhandlers, um den Entwurfsmodus zu aktivieren. Ihr/e Entwickler*in muss einen „Routenhandler“ installieren, den die Vercel-App verwendet, um Vorschaufunktionen in Ihrer Anwendung sicher zu aktivieren, wenn Ihr Team das Vorschau-Tool von Contentful verwendet. Dies ist ein erforderlicher Schritt.

• <0><1>Hinzufügen der Unterstützung für den Entwurfsmodus in Ihrer Anwendung</1></0><1>.</1> Unsere Entwicklerdokumentation bietet Ihrem Entwickler/Ihrer Entwicklerin eine umfassendere Anleitung, wie der Entwurfsmodus in die Contentful API-Abfragen in Ihrer Anwendung integriert werden kann und wie die leistungsfähigeren Live-Vorschau-Funktionen von Contentful wie direkte Bearbeitung und Live-Updates implementiert werden können.

Hinweis: Ihr Team muss nicht alle Vorschaufunktionen von Contentful vollständig implementieren, um die Vercel-App nutzen zu können. Ihre Anwendung sollte jedoch die oben angegebenen Routenhandler-Anleitungen unterstützen und mindestens einige der Vorschaufunktionen von Contentful implementieren, bevor Sie mit dem nächsten Schritt fortfahren.

Die App kann entweder über den Contentful Marketplace oder in Ihrem Contentful Space installiert werden.

Konfigurieren des Zugriffs auf Vercel

Im ersten Schritt des App-Installationsprozesses müssen Sie ein „Vercel Access Token“ einfügen, das der Vercel-App Zugriff auf die Vercel-Projekte Ihres Teams gewährt.

So erhalten Sie ein Vercel Access Token, das Sie mit der App verwenden können:

• Befolgen Sie diese Anweisungen von Vercel, um ein Access Token zu erstellen. Benennen Sie das Token nach Ihren Wünschen.

• Wichtig: Sie müssen ein Team aus der Liste der Bereiche im Formular „Token erstellen“ auswählen. Wenn Sie Mitglied mehrerer Teams in Vercel sind, wählen Sie das Team aus, das das Vercel-Projekt enthält, mit dem Sie eine Verbindung herstellen möchten.

• Stellen Sie sicher, dass Sie „Kein Ablauf“ angeben. Andernfalls müssen Sie die App-Konfigurationsseite besuchen und Ihr Token regelmäßig neu generieren.

• Kopieren Sie den Token-Wert und fügen Sie ihn in das Feld „Vercel Access Token“ der Contentful App ein.

Wenn Sie erfolgreich ein gültiges Vercel Access Token erstellt und eingefügt haben, sollte eine Option zur Auswahl eines Projekts angezeigt werden.

Verbinden mit Ihrem Vercel-Projekt

Wählen Sie im Dropdown-Menü „Projekt“ ein Vercel-Projekt aus, mit dem Sie eine Verbindung herstellen möchten. Dies sollte das Projekt sein, mit dem der Contentful Space verbunden ist, in dem Sie die App installieren.

Als Nächstes müssen Sie die „Route“ in Ihrem Projekt angeben, die so konfiguriert ist, dass sie den Entwurfsmodus aktiviert. (Sie müssen mit Ihren Entwickler*innen zusammenarbeiten, um eine solche Route zu installieren, wie in Schritt 1 oben beschrieben.)

Hinweis: Wenn in der Dropdown-Liste mehrere Routen verfügbar sind und Sie sich nicht sicher sind, welche Sie auswählen sollen, sprechen Sie mit Ihrem Entwicklungsteam. Wenn Ihre Entwickler*innen unsere Anleitung befolgt haben, sollte die richtige Route „api/enable-draft“ oder ähnlich benannt sein.

Nachdem Sie sich erfolgreich mit Ihrem Vercel-Projekt verbunden haben, können Sie Vorschau-Umgebungen für bestimmte Contenttypen konfigurieren, die Ihre Content-Editor*innen in der Vorschau anzeigen können.

Die App selbst kümmert sich um die Bereitstellung einer Domain und anderer Elemente, die erforderlich sind, damit Ihre Vorschauumgebung korrekt mit Contentful funktioniert. Für jeden Contenttyp müssen sie jedoch noch den Pfad angeben, unter dem die Contenteinträge eines bestimmten Contenttyps angezeigt werden können.

Im Allgemeinen ist der „Pfad“ einfach eine URL auf Ihrer Website, auf der bestimmte Arten von Content angezeigt werden können. Da jedoch verschiedene Contenteinträge unterschiedliche URLs haben, müssen Sie auch das „Token“ angeben, das Ihre App verwendet, um einen bestimmten Contenteintrag für die Vorschau zu identifizieren.

Eine detaillierte Anleitung, welche „Token“ zur Verfügung stehen, finden Sie hier oder in einem Pop-up-Fenster, das angezeigt wird, wenn Sie auf „Token anzeigen“ klicken:

Einige Beispiele veranschaulichen, wie dies in einer hypothetischen Anwendung funktionieren könnte:

• Ihr Projekt hostet einen Blog, in dem Blog-Beiträge in einer URL angezeigt werden, die wie http://www.example.com/blog/a-blog-post-for-today aussieht. Der Wert „ein-blog-post-für-heute“ ist in einem Feld „Slug“ in Ihrem Contenttyp „Blog-Post“ vorhanden. Für das Feld „Pfad“ würden Sie Folgendes eingeben: /blog/{entry.fields.slug}

• Ihr Projekt hostet eine Wissensdatenbank, in der Wissensartikel in einer URL angezeigt werden, die aussieht wie http://www.example.com/help/questions/7yr4hfr17dfsasdf. Der Wert „7yr4hfr17dfsasdf“ ist die Contentful ID Ihrer Wissensartikel-Contenteinträge. Für das Feld „Pfad“ würden Sie Folgendes eingeben: /help/questions/{entry.sys.id}

Hinweis: Das Erstellen eines funktionierenden Vorschau-Pfads erfordert einige Kenntnisse darüber, wie die Routen Ihrer Anwendung strukturiert sind und welche Felder in Contentful diese Routen verwenden, um bestimmte Contenteinträge zu identifizieren. Wenden Sie sich an Ihr Entwicklungsteam, wenn Sie sich nicht sicher sind, wie Sie einen funktionierenden Vorschau-Pfad konfigurieren.

Sobald Sie die Vorschau-Pfade für die Contenttypen erfolgreich konfiguriert haben, kann Ihr Content-Team sofort die Vorschau-Funktionen nutzen, die im „Side-by-Side“-Vorschau-Editor von Contentful verfügbar sind.

Content-Vorschau einrichten

Normalerweise würde Ihr Team Content-Vorschau-Umgebungen konfigurieren und verwalten, indem es zu Einstellungen > Content-Vorschau geht. Sie können zwar weiterhin zusätzliche Vorschau-Umgebungen hinzufügen und konfigurieren, müssen jedoch keine zusätzlichen Konfigurationen vornehmen, um die von der Vercel-App bereitgestellten Vorschauen zu operationalisieren.

Sobald die Vercel-App korrekt installiert ist, sehen Sie einen Abschnitt zu den Content-Vorschau-Einstellungen, der Ihre Nutzer*innen zurück zur App-Konfigurationsseite leitet, auf der sie Vercel-spezifische Content-Vorschau-Einstellungen verwalten können (siehe oben):

Es gibt einige zusätzliche Einstellungen auf dieser Seite, die relevant bleiben:

• Sie müssen weiterhin den „Vorschau-Modus“ angeben, den Ihre App unterstützt – entweder „Live-Vorschau“ oder „Vorschau in neuer Registerkarte“

• Benutzerdefinierte Vorschau-Token werden weiterhin über den Bildschirm mit den Content-Vorschau-Einstellungen konfiguriert und verwaltet. Alle benutzerdefinierten Token, die Sie hier definieren, sind im Feld Vorschaupfad verfügbar, wie im obigen Abschnitt beschrieben.

Content-Vorschau verwenden

Ihre Nutzer*innen können den Vorschau-Modus direkt über die Seitenleiste des Eintrags auslösen:

Wenn Sie mehrere Vorschau-Umgebungen haben (wie in der Abbildung oben), wird die von der Vercel-App bereitgestellte Vorschau-Umgebung als solche gekennzeichnet. Ihre Nutzer*innen können über den Link „Ändern“ zwischen den Vorschau-Modi wechseln.

Hinweis: Wenn die Vercel-App die einzige Umgebung ist, die Sie für einen Space konfiguriert haben, werden Ihren Nutzer*innen die Optionen „Plattform“ und „Ändern“ nicht angezeigt.

Möglicherweise werden bei der Konfiguration der Vercel-App bestimmte Fehlermeldungen angezeigt. Nachfolgend finden Sie einige der häufigsten Fehler, die bei jedem Konfigurationsschritt auftreten können, und Vorschläge, wie Sie die Fehler am besten beheben können.

Authentifizierung

• Ungültiges Zugriffstoken. Das Token ist möglicherweise kein gültiges Vercel-Zugriffstoken. Befolgen Sie unsere obigen Anweisungen, um ein gültiges Vercel Access Token zu erstellen.

• Der Token ist nicht auf ein Team beschränkt. Der Zugriffstoken, den Sie in Vercel erstellt haben, ist nicht auf ein bestimmtes Team beschränkt, sondern auf das gesamte Konto. Stellen Sie sicher, dass Sie beim Erstellen des Tokens ein bestimmtes Team für die Spezifikation mit dem Titel Ziel auswählen.

• Der Token ist abgelaufen. Der von Ihnen hinzugefügte Zugriffstoken ist abgelaufen. Versuchen Sie, ein neues Token in Vercel zu erstellen. Wir empfehlen, ein Token ohne Ablaufdatum zu erstellen.

Projektauswahl

• Das von Ihnen konfigurierte Projekt ist nicht mehr verfügbar. Bitte wählen Sie ein anderes aus. Das Projekt, das Sie zuvor konfiguriert hatten, ist nicht mehr in der Liste der verfügbaren Vercel-Projekte verfügbar, da es höchstwahrscheinlich in Vercel gelöscht wurde. Versuchen Sie, ein anderes Projekt auszuwählen.

• Es sieht so aus, als hätten Sie im ausgewählten Vercel-Projekt eine Umgebungsvariable, CONTENTFUL_SPACE_ID, konfiguriert, die nicht mit der aktuellen ID des Space, <space_id>, übereinstimmt, in dem diese App installiert ist. Stellen Sie sicher, dass die Umgebungsvariable auf die richtige Contentful Space-ID verweist, in der die App installiert ist. Die Umgebungsvariable finden Sie in Ihrem Vercel-Projekt unter Einstellungen > Umgebungsvariablen. (Beachten Sie, dass diese Nachricht eine Warnung ist – es ist möglich, dass Ihre Entwickler*innen eine andere Methode verwenden, um den Space zu identifizieren, in dem sich Ihr Contentful Content befindet. Wenn alles richtig funktioniert, können Sie diese Warnung ignorieren.)

• Das von Ihnen konfigurierte Projekt hat keine Schutzumgehung aktiviert. Bitte aktivieren Sie sie. Stellen Sie sicher, dass im ausgewählten Vercel-Projekt die Option Schutzumgehung für die Automatisierung aktiviert ist. Dies ist wichtig, damit Ihre Anwendung korrekt im Side-by-Side-Vorschaufenster von Contentful geladen wird. Diese Einstellung finden Sie in Ihrem Vercel-Projekt unter Einstellungen > Bereitstellungsschutz. Scrollen Sie nach unten zum Abschnitt Schutzumgehung für die Automatisierung, wo Sie die Einstellung aktivieren können.

Auswahl des Routenhandlers für den Entwurfsmodus

• Die von Ihnen konfigurierte Route ist nicht mehr verfügbar. Bitte wählen Sie eine andere aus. Die Route, die Sie zuvor zum Aktivieren des Entwurfsmodus ausgewählt hatten, ist nicht mehr in der Liste der konfigurierten Routen verfügbar, die Ihrem Projekt zugeordnet sind. Versuchen Sie, eine andere Route aus der Dropdown-Liste auszuwählen, und sprechen Sie mit Ihrem Entwicklungsteam, wenn Sie die entsprechende Route nicht finden.

• Es sieht so aus, als wären in Ihrem Vercel-Projekt noch keine Routen konfiguriert. Der Fehler wird zusammen mit einer Texteingabe angezeigt, um die manuelle Eingabe der Route zu unterstützen. Dies kann ein Indikator dafür sein, dass Ihre Anwendung noch nicht korrekt eingerichtet ist (siehe Schritt 1 oben für eine Anleitung, was von Ihrem Entwicklungsteam zur Unterstützung der Vercel-App benötigt wird). Sie können auch bestätigen, dass diese Routen existieren, indem Sie Ihr Projekt auf Vercel anzeigen. Klicken Sie unter Bereitstellungen auf die letzte Bereitstellung. Klicken Sie im Abschnitt Bereitstellungsdetails Ihrer letzten Bereitstellung auf Bereitstellungszusammenfassung > Funktionen, wo die Routen aufgeführt werden sollten (z. B./api/enable-draft).

Auswahl des Contenttyps und des Vorschaupfads

• Das Feld ist leer. Stellen Sie sicher, dass für jeden Contenttyp, den Sie unter Vorschau-Einstellungen konfiguriert haben, ein Vorschau-Pfad vorhanden ist.

• Der Pfad muss mit einem „/“ beginnen und ein {token} enthalten. Stellen Sie sicher, dass Ihr Vorschaupfad mit einem Schrägstrich beginnt und ein dynamisches Token enthält, das von geschweiften Klammern umgeben ist, z. B./blogs/{entry.fields.slug} . Lesen Sie diese Anleitung, wenn Sie Schwierigkeiten haben, einen Vorschaupfad zu erstellen, der korrekt mit der Verwendung von Contentful durch Ihr Team funktioniert.