As a developer, you can integrate Builder into your codebase and give other team members, such as content editors, marketers, and designers, the ability to build and manage pages without ever having to ping you.
This guide is detailed. If you're using React, Next.js, Remix, Angular with standalone components, or Qwik and you'd prefer a more automated process, visit Developer Quickstart, which uses Devtools to integrate for you.
We highly recommend that you integrate Builder into an existing app, and these instructions assume you already have one. However, if you need to create an app, and would like instructions, visit Creating an App.
Want a shortcut? Get going right away with Builder and Next.js; use Builder's Devtools for Automatic Integration. Devtools fully automates your integration, so you don't have to take the steps in the rest of this document.
If you choose not to use the built-in Builder integration with Next.js with Devtools, continue with the instructions below.
At the command line, at the root of your project, use npm to install the Builder SDK:
npm install @builder.io/reactIf you're using Windows, be sure to use quotes when you install dependencies that use the @ operator; for example, npm install "@builder.io/react".
Start the development server:
npm run devIn components/builder.tsx (create this directory and file if needed) and paste in the following code:
// components/builder.tsx
"use client";
import { ComponentProps } from "react";
import { BuilderComponent, useIsPreviewing } from "@builder.io/react";
import { BuilderContent, builder } from '@builder.io/sdk';
import DefaultErrorPage from "next/error";
type BuilderPageProps = ComponentProps<typeof BuilderComponent>;
// Replace with your Public API Key
builder.init(YOUR_API_KEY);
export function RenderBuilderContent(props: BuilderPageProps) {
// Call the useIsPreviewing hook to determine if
// the page is being previewed in Builder
const isPreviewing = useIsPreviewing();
// If `content` has a value or the page is being previewed in Builder,
// render the BuilderComponent with the specified content and model props.
if (props.content || isPreviewing) {
return <BuilderComponent {...props} />;
}
// If the `content` is falsy and the page is
// not being previewed in Builder, render the
// DefaultErrorPage with a 404.
return <DefaultErrorPage statusCode={404} />;
}
Create an app directory at the root of your project if you don't already have one. In app/[...page], create a file called page.tsx and paste in the following:
// Example file structure, app/[...page]/page.tsx
// You could alternatively use src/app/[...page]/page.tsx
import { builder } from "@builder.io/sdk";
import { RenderBuilderContent } from "../../components/builder";
// Replace with your Public API Key
builder.init(YOUR_API_KEY);
interface PageProps {
params: {
page: string[];
};
}
export default async function Page(props: PageProps) {
const model = "page";
const content = await builder
// Get the page content from Builder with the specified options
.get("page", {
userAttributes: {
// Use the page path specified in the URL to fetch the content
urlPath: "/" + (props?.params?.page?.join("/") || ""),
},
// Set prerender to false to return JSON instead of HTML
prerender: false,
})
// Convert the result to a promise
.toPromise();
return (
<>
{/* Render the Builder page */}
<RenderBuilderContent content={content} model={model} />
</>
);
}
Tip: If you don't have an app directory, be sure to create one.
A later section in this tutorial guides you through getting your Public API Key from the Account section of Builder. When you have your Public API Key be sure to add it to the builder.init() method in this code snippet. The API Key is required for connecting your app to Builder.
The BuilderComponent accepts several props for customization. One important prop for client-side routing is renderLink, which means you can implement custom routing. For more information on renderLink and other props, visit the renderLink entry in Using BuilderComponent.
Here's an example of how you might use the renderLink prop:
<BuilderComponent
model="page"
content={content}
renderLink={(props) => <CustomLink {...props} />}
/>
Builder adds the ability for your team members–even those who don't code–to create and iterate on ideas with a drag-and-drop interface.
Go to Builder.io to sign up for an account if you don't already have one. Come back when you're logged in.
This next video covers demonstrates the entire process of following this tutorial. The end result is a local application connected to Builder. This example uses Next.js but all frameworks use the same process.
To connect your Builder.io space to your application, add the Public API key to your code.
Find your Public API Key within Builder.io in one of two ways:
- Press
Cmd/Ctrl+kin Builder to bring up the command palette and search for API Key. Clicking the Public API Key copies it to your clipboard. - Go to Settings and copy your Public API Key.
For more detail about the Public API Key, see Using Builder API Keys.
Paste the Public API Key into your app by replacing the YOUR_API_KEY placeholder in your code. This location varies depending on your framework. Make sure to wrap your Public API Key in quotes.
The following video demonstrates how to copy your Public API Key from Settings and paste it into a Next.js app.
To enable Builder to open your site in the Visual Editor, provide a URL that Builder can open which has the Builder rendering component in it.
- Go to Models and choose the Page model.
- Set the Preview URL to
http://localhost:<your-port>, where<your-port>is the port your app is using. Be sure to include thehttp://. - Click Save.
The following video shows these steps:
Create a Builder Page to use with your integrated app.
- Go to Content.
- Click the + New Entry button near the top right of the screen.
- Create a new Page in Builder.
- The Editor for your new Page loads automatically.
- In your new Page, drag in Builder blocks.
- Click the Publish button in the upper right of the browser.
- After a few moments, your page will be available on localhost. Click the right arrow icon next to the Publish button and choose View live page to visit your page.
The next video shows creating a Page in a Builder-integrated app and dragging in an Image and Text block.
After you deploy your updates, be sure to update this to a public URL, such as your live site or your staging site; for example, https://your-site.com, so anyone on your team can connect to your site for visual editing.
If you're getting a 404 but aren't sure why, check these things:
- Make sure you've published your page in Builder by clicking the Publish button on the upper right corner.
- Check the URL. If you name the page
test2for example, Builder adds a hyphen, so that the URL segment istest-2. - Make sure that you've set the preview URL on the Page Model.
- For some frameworks, you might have to restart the dev server.
For more information regarding special use cases, visit Integration Tips.
We recommend that you place your Builder pages between your header and footer. A common use case is developers keeping headers and footers in their codebase while integrating page building. In this way, non-developer team members can iterate on pages, without having to rely on developers.
To use Builder pages between your header and footer, follow the guidance below for your framework:
Import your header and footer along with the other JavaScript imports at the top of [...page].jsx.
Add the header and footer components before and after BuilderComponent.
+ import MyHeader from '../components/my-header'
+ import MyFooter from '../components/my-footer'
export default function Page({ page }) {
...
return (
<>
<Head>
<title>{page?.data.title}</title>
</Head>
+ <MyHeader />
<BuilderComponent model="page" content={page} />
+ <MyFooter />
</>
);
}
With your app and Builder working together, the next step is the fun part–add some pages in Builder and drag in some elements. Play with styles and explore the UI.