Kookeebeta
Zurück zum Blog

Blog, Changelog und Hilfecenter an einem Nachmittag mit Kookee

getting-startedDenis Povarov

Kookee ist ein Content-Backend: Du schreibst Blogbeiträge, Changelog-Einträge, Hilfeartikel, Seiten und Ankündigungen in einem Dashboard, und deine App holt sie als JSON und rendert sie mit deinen eigenen Komponenten auf deiner eigenen Domain. Diese Anleitung führt mit dem TypeScript-SDK vom leeren Projekt zu drei Inhaltsbereichen, die live sind. Wenn dein Framework JSON laden und auf dem Server rendern kann – Next.js, Astro, Nuxt, SvelteKit, TanStack Start –, lässt sich alles direkt übertragen.

1. Projekt anlegen und Zugangsdaten holen

Registriere dich (der Free-Plan braucht keine Kreditkarte und enthält die Module Blog, Changelog und Hilfecenter), leg ein Projekt an und notiere dir zwei Zugangsdaten:

  • Projekt-ID – darf im Browser-Code stehen; sie liest veröffentlichte Inhalte, genau wie der API-Schlüssel. Sie funktioniert nur, solange das gehostete Portal des Projekts aktiviert ist; sonst antwortet die API mit 403 PORTAL_NOT_ENABLED.

  • API-Schlüssel – funktioniert für jedes Projekt, auf deinen Servern und im Browser. Er liest nur veröffentlichte Inhalte. Alles, was an einen Browser geht, sehen aber auch die Besucher, also beschränke ihn über die erlaubten Origins des Projekts auf deine Domains.

Die Faustregel: apiKey überall, über erlaubte Origins beschränkt, wo immer er einen Browser erreicht; projectId im Browser-Code nur, solange das gehostete Portal eingeschaltet bleibt.

Schreib jetzt im Dashboard einen Test-Blogbeitrag, einen Changelog-Eintrag und einen Hilfeartikel und veröffentliche sie – am anderen Ende deines ersten Fetch sollen echte Daten liegen.

2. SDK installieren und initialisieren

Bash 
npm install @kookee/sdk
ts 
import { Kookee } from '@kookee/sdk';

export const kookee = new Kookee({ apiKey: process.env.KOOKEE_API_KEY });

Das SDK ist TypeScript-first, hat keine Abhängigkeiten und ist tree-shakeable; jede Lesemethode nimmt ein AbortSignal an. Instanziiere es einmal in einem gemeinsamen Modul und importiere es in deinen Route-Loadern.

3. Der Blog: Liste und Detailseite

Zwei Routen. Die Listenseite:

ts 
const { data: posts } = await kookee.blog.list({ page: 1, limit: 10 });

Jede Zusammenfassung enthält Titel, Slug, Auszug, Tags und Zeitstempel – genug für Karten. Die Detailseite lädt den vollständigen Eintrag per Slug:

ts 
const post = await kookee.blog.getBySlug(slug);

Detail-Antworten enthalten den gerenderten Body als HTML und dazu die SEO-Felder, die du im Editor gesetzt hast. Der Head deines Dokuments kommt also aus demselben Fetch: Titel, Meta-Description, Canonical aus dem Slug, OG-Bild. Findet getBySlug nichts, gib ein echtes 404 zurück.

Tag-Seiten sind derselbe List-Aufruf mit tags: ['news'], ein Suchfeld ist list({ search: query }), und kookee.blog.getTags() liefert dir die Tag-Wolke mit Zählern.

4. Der Changelog

Genauso aufgebaut, mit typisierten Kategorien:

ts 
const { data: entries } = await kookee.changelog.list({ page: 1, limit: 20 });
const features = await kookee.changelog.list({ filter: { changelogType: 'feature' } });

Jeder Eintrag hat einen Typ (feature, fix, improvement, breaking, security, deprecated oder other) und optional eine Version. Deine UI rendert damit Badges und Filter, ohne dass du eine eigene Konvention erfinden musst. Reaktionen kosten einen einzigen Aufruf, wenn du zu Releases eine schnelle Rückmeldung willst:

