Builder environments

Builder supports multiple environments within a space. The default environment of a space is called Main, and additional environments are referred to as "child environments". Additional information about environments can be found in Builder's official documentation.

Environment hierarchy

In a typical setup, Main represents production, while child environments may represent development, QA, staging, etc. Child environments are considered siblings in the sense that Builder.io itself doesn't distinguish between them—for example, "staging" would not be a parent environment of "development".

Sync between environments

By default, live sync is enabled in all environments. This means that models and content created in Main are automatically created and updated in all child environments. During development, model and content creation can be done safely in a child environment without impacting the production website. To make changes to existing models or content, you must first unlink them, make the necessary changes, and then push them when they are ready for production. This process can be done in stages (Development → Test → Staging → Production) if multiple environments are available.

Caveats

It is often the case that some content in an environment will refer to entities that exist outside Builder.io itself—for example, a piece of content pointing to a product category in a PIM system, a page component referencing an image in DAM, or data from other external systems. When this content is pushed to a different environment, it retains the original reference to the respective entity in the PIM, DAM, etc., which may not exist or be the same in the destination environment. In such cases, unless mechanisms are in place to ensure data consistency between environments, the content will need to be adjusted manually in the destination environment.

To minimise manual intervention, we recommend the following practices:

Bizzkit DAM file plugin

The data produced by the plugin includes a field called filePath, which can be used in combination with the GET /api/{culture}/files/by-path endpoint in DAM to look up the fileId associated with that path. This provides reliable fallback behaviour, as long as the files are named the same and are placed within a folder structure with the same name.