How Builder Works (Technical Overview)
Overview
Builder allows non developers to create and manage parts of your site or app that you allow. We pass data to your site or app using our various SDKs and APIs.
We do not host your site for you, but give 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.
You control the structure of your site with models. You can customize where content of each model loads, how it is targeted and filtered, and where and how it is rendered.
See this guide to learn how to integrate Builder into your site or app.
Comparing to a traditional headless CMS
In many ways, Builder works the same as any headless CMS, and our CMS data models work identically.
So similar to a headless CMS, you create entires including with structured custom fields (or targeting). You can then query via these fields and display the content you desire, where you desire.
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. Optionally, you can also restrict builder editing to only these components (with or without allowing custom styling) using components-only mode and/or roles and permissions.
Besdies visual editing, Builder also adds additional features that are less common in traditional headless CMSs, such as content targeting and analytics.
And also don't get us wrong, structured CMS data has its purpose to. 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 is the data 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 we provide, like
For pages and sections, we automatically populate a field called blocks that is a list of components to render and their options.
We pass this data to your site or app via our various APIs, and you can load it into your site as HTML or rendered dynamically via this JSON with frameworks such as React.
How does the visual editor work?
Our editor loads your site in an iframe. You need to provide the URL for our editor to open. This page will need to have a Builder SDK integrated so we can discover where it is, any settings provided, and pass messages to it.
When a Builder SDK sees it is loaded in our editor, instead of showing the default content, it waits on a message from the Builder webapp of what content to display. We message down the JSON and send patches as edits are made of what to render differently (component added, input changed, etc) and the SDK will render the updates accordingly
You can also register your own components to be used in the editor. When you do this Builder keeps a map of component names to references, and messages the webapp what components exist and what inputs they take. Under the hood, the built in components (like Image, Text, Columns, etc) work the same way and are open source
Internally, we keep a map like:
And then when we render the content for you, we iterate over the blocks and render the components and inputs via your farmework/SDK of choice, like:
You can see examples on how to implement your own rendering for any language or framework here
How does the real time preview work?
Builder.io loads your website in an iframe in our web application.
When your page loads in our web app, any Builder component on your page will send a message to us notifying that it has been found. This will only occur for a matching component - for instance if you are opening a page to edit your page model, we wait for a message from a component whose model is page. Once received, Builder sends a message down for what content should be rendered for the preview.
As you click around and make edits, Builder continuously passes messages down to this component telling it what new changes should be reflected.
If Builder never receives a message from a component of the model type you are trying to edit, we don'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.
Hosting
Builder pushes content to your site or app via APIs. You control your site, code, and hosting - we only pass content within your own setup for you
Can I extend Builder functionality with my own code?
Absolutely. Besides being able to register your own components in the editor and change settings, you can also customize Builder deeply via plugins
How is Builder structured?
Builder is structured by models. You can make models for Pages, Sections, and Data
Structuring your site
One of the easiest ways to get started is to add landing page building to your site. Once you have that, you can start adding editable sections across your site, and use targeting to choose the right content for the right users
Here are some examples we recommend for how to structure various pages on your site
👉Tip: See here for a full recommendation on how to structure your site with Builder
Where can I get integration help?
