クライアント設定

@genko-me/sdkは、genko.meの配信APIをJavaScript／TypeScriptから利用するためのSDKです。ReactやNext.jsを使わないアプリでも、サーバー側から利用できます。

初めて接続する場合はクイックスタートで、API作成とCLIによる初期設定を済ませてください。

生成されたクライアント

initはAPI定義をlib/schema.tsへ、接続設定をlib/client.tsへ生成します。Next.jsプロジェクトで生成される接続設定は次の形です。

import "server-only";
import { createGenko } from "@genko-me/sdk";
import { apis } from "./schema";

export const genko = createGenko({
  workspace: "your-workspace",
  apiKey: process.env.GENKO_API_KEY!,
  apis,
});
export const client = genko.apis;

apisのキーがエンドポイントになります。たとえばエンドポイントにハイフンを使っている場合も、{ "news-items": newsItems }のように実際のエンドポイントをキーにします。CLIはこの対応も生成します。

process.env.GENKO_API_KEY!の!はTypeScript上の指定です。環境変数が未設定でも値を補うものではありません。実行環境への設定を確認してください。

スキーマとクライアントの更新

npx @genko-me/cli pull

pullはスキーマを再生成し、クライアントは変更しません。生成されたapisにはAPI一覧も含まれるため、API追加時もclient.tsの編集は不要です。同期対象を限定している場合はpull --select-apisで新しいAPIを選択に追加します。再生成後は利用コードの型チェックを行います。古いクライアントでapis: { blog }のように列挙している場合は、上の例のようにschema.tsのapisを参照する形へ変更してください。

共通オプション

createGenkoでは、このほかにapisと任意のpluginsを設定します。プラグインでNext.js連携やリクエスト処理の拡張ができます。

手動で定義する

CLIを使わない場合はSDKをインストールし、自分で型を定義できます。型は管理画面のスキーマと合わせて管理してください。

npm install @genko-me/sdk

import { createGenko, listApi, objectApi } from "@genko-me/sdk";

type BlogPost = { title: string; body: string };
type Profile = { name: string; bio?: string };

export const genko = createGenko({
  workspace: "your-workspace",
  apiKey: process.env.GENKO_API_KEY!,
  apis: {
    blog: listApi<BlogPost>(),
    profile: objectApi<Profile>(),
  },
});

上の例はデータ取得用です。ListItem / ViewItemで表示する場合は、型に加えてfieldsの定義が必要です。手動導入の例を参照してください。

listApi／objectApiはクライアントの型と取得方法を決める定義です。実行してもgenko.me側にAPIを作成しません。

エンドポイントを都度指定する

固定のapisを定義せずに取得する場合は、createClientを使えます。

import { createClient } from "@genko-me/sdk";

const client = createClient({
  workspace: "your-workspace",
  apiKey: process.env.GENKO_API_KEY!,
});

const { contents } = await client.getList<{ title: string }>({
  endpoint: "blog",
  queries: { limit: 10 },
});

createGenkoからもgenko.clientで低レベルクライアントにアクセスできます。

fetchとキャッシュ

List / Viewを使う場合は、既定で毎回取得します。キャッシュが必要な場合だけ部品にcache={60}などを指定してください。PaginationはSDK内のServer Actionを使うため、カスタムfetchやwrapRequestを設定したクライアントには対応しません。以下は取得処理を自分で書く場合の設定です。

SDK自体はキャッシュの有効期間や自動リトライを設定しません。必要に応じてfetchを差し替えます。たとえば毎回取得する設定は次のように書けます。

import { createGenko } from "@genko-me/sdk";
import { blog } from "./schema";

export const genko = createGenko({
  workspace: "your-workspace",
  apiKey: process.env.GENKO_API_KEY!,
  apis: { blog },
  fetch: (input, init) => fetch(input, { ...init, cache: "no-store" }),
});

initには認証ヘッダーが入るため、差し替えた関数でも引き継ぎます。プレビューは公開ページの共有キャッシュへ保存しない構成にしてください。

型が扱う範囲

戻り値にはコンテンツの型に加えて、ID・日時のメタ情報が付与されます。ただしSDKは実行時のJSON検証をしません。参照フィールドや項目選択を使うときはレスポンスの値も確認してください。