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.
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.
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.
Like a headless CMS, you create entires with structured custom fields or targeting. You can then query via these fields and display the content you want, where you want.
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.
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.
In addition to visual editing, Builder also adds additional features that are less common in traditional headless CMSes, such as content targeting and analytics.
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:
React SDK:
Vue SDK:
Qwik SDK:
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.
Hosting
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
In addition to being able to register your own components in the editor and using Components-only mode, you can also Extend the Builder UI with plugins for deep customization.
How Builder is structured
Builder gets its structure from models. You can make additional models for Pages, Sections, and Data, and customize them with custom field types as well as plugins.
Visual Pages
Use Pages to manage entire pages, such as:
- Marketing and content pages
- Landing pages
CMS Data
Use Data to manage structured data, such as:
- Navigation links
- Product details
- Blog post authors
Structuring your site
By adding landing page building to your site, you can create editable sections across your app and use targeting to choose the right content for the right users.
The following image illustrates some examples we recommend for structuring various pages on an e-commerce site:
Home Page
- Builder manages full homepage
- Optionally target features such as purchase history.
Collection Page
- Builder hero section targeted by collection
- Your code manages the products
Product Page
- 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
Cart Promotion
Promotion and cross-sells targeted by cart contents
Announcement Bar
Target content by URL and audience
Navigation Links
Use a data model to define the links and text
Getting integration help
In addition to taking a look at our docs and SDKs, you can always post questions on the Builder forum where Builder's technical team is available to help you out.
Next steps
For more information on structuring your app, see:
- Builder Best Practices: pointers on how to use the Visual Editor. Great for non-developers on your team.
- Architecture Best Practices: guidelines for how to structure your app and decide what goes in Builder and what goes in your code.
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.