ts 
await kookee.changelog.react(entryId, { reactionType: 'fire', action: 'add' });

5. Das Hilfecenter: Kategorien, Artikel, semantische Suche

Drei Fetches decken die Routen ab:

ts 
const categories = await kookee.help.categories();
const articles = await kookee.help.list({ category: 'getting-started' });
const article = await kookee.help.getBySlug('reset-your-password');

Das Besondere ist die Suche: Sie ist semantisch. Sie sucht nach Bedeutung statt nach Stichwörtern und liefert den passenden Ausschnitt mit, damit du zeigen kannst, warum ein Treffer passt:

ts 
const results = await kookee.help.search({ query: 'diesen Monat doppelt abgebucht', limit: 5 });
// results[i].title, results[i].matchedChunk

Wenn dein Artikelbestand so weit ist, liefert derselbe Inhalt KI-Antworten: kookee.help.chat gibt Antworten zurück, die sich auf deine Artikel stützen und ihre Quellen nennen, und chatStream liefert Deltas für eine Streaming-UI. Im Free-Plan ist das die KI-Funktion mit Kontingent (50 KI-Antworten im Monat), und sie braucht keine zusätzliche Integration: Die Artikel, die du gerade veröffentlicht hast, sind die Wissensbasis.

6. Abkürzungen für React, falls das dein Stack ist

@kookee/react verpackt all das in Hooks – useBlogPosts, useBlogPost, useChangelog, useHelpCategories, useHelpSearch (mit Debounce, lässt sich direkt an ein Eingabefeld hängen) –, die jeweils { data, isLoading, error } zurückgeben, mit Paginierung über loadMore. Rendere auf dem Server mit dem Loader deines Frameworks und übergib das Ergebnis als initialData, damit der erste Paint vollständig ist. Für die Inhalte rendert <EntryContent entry={post} /> das HTML des Eintrags, mit einem Stylesheet für Codeblöcke, das du in einen Tailwind-Cascade-Layer importieren kannst.

Seit 1.9.0 liefert das Paket außerdem serverseitig gerenderte Komponenten für alle drei Bereiche; siehe React-Komponenten für Blog, Changelog und Hilfecenter.

7. Was du bekommst, ohne mehr Code zu schreiben

  • Ein gehostetes Portal unter your-project.kookee.dev – Feedback-Board, Roadmap, Changelog und Hilfecenter sind live, sobald du auf der Seite „Öffentliches Portal“ des Projekts „Öffentliches Portal aktivieren“ einschaltest. Das hilft, solange deine eigenen Routen noch in Arbeit sind (Portal-Seiten stehen auf noindex und konkurrieren in der Suche nie mit deiner Domain).

  • Übersetzungen: Jeder Inhaltstyp nimmt einen locale-Parameter mit Fallbacks pro Projekt an, wenn du mehrsprachig wirst.

  • Kommentare und Reaktionen in allen Modulen, moderiert im Dashboard.

  • Ein MCP-Server: KI-Agenten und Assistenten durchsuchen, lesen und entwerfen darüber deine Inhalte, jedes Teammitglied mit eigenem persönlichem Token, nur lesend, außer du legst es anders fest.

Der Nachmittag im Einzelnen

Realistisch gerechnet: Projekt einrichten und erste Inhalte, eine halbe Stunde; Blog-Routen, eine Stunde; Changelog, eine halbe Stunde; Hilfecenter mit Suche, ein bis zwei Stunden; Metadaten im Head verdrahten, eine Stunde. Die 100.000 API-Requests im Monat aus dem Free-Plan reichen locker für den serverseitig gerenderten Traffic einer kleinen Website, und du zahlst nichts, bis du darüber hinauswächst.

Das Muster, das das so schnell macht, ist der Kern des Produkts: Kookee übernimmt Schreiben, Speicherung, Suche und Auslieferung; dir gehören zwei oder drei schlanke Routen pro Bereich, gebaut mit den Komponenten, die du schon hast. Leg das Projekt an, veröffentliche einen Testbeitrag und mach den ersten list-Aufruf – alles Weitere baut darauf auf.