How to Connect Builder.io to Next.js and Ship Faster

November 11, 2026

Connect Builder.io to Next.js by installing @builder.io/react, dropping in a catch-all route, and mapping your own components into the visual editor. Setup takes about 20 minutes and afterwards a marketer can change a landing page without a deploy.

The hosted route gets you a page fast. The SDK route is where Builder.io earns its price — content editors work in the visual canvas, your team keeps components in git, and nobody files a ticket called “can you swap the hero image”.

What do you need before starting?

A Next.js app (App Router or Pages Router both work), your Builder public API key from the space settings, and a page already created in Builder with a URL path like /landing/demo.

Check your Next.js version first. Builder’s SDK tracks recent Next releases; an old 12.x app may need a pinned SDK version. Version mismatch is the number one cause of pages rendering empty in local dev.

How do you install and configure the SDK?

  1. Run npm install @builder.io/react in your project.
  2. Add your public key to .env.local as NEXT_PUBLIC_BUILDER_API_KEY.
  3. Initialize Builder in a client component wrapper.
  4. Create a catch-all route that fetches content by URL path.
  5. Render with the BuilderComponent element, passing the fetched content object as its content prop.

The public key is safe in the browser. Don’t confuse it with the private key, which must never ship to the client — it belongs in server-side env vars only.

How do you fetch content in the App Router?

On the App Router, fetch in the server component and pass the JSON down. Builder exposes a Content API at its REST endpoint; you query by url and the model name (usually page), and pass your API key as a query param.

One practical detail: cache policy. If you set revalidate: 60, published changes appear within a minute. If you set no-store, every request hits Builder’s API, which is slower and burns your view quota faster. Most marketing pages are fine at 60 seconds.

For draft preview you want the opposite — no cache and draft content enabled — gated behind a query param that only your CMS editors know.

How do you register your own components?

This is the part that makes the integration worth doing. Any React component can become an editable block.

Builder.registerComponent(PricingCard, {
  name: 'PricingCard',
  inputs: [
    { name: 'tier', type: 'string' },
    { name: 'price', type: 'number' },
    { name: 'ctaLabel', type: 'string', defaultValue: 'Start free' }
  ]
});

Once registered, PricingCard shows up in the insert panel with those three fields. Editors can drop it anywhere and change price or button text without touching code — and the component still obeys your design system.

Register components in a single file imported once. Scattering registrations across the app causes blocks to appear and disappear depending on which page you’re on.

What breaks in practice?

Two things, repeatedly.

Hydration mismatches. If a registered component uses browser-only APIs during render, Next.js throws a hydration error. Guard with useEffect or a mounted check.

Preview on production URLs. Draft preview needs draft content, which needs the private key, which must stay server-side. Implementing preview as a client-side fetch is the usual shortcut and it leaks the key. Do the draft fetch on the server and pass the result down.

Route Setup effort Editing for marketers Deploy needed
Builder hosted Minutes Yes No
Next.js + SDK ~20 min Yes, on registered components No
Static export Minutes Yes Yes

Who should take the SDK route?

Teams with a component library and a real front-end codebase. Ecommerce and SaaS marketing sites are the sweet spot — you have components, you have deploys, and you want to stop deploying for copy changes.

Skip it if your site is a simple brochure with no build step. The hosted route is enough there, and the SDK adds a dependency you’ll maintain for no gain.

Quick Summary

  • Install @builder.io/react, add a catch-all route, render content JSON with BuilderComponent.
  • Use the public API key in the client; the private key stays server-side for draft preview.
  • Register your own React components with typed inputs so marketers can edit props.
  • Cache content for 60 seconds in production; disable cache only for draft preview.
  • SDK mismatch and hydration errors are the two failures you’ll actually hit.