This document provides a collection of tips and solutions to help you integrate with Builder effectively. It covers common scenarios such as resolving API key mismatches, fixing model name discrepancies, handling common errors and enabling data-bindings in Node environments.
If you get a message in the Visual Editor that there's an API Key mismatch, it means that Builder and your codebase are using different API keys.
Check the API Key: Since each Space has its own Public API Key, if you have more than one Space in your Organization, make sure you are using the Public API Key for the intended Space.
Verify the API Key in Builder: To confirm that you're using the correct Public API Key, check that the API Key in your codebase and the Public API Key in Builder for the intended Space are the same.
If you get a message in the Visual Editor that there's a model name mismatch, it means that the Builder model name and the code component name in your codebase aren't the same.
To confirm that you're using the correct model name:
If you encounter situations where changes you make to your content don't appear in the preview immediately, you may need to adjust your integration code.
Try the following solutions to see if any solve your issue.
If using Next.js, you may notice that your content changes do not show up on your website as quickly as you might like after publishing in Builder. This is due to the caching strategies Next.js uses by default. If you are experiencing this issue, consider modifying your Next.js cache settings.
For example, the following code changes the behavior of the request from indefinitely caching fetch calls to caching for 5 seconds.
See the Next.js documentation, particularly Caching in Next.js, to learn how to modify those settings. There you will find information on Opting Out from caching fetch request responses and Opting Out of Full Route Cache.
If published changes don't appear on your live site, it may be due to caching issues rather than a problem with Builder.
Builder publishes content to its API immediately. Delays in displaying changes are typically due to caching at the hosting provider level or within your application's caching strategy.
Work directly with your hosting provider to adjust caching for your deployed application. Some common guides are included below:
In certain Node server environments, the builder SDK may require additional initialization steps, namely the initialization of a package called isolated-vm (used to safely evaluate your data bindings).
On Apple Silicon Macs using Node v20, isolated-vm can crash and break SSR in local environments. To prevent this, prepend NODE_OPTIONS=--no-node-snapshot to your start, dev, and build scripts. Production environments are not affected.
If you're using Builder's Gen 1 SDKs and data binding on a provider with edge workers, such as Cloudflare, Netlify, or Vercel, you might encounter a situation where certain dependencies are automatically removed in their ISR (Incremental Static Regeneration) functions.
Two indicators can help identify this issue:
Hydration errors—where the SSR and the client side version are different—because the data binding did not execute on the server side.
Missing data that populates on the client side; that is, the data binding is not executing on the server side.
This can lead to a failure with the function safeDynamicRequire. In such cases, consider applying the following workaround.
In the pages/_document.jsx file or any server-only execution location, add the following code:
import ivm from 'isolated-vm'
import { Builder } from '@builder.io/react'
const isolate = new ivm.Isolate({ memoryLimit: 128 });
const context = isolate.createContextSync();
Builder.setServerContext(context);
If there's no _document.tsx file in the project, you can add the code anywhere but wrap it with this condition:
if (Builder.isServer) {
// Add the provided code here
}
This workaround should prove helpful when using Builder's Gen 1 React SDK on the server side with Vercel or similar platforms where automatic dependency removal might cause issues.
In your _document.tsx —or any other code block that only executes on your server — add the following:
In your page.tsx that is responsible for rendering your Builder content, import isolated-vm at the start of the Page component:
export default async function Page(props) {
// import must be inside the Page component
await import('isolated-vm');
//...the rest of your component logic
}
In your next.config.js, add isolated-vm to the list of serverExternalPackages :
In your Remix route's loader that is responsible for fetching the page content from Builder.io (or any other code path that only executes on the server), import "@builder.io/sdk-react/node/init" and call initializeNodeRuntime():
To make sure that initializeNodeRuntime() is imported and executed only in your server code, and not included in your browser bundle, you need to configure it according to your specific server and web application setup.
Here's an example that shows how to render Vue using an Express server:
In your Nuxt project, you can use the @builder.io/sdk-vue/nuxt module. Set initializeNodeRuntime to true to automatically handle the import and execution of initializeNodeRuntime() for you.
If you prefer more control over the import and execution of initializeNodeRuntime(), you can manually call it in a server-only environment. This approach means you can import initializeNodeRuntime() from the @builder.io/sdk-vue/node/init entry point and use it as needed in your server code.
1. Initialize Node runtime: In your entry.ssr.tsx — or any other code block that only executes on your server — add the following to ensure proper initialization:
// entry.ssr.tsx
import {
renderToStream,
type RenderToStreamOptions,
} from "@builder.io/qwik/server";
import { manifest } from "@qwik-client-manifest";
import Root from "./root";
import { initializeNodeRuntime } from "@builder.io/sdk-qwik/node/init";
initializeNodeRuntime();
export default function (opts: RenderToStreamOptions) {
return renderToStream(<Root />, {
manifest,
...opts,
// ...
});
}
2. Add isolated-vm as an external dependency: To handle the isolated-vm package, which helps safely evaluate data bindings, declare it as an external dependency in your Vite configuration, especially if you're using adapters like Azure:
3. Include the installation of isolated-vm: since Qwik doesn't automatically add dependencies to the package.json generated for Node environments, include isolated-vm in your build.server pipeline by updating your package.json:
4. Run the build command: After updating package.json, run the following command to ensure the dependencies are included:
npm run build.server
This adds the isolated-vm package to your node_modules and include it in your server build. This ensures that all necessary dependencies are available when you deploy the app.
Avoid naming a data prop key state. If you pass state as a property name inside the data object—for example, data=undefined—it conflicts with Builder's internal state handling and causes bindings to fail silently. Use a different key name.
Chrome 142 introduced a new security feature that restricts websites from accessing your local network. When Builder's Visual Editor first attempts to connect to your localhost URL, Chrome displays a permission prompt asking you to allow or block local network access. If you select block, the Visual Editor cannot connect to your local development server.
This restriction is part of Chrome's security measures to protect against cross-site request forgery (CSRF) attacks targeting local network devices. For more information, see Google's announcement: New permission prompt for Local Network Access.
