Client configuration

@genko-me/sdk is an SDK for using genko.me's delivery API from JavaScript/TypeScript. You can use it on the server without React or Next.js. This page covers the 0.6.0 API.

If you are connecting for the first time, please go to Quick Start to create the API and complete the initial settings using the CLI.

Generated client

init generates API definitions in lib/schema.ts and connection settings in lib/client.ts. The connection configuration generated in a Next.js project is of the form:

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;

The apis key will be the endpoint. For example, even if you use a hyphen for the endpoint, use the actual endpoint as the key, like { "news-items": newsItems }. The CLI also generates this correspondence.

The ! in process.env.GENKO_API_KEY! is a TypeScript assertion. It does not provide a value when the environment variable is missing. Please check the settings for the execution environment.

Schema and client updates

npx @genko-me/cli pull

pull regenerates the schema and leaves the client unchanged. The generated apis also includes the API list, so there is no need to edit client.ts when adding an API. If you are limiting the synchronization targets, use pull --select-apis to add new APIs to the selection. After regeneration, the code used will be type checked. If you have an old client that lists things like apis: { blog }, please change it to refer to apis in schema.ts as in the example above.

Common options

createGenko also sets apis and any plugins. Plugins allows you to expand Next.js integration and request processing.

Define manually

If you don't want to use the CLI, you can install the SDK and define the types yourself. Please manage types together with the schema on the dashboard.

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>(),  },});

The example above fetches data. If you want to display with ListItem / ViewItem, you need to define fields in addition to the type. Please refer to Example of manual installation.

listApi and objectApi define client types and fetch methods. They do not create APIs in genko.me.

Specify an endpoint per request

Use createClient if you want to fetch an endpoint without defining it in apis.

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 },});

You can also access the low-level client from createGenko with genko.client.

For multilingual APIs, pass lang, langFallback, and include in getList's queries or in the options for get and getObject. langFallback: true becomes lang_fallback=true in HTTP, and include: ["_langs"] becomes include=_langs. Omitting these options leaves the URL unchanged.

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,});

Even if include is specified, the _langs type can be omitted. Please check whether it is included in the actual response before using it. See also SDK language-specific queries.

Fetch and cache

List and View fetch on every request by default. Specify cache={60} for the part only if caching is required. Pagination uses the Server Action in the SDK, so it does not support clients with custom fetch or wrapRequest settings. Below are the settings when writing the fetching process yourself.

The SDK does not set a cache lifetime or retry automatically. Replace fetch as necessary. For example, the settings to be retrieved every time can be written as follows.

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" }),});

Since the authentication header is included in init, the replaced function will also inherit it. Please configure the preview so that it is not saved to the shared cache of the public page.

What types cover

In addition to the content type, meta information such as ID and date and time are added to the return value. However, the SDK does not perform JSON validation at runtime. When using reference fields or item selections, also check Response values.