Menu
How to wire a new Builder.io-rendered route or model — fetch helper, route, registry, config.
How to move an app component into the headless @jasonyangcis/core-ui library — headless conversion, cross-repo file checklist, treeshake sentinel, changeset, consumer wiring.
Pattern for adding a server Route Handler under app/api/** — origin check, zod body, server-only deps, safe responses.
Builder.io Gen-2 SDK patterns — fetch, render, register, model guard, preview.
Tokens, cn(), focus rings, shadcn/ui (new-york), insert-menu groups.
TS strict, four-file folder pattern, import boundaries, no console.
Secret hygiene, CSP, CSRF, webhook HMAC, session encryption.
| name | builder-page-wiring |
| description | How to wire a new Builder.io-rendered route or model — fetch helper, route, registry, config. |
Wiring a new Builder model into an App Router route is a 4-file change. Follow this order so you don't forget a step:
config.ts — add the model name under config.models.<key>. Never reference the raw string elsewhere.lib/builder/client.ts — add a typed getBuilderX(...) helper that calls fetchOneEntry({ model: config.models.X, apiKey: config.apiKey, userAttributes: { urlPath, ...targeting } }). This file is server-only.app/<route>/page.tsx — async server component with:
export const revalidate = 5;params is a Promise in Next 16 — const { handle } = await params;if (!content) notFound(); (only on Builder-only pages — for hybrid pages like the PDP, just skip rendering when null).<RenderBuilderContent content={content} model={config.models.X} /> — never <Content> directly.metadata via generateMetadata from Builder data.title / data.description when applicable.builder-registry.ts — register any new custom components used inside this model with full input schemas. Use registerInsertMenu from utils/register-insert-menu.ts to group them in the Builder editor.For preview support, do NOT add per-route preview logic — app/preview/page.tsx already handles every model via getBuilderSearchParams. Just make sure the model name resolves through config.models.
For HTML-typed Builder fields, route through utils/sanitize-html.ts before rendering. Never dangerouslySetInnerHTML directly.
Canonical examples: app/[...page]/page.tsx (pure Builder) and app/products/[handle]/page.tsx (hybrid Shopify + Builder section).