How Builder works (technical overview)

👉Tip: We recommend first reading our high level overview of Builder for the foundation that this builds on

How is Builder structured?

Builder is structured by models. You can make models for Pages, Sections, and Data

Try it out

Use Pages to Build to manage entire pages, like:

Homepage
Content pages (about, partners, etc)
Blog pages
Landing pages

Try it out

Use Sections to Build and parts around your site or app

Announcement bars
Product detail descriptions
Collection heros
Cart upsells

Use targeting to show different content on different pages and to different users

Learn more

Use Data to control structured data like

Navigation links
Product data
Blog post authors

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

How is the data structured?

Builder uses a simple JSON data structure like the below. It is a tree of "blocks" which are the components our SDKs will render for you with the options provided in the UIs

{ 
  "blocks":  [
    {
      "component": {
        "name": "Text",
        "options": {
           "text": "Hello world!"
        }
      }
    }
  ]
}

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

// This code is in your app. Can be the same components you already use
import { Builder } from '@builder.i/react';

const Heading = (props) => <h1>{props.text}</h1>

Builder.registerComponent(Heading, {
  name: 'heading',
  inputs: [{ type: 'string', name: 'text' }]
})

Internally, we keep a map like:

const componentMap = {}
componentMap['heading'] = Heading

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:

// Simplified example

export const BuilderComponent = (props) => (
  props.blocks.map(component => {
    let Component = componentMap[component.name]; 
    return <Component {...component.options } />
  })
)

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 funtionality 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

Where can I get integration help?

Besides taking a look at our docs and SDKs - if you are ever stuck, post your Qs to our forum and our technical team will help you out!

Was this article helpful?