Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.kibocommerce.com/llms.txt

Use this file to discover all available pages before exploring further.

In this guide, we’ll explore how the Website Builder works from a developer’s perspective, then get the Next.js starter kit running locally and create a first page — confirming the full stack is wired up correctly. What you’ll learn:
  • How the editor and your Next.js app connect
  • How to clone and install the Website Builder Next.js starter kit
  • How to configure API keys and environment variables
  • How to create a page in the Admin editor and see it rendered
Prerequisites:
  • Access to a Kibo CMS Admin instance
  • Node.js 20.9+ and npm/yarn installed
  • Familiarity with Next.js App Router — the starter kit uses App Router, not Pages Router

​
How It All Fits Together

Before writing any code, it’s worth understanding how the Website Builder actually works — because it’s a bit different from what you might expect. When a content editor opens the Website Builder in Kibo CMS Admin, they see a canvas where they can drag components onto a page, configure their inputs in a sidebar, and hit Publish. That’s the editorial experience. On the developer side, the picture is different — and it’s what makes the Website Builder stand out from most page builders. The editor doesn’t have its own components or styles. Instead, it’s always connected to a separate frontend app that you own — in this case a Next.js project. When the editor opens, it loads your Next.js app inside an iframe. The component palette, the live preview, all of it is your real app running right there. This means all your component code and all your styles live in your Next.js project. Kibo CMS only stores the page structure — which components are on the page and what input values the editor set for each one. It has no idea what a “Hero” or “Banner” looks like, and it never needs to.
We cover how to create and register your own editor components in the Custom Components guide.
The practical upside: no style clashes, no fighting the platform, full ownership of your code. And because editors are looking at your actual app, the WYSIWYG is genuine — not a simulation. The @webiny/website-builder-nextjs SDK is what connects the two sides — it handles the communication between the editor and your app when editing, and fetches published page documents from Kibo CMS when rendering pages for visitors.

​
Step 1: Open the Admin App

Navigate to your Kibo CMS Admin URL. You’ll need it running and accessible before creating pages later in this guide.

​
Step 2: Clone the Starter Kit

The official Next.js starter kit wires up the SDK, routing, and rendering so you have a working base to build from.
Terminal
git clone https://github.com/webiny/website-builder-nextjs.git my-website
cd my-website
npm install
Before running npm install, make sure the @webiny/website-builder-nextjs and @webiny/sdk versions in package.json match your Kibo CMS version. You can find your Kibo CMS version in the Admin app under Support → About. For example, if your Kibo CMS version is 6.2.1, your package.json should have:
package.json
{
  "dependencies": {
    "@webiny/website-builder-nextjs": "~6.2.1",
    "@webiny/sdk": "~6.2.1"
  }
}

​
Step 3: Gather Your Credentials

To connect the starter kit to your Kibo CMS project, you’ll need an API key, API host URL, and tenant ID. The easiest way to get these is through the Configure Next.js shortcut in Kibo CMS Admin — click Support in the bottom-left corner and select Configure Next.js. Open the Support menu and select Configure Next.js A dialog appears with the three environment variables already filled in and ready to copy: The Configure Next.js dialog gives you all three values in one click Click the copy icon and paste the block directly into your .env file in the next step.
If your Admin is running on a non-localhost domain, the dialog will also include a NEXT_PUBLIC_WEBSITE_BUILDER_ADMIN_HOST variable — make sure to copy that too.

​
API Key Is Auto-Created

Unlike the Headless CMS where you manually create an API key and configure its permissions, the Website Builder API key is created automatically for the current tenant — you’ll find it under Settings → Access Management → API Keys as “Website Builder”. It’s a read-only key, intentionally scoped that way since it’s meant to be used in external frontend apps like your Next.js project. The Website Builder API key is created automatically — no manual setup needed

​
Step 4: Configure Environment Variables

Create a .env file in the root of your Next.js project:
.env
NEXT_PUBLIC_WEBSITE_BUILDER_API_KEY=your_api_key_here
NEXT_PUBLIC_WEBSITE_BUILDER_API_HOST=https://your-cloudfront-url.cloudfront.net
NEXT_PUBLIC_WEBSITE_BUILDER_API_TENANT=root
All three variables are prefixed with NEXT_PUBLIC_ because they are used on the client side during live editing. The Content SDK also reads them server-side at build/request time.

