Kookeebeta
Назад к блогу

Блог, журнал изменений и центр помощи на Kookee за полдня

getting-startedDenis Povarov

Kookee — это бэкенд для контента: вы пишете посты для блога, записи журнала изменений, статьи центра помощи, страницы и объявления в одной панели управления, а ваше приложение получает их в виде JSON и показывает своими компонентами на вашем домене. Это руководство ведёт от пустого проекта до трёх работающих разделов с контентом на TypeScript SDK. Если ваш фреймворк умеет получать JSON и рендерить на сервере — Next.js, Astro, Nuxt, SvelteKit, TanStack Start, — всё ложится на него напрямую.

1. Создайте проект и возьмите данные для подключения

Зарегистрируйтесь (бесплатному тарифу не нужна банковская карта, и в него входят модули блога, журнала изменений и центра помощи), создайте проект и запишите два значения для подключения:

  • ID проекта — его можно показывать в коде для браузера; он читает опубликованный контент, как и API-ключ. Работает, только пока у проекта включён готовый портал, иначе API отвечает 403 PORTAL_NOT_ENABLED.

  • API-ключ — работает в любом проекте, на ваших серверах и в браузере. Он только читает опубликованный контент, но всё, что попадает в браузер, видят посетители, поэтому ограничьте ключ своими доменами в разрешённых источниках проекта.

Простое правило: apiKey — везде, с ограничением по разрешённым источникам, если ключ попадает в браузер; projectId — в коде для браузера, и только пока готовый портал включён.

Сразу напишите в панели управления один пост для блога, одну запись журнала изменений и одну статью центра помощи и опубликуйте их: на другом конце первого запроса должны быть настоящие данные.

2. Установите и инициализируйте SDK

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

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

SDK написан на TypeScript, не имеет зависимостей и поддерживает tree-shaking; каждый метод чтения принимает AbortSignal. Создайте экземпляр один раз в общем модуле и импортируйте его в загрузчики маршрутов.

3. Блог: список и страница поста

Два маршрута. Страница списка:

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

В каждой краткой записи есть заголовок, slug, отрывок, теги и даты — этого хватает для карточек. Страница поста получает запись целиком по slug:

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

Ответ для поста содержит готовый HTML текста и SEO-поля, заполненные в редакторе, поэтому head документа собирается из того же запроса: title, meta description, canonical из slug, OG-картинка. Если getBySlug ничего не нашёл, верните настоящий 404.

Страницы тегов — тот же вызов list с tags: ['news'], поле поиска — list({ search: query }), а kookee.blog.getTags() отдаёт облако тегов с количеством постов.

4. Журнал изменений

Устроен так же, только с типизированными категориями:

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

У записей есть тип (feature, fix, improvement, breaking, security, deprecated или other) и необязательная версия, так что интерфейс может показывать бейджи и фильтры без самодельных соглашений. Если нужна простая обратная связь по релизам, реакции — это один вызов:

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

5. Центр помощи: категории, статьи, семантический поиск

Маршруты закрывают три запроса:

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');

Главное отличие — поиск. Он семантический: ищет по смыслу, а не по ключевым словам, и возвращает найденный фрагмент, чтобы вы могли показать, почему результат подошёл:

ts 
const results = await kookee.help.search({ query: 'списали деньги дважды в этом месяце', limit: 5 });
// results[i].title, results[i].matchedChunk

Когда статей станет достаточно, на том же контенте заработают ответы ИИ: kookee.help.chat возвращает ответы с источниками, опираясь на ваши статьи, а chatStream отдаёт дельты для интерфейса со стримингом. Это функция ИИ с лимитом на бесплатном тарифе (для начала 50 ответов в месяц), и отдельной интеграции ей не нужно: корпус — это статьи, которые вы только что опубликовали.

6. Готовые хуки, если у вас React

@kookee/react оборачивает всё перечисленное в хуки — useBlogPosts, useBlogPost, useChangelog, useHelpCategories, useHelpSearch (с debounce, его можно подключать прямо к полю ввода), — и каждый возвращает { data, isLoading, error } с пагинацией через loadMore. Рендерите на сервере загрузчиком своего фреймворка и передавайте результат в initialData, чтобы первая отрисовка была полной. Текст записи выводит <EntryContent entry={post} />, а к нему есть таблица стилей для блоков кода, которую можно импортировать в cascade layer Tailwind.

С версии 1.9.0 в пакете есть и серверные компоненты для всех трёх разделов, подробнее — в статье React-компоненты для блога, журнала изменений и центра помощи.

7. Что вы получаете, не написав больше ни строчки

  • Готовый портал на your-project.kookee.dev: доска обратной связи, дорожная карта, журнал изменений и центр помощи начинают работать, как только вы включите переключатель «Включить публичный портал» на странице проекта «Публичный портал». Он пригодится, пока ваши собственные маршруты в работе (страницы портала закрыты от индексации, поэтому в поиске не конкурируют с вашим доменом).

  • Переводы: каждый тип контента принимает параметр locale с запасными языками на уровне проекта — на тот случай, когда сайт станет многоязычным.

  • Комментарии и реакции во всех модулях, с модерацией из панели управления.

  • MCP-сервер: ИИ-агенты и ассистенты ищут, читают и готовят черновики вашего контента по личному токену каждого участника команды — только для чтения, если вы не решите иначе.

Полдня по пунктам

Если реалистично: настройка проекта и первый контент — полчаса, маршруты блога — час, журнал изменений — полчаса, центр помощи с поиском — час-два, метаданные в head — час. 100 000 запросов к API в месяц на бесплатном тарифе с запасом хватает на серверный рендеринг небольшого сайта, и платить не нужно, пока вы из них не вырастете.

Быстро получается благодаря тому, ради чего продукт и сделан: написание, хранение, поиск и доставка контента — на Kookee, а на вас — два-три тонких маршрута на раздел, собранных из компонентов, которые у вас уже есть. Создайте проект, опубликуйте тестовый пост и сделайте первый вызов list — дальше всё пойдёт само.