クイックスタート

このガイドでは、blogというAPIに記事を1件作成し、CLIで接続して、SDKのListとViewで一覧・詳細を表示します。保存済み下書きのプレビューも、同じ詳細ページで確認できます。

原稿の作成だけを担当する方は、手順3まで進めてからコンテンツの作成と公開へ進んでください。

用意するもの

• genko.meのアカウントとワークスペース。APIの作成・APIキーの発行にはオーナー権限が必要です。
• 開発する場合は、利用するNext.jsに対応したNode.jsとパッケージマネージャー、および起動できるNext.js 16以降・React 19のApp Routerプロジェクト。表示部品はNode.jsランタイムを対象にしています。
• ターミナルで、そのプロジェクトのpackage.jsonがあるディレクトリを開いておきます。

このガイドのyour-workspaceは、自分のワークスペースIDに置き換えます。@/はプロジェクトのルートを指すimportエイリアスを想定しています。src/構成などの場合は、生成先に合わせてimportを調整してください。

1. ワークスペースを開く

genko.meに登録・ログインし、初回は個人ページIDの設定を完了します。チームを使う場合は、そのチームへ切り替えてください。

管理画面のURLがhttps://genko.me/your-workspaceなら、接続に使うワークスペースIDはyour-workspaceです。

2. ブログAPIを作る

ワークスペースでAPIの作成画面を開き、次の内容で作成します。

スキーマには次の2項目を用意します。既存の項目がある場合は、IDと種類が一致しているか確認してください。

複数の記事を管理するのでリスト形式を使います。サイト設定など1件だけを管理するときはオブジェクト形式を選びます。APIとスキーマで詳しく説明しています。

3. 記事を1件公開する

1. 作成したブログAPIを開き、新しいコンテンツを追加します。
2. タイトルに「はじめての記事」、本文に好きな文章を入力します。
3. エディタの「設定」で公開状態を「公開」にします。
4. 「保存する」を押し、「保存済み」になったことを確認します。

下書きのままでは、通常の配信APIから取得できません。 公開状態の変更も保存が必要です。

4. APIキーを発行する

ワークスペースの「APIキー」で、用途がわかる名前を付けてキーを作成します。作成直後に表示される値を控えます。全文は後から再表示できません。

APIキーは、次のCLIの入力で使います。ブラウザ側のコードや公開リポジトリには含めないでください。APIキーの管理に交換手順もまとめています。

5. CLIで接続する

アプリのプロジェクトルートで実行します。

npx @genko-me/cli init

ワークスペースIDとAPIキーを入力し、同期するAPIとしてblogを選択すると、SDK・Next.js用React部品の追加と接続ファイルの生成が行われます。表示部品はNext.js 16以降のApp Routerを対象にしています。

.env.localがGitの追跡対象になっていないことを確認してください。すでに初期化済みならinitを繰り返さず、pullで型を同期します。

CLIはページ自体を生成しません。以下の一覧・詳細ページのコードを配置してください。src/app構成では生成先が自動でsrc/libになります。以降のページもsrc/appに配置してください。独自のimportエイリアスを使っている場合は、生成先に合わせてimportを調整します。

6. 記事一覧を表示する

生成された client とSDKの表示部品をサーバーコンポーネントから利用します。

import { client } from "@/lib/client";
import { List, ListItem, Pagination, Error, Null } from "@genko-me/react/next";

export default function BlogPage() {
  return (
    <main>
      <h1>ブログ</h1>
      <List api={client.blog} limit={6} orders="-publishedAt" href="/blog/{id}">
        <article><h2><ListItem id="title" /></h2></article>
        <Pagination />
        <Error template />
        <Null>公開されている記事はありません。</Null>
      </List>
    </main>
  );
}

開発サーバーを起動し、/blogを開きます。「はじめての記事」が表示されれば接続完了です。環境変数を追加した後にすでにサーバーが動いていた場合は、再起動してください。

7. 詳細ページと下書きプレビュー

import { client } from "@/lib/client";
import { View, ViewItem, Error, Null } from "@genko-me/react/next";

type Props = {
  params: Promise<{ id: string }>;
  searchParams: Promise<Record<string, string | string[] | undefined>>;
};

export default async function BlogDetail({ params, searchParams }: Props) {
  const { id } = await params;
  return (
    <View api={client.blog} id={id} searchParams={searchParams}>
      <h1><ViewItem id="title" /></h1>
      <ViewItem id="body" />
      <Error template />
      <Null>記事が見つかりません。</Null>
    </View>
  );
}

管理画面のプレビューURLを https://your-site.example/blog/{id}?draftKey={key} に設定します。保存してから「プレビュー」を開くと、同じ詳細ページで下書きが表示されます。追加のRoute HandlerやProxyは不要です。ただし、ページが受け取るsearchParamsをViewへ渡す記述は必要です。SDKがページのURLから自動で受け取るわけではありません。

通常表示も既定では毎回最新を取得します。キャッシュしたいときだけ cache={60} のように秒数を指定します。下書きは常にキャッシュしません。

表示されないとき

スキーマを変更したら

管理画面で項目を追加・変更した後は、アプリ側で実行します。

npx @genko-me/cli pull

lib/schema.tsの型・フィールド定義・API一覧が更新されます。client.tsはその一覧を参照するため編集は不要です。新しいAPIも使う場合はpull --select-apisで同期対象に追加します。開発中は pull --watch を別ターミナルで実行すると、変更を10秒ごとに確認できます。

本番へデプロイするときは、ホスティング先にもGENKO_API_KEYを設定します。ローカルの.env.localは自動では引き継がれません。

本番へ反映する

生成したスキーマ・クライアント・設定とページをリポジトリへ追加し、本番環境のGENKO_API_KEYを設定してビルド・デプロイします。.env.localやキーの値は追加しません。

デプロイ後は公開記事を開き、管理画面から保存済み下書きをプレビューして、終了操作で公開表示に戻ることを確認します。記事数がlimitを超える場合はページ送りも確認してください。PaginationはSDK内のServer Actionを使うため、静的エクスポートやEdgeランタイムには対応していません。

次にできること

• 表示部品のカスタマイズ・手動導入
• 取得処理を自分で書く
• リッチテキストの本文を表示する
• 公開前のページをプレビューする
• コンテンツ更新をサイトに反映する
• SDKを使わずHTTPで取得する