​
Step 5: Start the Dev Server

Terminal
npm run dev
Open http://localhost:3000. At this point you’ll see a “Page not found” message — that’s expected because there are no pages in your Website Builder yet. No pages yet — this is expected at this point

​
Step 6: Create Your First Page

  1. Open your Kibo CMS Admin app.
  2. In the sidebar, go to Website Builder → Pages.
  3. Click New Page.
  4. Set the title to “Hello World” and the path to / (the homepage), then click Create.
Set the title and path, then hit Create
  1. You’ll land in the page editor. In the component palette on the left, find the Custom group and drag the Hero #1 component onto the canvas. It renders with placeholder content straight away — no configuration needed for now.
The Hero #1 component dropped onto the canvas, showing a live preview of your Next.js app
  1. Click Publish.

​
Step 7: See It Rendered

Go back to http://localhost:3000 and refresh. You should now see the hero section rendered by your Next.js app. The published page rendered by your Next.js app You’ve successfully rendered your first Website Builder page. Content authored in Kibo CMS Admin, delivered through your own Next.js app — that’s the full loop working end to end.

​
Project Structure

Here’s what’s in the starter kit and what each part does:
Project structure
src/
  app/
    [[...slug]]/
      page.tsx              # Catch-all route — renders every Website Builder page
    api/
      preview/              # Enables Next.js draft mode for Website Builder preview
      redirects/            # Serves redirect rules defined in Website Builder Admin
    layout.tsx

  components/
    DocumentRenderer.tsx    # Wires editorComponents into the SDK renderer
    Header.tsx
    NotFound.tsx
    PageLayout.tsx

  contentSdk/
    initializeContentSdk.ts # SDK init
    groups.ts               # Component group registration
    ContentSdkInitializer.ts # Client component wrapper for SDK init
    getTenant.ts            # Reads tenant ID from request headers
    index.ts

  editorComponents/
    index.tsx               # Register your components here
    Hero1.tsx               # Built-in Hero component

  theme/
    theme.css               # CSS variables + typography classes
    theme.ts                # createTheme() call
    tailwind.css

  utils/
    normalizeSlug.ts

  constants.ts
  middleware.ts             # Handles preview mode, tenant routing, redirects
The two folders you’ll spend most time in are editorComponents/ (building and registering components) and theme/ (styling). Everything else is infrastructure the starter kit handles for you.

​
How the Rendering Works

The starter kit’s catch-all route (src/app/[[...slug]]/page.tsx) handles all page rendering:
src/app/[[...slug]]/page.tsx (simplified)
export default async function Page({ params }) {
  const { slug = [] } = await params;

  // Initialize the SDK with credentials from env vars
  initializeContentSdk();

  // Fetch the published page document from Kibo CMS
  const page = await contentSdk.getPage("/" + slug.join("/"));

  // DocumentRenderer maps component names → your React components
  return <DocumentRenderer document={page} />;
}
initializeContentSdk (in src/contentSdk/initializeContentSdk.ts) calls contentSdk.init() with your env var credentials and registers the component groups. DocumentRenderer takes the page document — a JSON tree of component names and their input values — and renders it by looking up each name in your registered editorComponents array.

​
Troubleshooting

​
Still seeing “Not found!” after publishing

  • Make sure you set the page path to / exactly.
  • Check the browser console for API errors — a CORS or auth error means your env vars may be wrong.
  • Restart the dev server after editing .env.

​
Editor shows a blank canvas

  • Make sure your Next.js dev server is running on http://localhost:3000.

​
Summary

  • The Website Builder editor loads your Next.js app in an iframe — components and styles live entirely in your project.
  • Clone the starter kit and configure the three required env vars.
  • Create a page in the Admin editor using the built-in Hero #1 component and see it rendered in the Next.js app.
  • The catch-all route + initializeContentSdk + DocumentRenderer is how every page gets rendered.