How Builder Works: A Technical Overview
With Builder, you determine which parts of your app that non-developers can create and manage. Builder passes data to your site or app using various SDKs and APIs.
The images below show how you:
- Add a little code to your app
- Use Builder to add drag-and-drop
- Click the Publish button to make your content live
Builder doesn't host your site for you, but gives you the tools to dynamically load content created in Builder into your code. You have complete control as to what you want to be Builder-editable and where.
To get up and running with an integrated app, see the Developer Quickstart.
Comparing to a traditional headless CMS
In many ways, Builder works the same as any headless CMS, and Builder's CMS data models work identically.
In many cases with Builder, the main difference is instead of hard coding a page layout, you have a Builder renderer component render the content dynamically, optionally using components from your codebase.
The next image shows how integrating your app can remove hard-coded content best maintained by other roles on your team, such as marketers, and copywriters.
Structured CMS data has its purposes, and while it often isn't the best for things like pages and layouts, it can be great for a number of other use cases that structured data can be more ideal than pure visual editing.
How the data is structured
Under the hood, Builder is a headless CMS like any other. You can create documents with structured data fields and consume these via our SDKs and APIs and render the data as you choose.
On top of this, Builder adds even more power by letting you register components that can render dynamically, saving you from having to write all of this logic manually. Instead, you can pass the data to a render Builder provides, such as in the following snippet:
For pages and sections, Builder automatically populates a field called
blocks that is a list of components to render and their options, as in the following snippet:
Builder passes this data to your site or app via various APIs, and you can load it into your site as HTML or rendered dynamically via this JSON with frameworks such as React.
Performance is top priority
All content is delivered from the edge, renderable server-side or statically, and we optimize the heck out of it. And our SDKs are small and mighty.
Importantly, there are no hacks here—no iframes, no unneeded client-side code or rendering. Builder's guiding principle is that we produce content just as if you'd written it by hand. Assets are optimized, DOM is minimized, and it's all native to your framework. That is, if you use React, all components are React, and so on, for each framework.
Some example SDK sizes from Bundlephobia are:
Or for instance, take a look at the perf of the Builder.io site, which is built completely in Builder:
How the Visual Editor works
The Visual Editor loads your site in an
iframe. You provide the URL for the editor to open. This page needs to have a Builder SDK integrated so Builder can discover where it is, any settings provided, and pass messages to it.
When a Builder SDK is loaded in the editor, instead of showing the default content, the SDK waits on a message from the Builder web app of what content to display. Builder messages down the JSON and send patches as edits are made of what to render differently—such as added components or changed inputs—and the SDK renders the updates accordingly.
You can also register your own components to use in the editor. When you register your own components, Builder keeps a map of component names to references, and messages the web app what components exist and what inputs they take. Within Builder, the built-in components—such as Image, Text, and Columns—work the same way and are open source.
Internally, Builder keeps a map such as this one:
And then when Builder renders the content, Builder iterates over the blocks and render the components and inputs in your framework/SDK of choice, as in the example below:
You can see examples on how to implement your own rendering for any language or framework in this forum post.
How the real-time preview works
Builder.io loads your website in an
iframe in Builder's web application.
When your page loads in Builder's web app, any Builder component on your page sends a message to Builder notifying that it has been found. This only occurs for a matching component; for instance, if you are opening a page to edit your Page model, Builder waits for a message from a component whose model is
Page. Once received, Builder sends a message for what content should be rendered for the preview.
As you click around and make edits, Builder continuously passes messages to this component telling it what new changes to reflect.
If Builder never receives a message from a component of the model type you are trying to edit, Builder doesn't know where or how to preview your content, so you need to ensure the right component loads on the right page. See our troubleshooting section for more info.
Builder pushes content to your site or app via APIs. You control your site, code, and hosting—Builder only passes content within your own setup for you. The following diagram shows that Builder as a visual layer that integrates with your front end code, and isn't involved in hosting.
Extending Builder functionality with your own code
How Builder is structured
Structuring your site
The following image illustrates some examples we recommend for structuring various pages on an e-commerce site:
- Builder manages full homepage
- Optionally target features such as purchase history.
- Builder hero section targeted by collection
- Your code manages the products
- Your code manages image gallery and product options
- Builder section for product info, targeted by product (optional)
- Builder section for product editorial, targeted by product type
Promotion and cross-sells targeted by cart contents
Target content by URL and audience
Use a data model to define the links and text
Getting integration help
Looking to hire a 3rd party to help with your project?
Submit a project request and our partnerships team will reach out to connect you with an Expert from our partner ecosystem.