In this lesson, 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.

Prerequisites:

• A running Webiny project (completed via the Getting Started chapter, or already deployed)
• Node.js 20.9+ and npm/yarn installed (Node.js 24+ still required for Webiny CLI — if you're only working with the Next.js side, 20.9+ is sufficient)
• Familiarity with Next.js App Router — the starter kit uses App Router, not Pages Router

How It All Fits Together

Before we start writing any code, it's worth taking a moment to understand 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 Webiny 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.

Click to enlarge

On the developer side, the picture is a bit 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 our 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. Webiny 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.

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 Webiny when rendering pages for visitors.

With that in mind, let's get everything set up.

Step 1: Start the Admin App

You'll need the Webiny Admin app running before creating pages later in this lesson. Get it going now so it's ready when you need it.

• Locally: run yarn webiny watch admin in your Webiny project directory.
• Deployed environment: use the Admin CloudFront URL directly — no local command needed.

Step 2: Clone the Starter Kit

Webiny provides starter kits that wire up the SDK, routing, and rendering so you have a working base to build from. At the moment there is a Next.js starter kit, with more frameworks planned. The official Next.js starter kit lives at github.com/webiny/website-builder-nextjs.

Before running npm install, make sure the @webiny/website-builder-nextjs and @webiny/sdk versions in package.json match your Webiny version. You can find it by running webiny --version in your Webiny project.

For example, if your Webiny version is 6.2.1, your package.json should have (the ~ allows patch updates, which are safe):

Step 3: Gather Your Credentials

To connect the starter kit to your Webiny 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 Webiny Admin — click Support in the bottom-left corner and select Configure Next.js.

Click to enlarge

A dialog appears with the three environment variables already filled in and ready to copy:

Click to enlarge

Click the copy icon and paste the block directly into your .env file in the next step.

API Key Is Auto-Created

Note that unlike the Headless CMS chapter where you had to 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 Configure Next.js dialog pulls it for you, so there's nothing to set up manually.

Click to enlarge

Step 4: Configure Environment Variables

Create a .env file in the root of your Next.js project:

Step 5: Start the Dev Server

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.

Click to enlarge

Step 6: Create Your First Page

1. Open your Webiny 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.

Click to enlarge

6. 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.

Click to enlarge

7. 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.

Click to enlarge

You've successfully rendered your first Website Builder page. Content authored in Webiny Admin, delivered through your own Next.js app — that's the full loop working end to end.

Project Structure

Now that we've successfully rendered a page end-to-end, let's dive into a bit more of the technicalities — what's in the starter kit and what each part does:

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:

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.
• Cloned the starter kit and configured the three required env vars.
• Created a page in the Admin editor using the built-in Hero #1 component and saw it rendered in the Next.js app.
• The catch-all route + initializeContentSdk + DocumentRenderer is how every page gets rendered.

Next lesson: Learn how editor components work and how to register your own.