Quickstart

This guide creates one entry in an API named blog, connects with the CLI, and shows a list and a detail page with the SDK's List and View. You can also check saved drafts on the same detail page with preview.

If you only write content, finish step 3, then go to Create and publish content.

What you need

• A genko.me account and workspace. Creating an API and issuing an API key require the Owner or Maintainer role.
• For development: a version of Node.js 20.12 or later that your version of Next.js supports, a package manager, and a Next.js 16+ / React 19 App Router project that runs. The components target the Node.js runtime.
• A terminal open in the directory that contains the project's package.json.

Replace your-workspace in this guide with your own workspace ID. @/ is assumed to be an import alias that points to the project root. If you use a layout such as src/, adjust the imports to match where the files are generated.

1. Open your workspace

Sign up or sign in at genko.me. The first time, set your personal workspace ID and choose a plan. If you use a team, switch to that team.

If your dashboard URL is https://genko.me/w/your-workspace, the workspace ID you connect with is your-workspace.

2. Create the blog API

Open the workspace's API creation screen (/w/your-workspace/new-api) and create it with these settings.

Add these two fields to the schema. If fields already exist, check that the IDs and types match.

Use the List format because you manage multiple posts. Choose the Object format when you manage a single item, such as site settings. APIs and schemas explains this in more detail.

3. Publish one entry

1. Open the blog API you created and add a new entry.
2. Enter "My first post" as the title and any text as the body.
3. In the editor's Settings, set the status to Published.
4. Select Save and confirm it changes to Saved.

A draft can't be fetched from the regular delivery API. Changing the status also needs a save.

4. Issue an API key

Open "Settings and plan" from the workspace menu, then create a key on the API keys tab (/w/your-workspace/settings/api-keys). Give it a name that describes its use and a validity period. If you choose "Selected APIs only", allow blog. Copy the value shown right after creation. You can't view the full value again later.

You use the API key in the CLI prompt below. Keep it out of browser-side code and public repositories. Manage API keys also covers how to rotate keys.

5. Connect with the CLI

Run this in the root of your app's project.

npx @genko-me/cli init

Enter your workspace ID and API key, then choose blog as the API to sync. The CLI adds the SDK and the React components for Next.js, and generates the connection files. The components target the Next.js 16+ App Router. The CLI itself is also added as a dev dependency.

CLI 0.2.7 init adds SDK ^0.6.0 and the React components ^0.5.0 (for Next.js). In a project that already has them, update the dependencies and then sync types with pull.

Make sure .env.local isn't tracked by Git. If the project is already initialized, don't repeat init. Sync types with pull instead.

The CLI doesn't generate the pages themselves. Add the list and detail page code below. With a src/app layout, the output goes to src/lib automatically, and you should put the following pages in src/app too. If you use a custom import alias, adjust the imports to match where the files are generated.

6. Show the post list

Use the generated client and the SDK's components from a server component.

import { client } from "@/lib/client";import { List, ListItem, Pagination, Error, Null } from "@genko-me/react/next";
export default function BlogPage() {  return (    <main>      <h1>Blog</h1>      <List api={client.blog} limit={6} orders="-publishedAt" href="/blog/{id}">        <article><h2><ListItem id="title" /></h2></article>        <Pagination />        <Error template />        <Null>No published posts yet.</Null>      </List>    </main>  );}

Start the dev server and open /blog. If "My first post" appears, you're connected. If the server was already running when you added the environment variables, restart it.

7. Detail page and draft preview

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>Post not found.</Null>    </View>  );}

Set the dashboard's preview URL to https://your-site.example/blog/{id}?draftKey={key}. After you save, select Preview and the same detail page shows the draft. You don't need an extra Route Handler or Proxy. You do need to pass the page's searchParams to View. The SDK doesn't read them from the page URL on its own.

Regular views also fetch the latest content every time by default. Set a number of seconds, such as cache={60}, only when you want caching. Drafts are never cached.

If nothing shows up

After you change the schema

After you add or change fields in the dashboard, run this in your app.

npx @genko-me/cli pull

This updates the types, field definitions, and API list in lib/schema.ts. client.ts reads that list, so you don't need to edit it. To use a new API too, add it to the sync with pull --select-apis. During development, run pull --watch in a separate terminal to check for changes every 10 seconds.

When you deploy to production, set GENKO_API_KEY on your hosting provider too. Your local .env.local isn't carried over automatically.

Ship to production

Add the generated schema, client, config, and pages to your repository, set GENKO_API_KEY in the production environment, then build and deploy. Don't commit .env.local or the key value.

After you deploy, open a published post, preview a saved draft from the dashboard, and confirm that exiting preview returns to the published view. If you have more entries than limit, check pagination too. Pagination uses a Server Action inside the SDK, so it doesn't support static export or the Edge runtime.

What to do next

• Start with the announcements template
• Customize the components or install them manually
• Write your own fetch code
• Display rich text content
• Preview a page before it's published
• Reflect content updates on your site
• Fetch over HTTP without the SDK