クライアント設定

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

初めて接続する場合はクイックスタートで、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!,  baseUrl: "https://api.genko.me",  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で低レベルクライアントにアクセスできます。

多言語のAPIでは、getListのqueries、getとgetObjectのオプションにlang・langFallback・includeを渡せます。langFallback: trueはHTTPのlang_fallback=true、include: ["_langs"]はinclude=_langsになります。省略した呼び出しのURLは従来と変わりません。

const { contents } = await client.getList<{ title: string }>({  endpoint: "blog",  queries: { lang: "en", include: ["_langs"] },});const article = await client.get<{ title: string }>({  endpoint: "blog",  id: "abcDEF123456",  lang: "en",});const profile = await client.getObject<{ name: string }>({  endpoint: "profile",  lang: "en",  langFallback: true,});

includeを指定した場合でも、_langsの型は省略可能です。実際のレスポンスに含まれるか確認してから使ってください。SDKの言語別クエリも参照してください。

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検証をしません。参照フィールドや項目選択を使うときはレスポンスの値も確認してください。