Artikel auf deiner Next.js-Seite ausliefern.
Bei Next.js schickt Citapult nichts an deine Seite, sondern deine Seite holt die Artikel ab: über eine kleine API mit eigenem Schlüssel. Citapult gibt dir den Code dafür, vier Dateien zum Kopieren.
Aktualisiert am
Was du brauchst
- Eine Next.js-Seite ab Version 15 mit App Router. Für andere Setups reicht die API allein, siehe unten.
- Zugriff auf die Umgebungsvariablen bei deinem Hoster, etwa in den Projekteinstellungen bei Vercel.
- Freie Pfade für
/blogund/<slug>, oder du passt die beiden Seiten aus den Starter-Dateien an deine Struktur an.
Einrichten
1. Integration hinzufügen
Öffne in Citapult Einstellungen → Integrationen, wähl unter „Art“ Next.js und klick auf „Hinzufügen“. Citapult legt dabei einen Schlüssel an, der mit
rq_beginnt. Er liest nur Artikel, die diese Integration bekommen hat.2. Starter-Dateien übernehmen
Unter „Einrichtung“ bei der Integration stehen vier Dateien mit deinem Schlüssel:
.env.local,lib/citapult.ts,app/blog/page.tsxundapp/[slug]/page.tsx. Kopier sie in dein Projekt. Weil.env.localnicht mit deployt wird, trägst du die beiden Variablen zusätzlich bei deinem Hoster ein und deployst..env.local CITAPULT_API_URL=https://…/api/v1 CITAPULT_API_KEY=rq_…
3. Artikel veröffentlichen
Öffne einen fertigen Artikel und klick auf „Veröffentlichen“. Ab dann liegt er auf deiner Seite unter
/<slug>, also unter derselben URL wie in Citapult, und in der Übersicht unter/blog. Deine Seiten laden höchstens alle fünf Minuten neu, und erst beim nächsten Aufruf: Der bekommt noch den alten Stand. Artikel, die du vor dem Hinzufügen veröffentlicht hast, liefert die API erst, wenn du sie noch einmal sendest.4. Optional: automatisch veröffentlichen
Schalte bei den Integrationen „Automatisch veröffentlichen“ ein. Dann gehen Artikel im Status „Zu prüfen“ an ihrem geplanten Tag ohne Klick an alle Integrationen. Die Uhrzeit stellst du im Kalender unter „Zeitplan“ ein.
Die Endpunkte
Die Starter-Dateien nutzen zwei Endpunkte unter CITAPULT_API_URL. Beide brauchen den Schlüssel im Header Authorization: Bearer rq_…. Ein falscher Schlüssel bekommt 401 mit {"error":"Invalid API key"}, ein unbekannter Slug 404 mit {"error":"Not found"}.
GET /articles:{ "articles": [...] }mit allen Artikeln, die diese Integration bekommen hat, die neuesten zuerst.GET /articles/<slug>: ein Artikel mit allen Feldern, so wie er zuletzt gesendet wurde.
curl "$CITAPULT_API_URL/articles" \ -H "Authorization: Bearer $CITAPULT_API_KEY"
Was die API liefert
Die Liste unter /articles lässt die großen Felder weg: content_html, content_markdown, json_ld und sources gibt es nur beim einzelnen Artikel.
| Feld | Inhalt |
|---|---|
id | Die ID des Artikels in Citapult |
title | Der Titel, auf der Artikelseite die H1 |
slug | Das Ende der URL, unter der dein Artikel liegt |
content_html | Der Artikeltext als HTML, ohne die H1. Rohes HTML aus dem Text kommt als Text an, nur YouTube-Einbettungen bleiben, deshalb kannst du ihn direkt einsetzen. |
content_markdown | Derselbe Text als Markdown |
meta_title, meta_description | Meta-Titel und Meta-Beschreibung, oder null |
image_url, image_alt | Titelbild und sein Alt-Text, oder null |
language | Sprache und Land des Artikels, etwa de-DE |
tags | Eine Liste mit dem Haupt-Keyword des Artikels |
json_ld | Die strukturierten Daten als Liste, je ein application/ld+json-Skript |
sources | Die Quellen mit url und title |
author | Name, Rolle und Kurzbio aus den Einstellungen, oder null |
created_at, published_at, updated_at | Zeitpunkte im ISO-Format |
Wenn du einen Artikel änderst
Bearbeitest du einen veröffentlichten Artikel, steht er wieder auf „Zu prüfen“, und die API liefert weiter die alte Fassung. Die neue kommt mit „Aktualisieren“ oder, mit „Automatisch veröffentlichen“, von selbst, wenn der Artikel für heute oder gestern geplant war. Den Slug sperrt Citapult nach dem ersten Veröffentlichen, damit die URL bleibt.
Integration entfernen
Der Schlüssel gilt dann sofort nicht mehr, und deine Seite bekommt keine Artikel mehr. Eine neue Integration hat einen neuen Schlüssel und liefert nur, was du danach erneut sendest.
Fehler und Fragen
Ich nutze den Pages Router oder ein anderes Framework
Die Starter-Dateien sind für den App Router gebaut. Die API selbst ist ein normaler GET mit Bearer-Token und funktioniert mit jedem Framework: Hol die Liste von /articles und den einzelnen Artikel von /articles/<slug>.
Ein neuer Artikel taucht nicht auf
Deine Seiten laden höchstens alle fünf Minuten neu, und erst beim nächsten Aufruf: Der bekommt noch den alten Stand. Ruf die Seite nach ein paar Minuten zweimal auf. Steht in der Liste unter dem Button ein Fehler bei der Next.js-Integration, hat sie den Artikel nicht bekommen. Ein Fehler bei einer anderen Integration hält ihn nicht auf.
Citapult API: HTTP 401 auf deiner Seite
Citapult API: HTTP 401 auf deiner SeiteDer Schlüssel fehlt in den Umgebungsvariablen deines Hosters, ist falsch kopiert oder gehört zu einer entfernten Integration. Kopier ihn neu aus „Einrichtung“ und deploye noch einmal.
„‚…‘ hat dort schon den Slug …“
Auf deiner Seite liegt schon ein anderer Artikel aus Citapult unter diesem Slug. Dann geht der neue Artikel an keine Integration raus, auch nicht an die anderen. Gib ihm einen anderen Slug und sende ihn noch einmal. Das geht, solange keine Integration den Artikel hat oder gerade anlegt. Danach ist sein Slug fest, und die Next.js-Integration kann ihn nicht neben dem anderen Artikel ausliefern.
Darf der Schlüssel in den Browser?
Nein, er gehört auf den Server. Die Starter-Dateien nutzen ihn nur in Server Components. Leg ihn nie in eine Variable mit NEXT_PUBLIC_.