When you've integrated your app with Builder, you can edit and preview your site using a preview URL. Setting a preview URL gives you a way to develop and preview your site in the browser, just as you would any other site.
Tip: If you are using the HTML API to serve Builder content, follow the steps in the Previewing content on your site section of Builder HTML API to set up previewing for your content.
To get the most out of this document, you should have already completed the following:
- integrated page building or section building
You can set a preview URL on a Page, Section, or Data model. Using a preview URL on any model gives you a way to render content and data to preview Pages, Sections, or Data while you're working.
Tip: With the Builder's React SDK, you can use live editing to render Data changes in real time. For configuration instructions, read the Usage with Data Models section of the React SDK readme on GitHub. If you aren't using the React SDK, you can still preview your data model. Once published, the changes will be reflected in the Visual Editor preview.
When you're still building out your site before going live, you need to work locally for extended periods with the convenience of a persistent preview URL. In this scenario, you can set the preview URL on the model so that all content using that model is automatically configured with the preview URL.
For example, if you're creating pages and need to preview all pages on localhost, you can set the preview URL on the Page model to localhost so that all Page content has that preview URL of localhost.
When your site is ready to go live, change the URL on the model to your staging or production URL.
The following video demonstrates opening a model and setting the URL.
Important: If you change the preview URL of a model from, for example, a live URL that is in production to localhost, any content using that model will no longer be live and all parts of your app using that model will be affected.
If you need to set the URL on the model, you must be certain that no published content is using that model.
When developing your app, you can set a temporary preview URL that resets upon refresh or if you leave the Visual Editor.
The following video shows how to click on the preview URL in the Visual Editor and edit it. This method is helpful if you're working on a page that is currently in production but that you would like to develop further. In this example, the preview URL is http://localhost:3000/test-page; that is, the localhost with the name of the page url, here, /test-page.
When you need to test out new changes or components in your local code across multiple content entries or models, it can be handy to override your preview URL host (e.g. from your production host, like your-site.com, to your localhost) for the duration of your session.
This can save you from entering a temporary URL repeatedly as you move across content models or entries, when you want to be connected to your localhost throughout.
To set a preview URL temporarily for just your session, without affecting other teammates, use the Developer Options as follows:
- In the Visual Editor, press
Cmd+Ctrl+aor⊞ Win+Ctrl+ato open the Developer Options. You must have Admin or Developer permissions to open this dialogue. - In the Override preview URL host field, enter the preview URL you'd like to use. This example uses
http://localhost:4200, but your URL might be different. - Click the X to close the dialogue.
This setting takes effect for the duration of your session, or until you remove it.
Setting the URL in Developer Options only affects the user who changes this setting, not other developers, teammates, or site visitors.
The following video demonstrates using Developer Options to set the preview URL to localhost.
When working on static sites, such as with Gatsby, Nuxt, or Next.js in static mode, there is some additional configuration you might need to do to get your preview URL to render previews.
By default, when creating a page and editing it in Builder, the editor and preview loads the URL for that page. For example, if you create a new page at /example but your static site has no such page, you could get a 404. There are two options for this scenario:
If you're getting a 404, add the Builder component to your 404 page to support previewing and editing.
On your 404 page in your code base, add <BuilderComponent> as in the following code snippet. In this example, if the page isn't found, BuilderComponent still returns a Builder page, so Builder gets the message it expects and returns a page.
import { Builder, BuilderComponent } from '@builder.io/react';
export function NotFoundPage() {
if (Builder.isPreviewing || Builder.isEditing) {
return <BuilderComponent model="page" />
}
return <Your404Page />
}To turn off the default behavior of previewing and editing on the specific URL for a page, do the following.
- Go to Account Settings > Advanced Settings > Advanced.
- Toggle Reload preview on URL path change to the off position.
You can turn off this setting to load the preview and editor on your hardcoded URL; for example, /builder-editing, regardless of the current editor path.
The following video demonstrates how to turn off the Reload preview on URL path change setting:
You can add logic to Page and Section models to dynamically create the preview URL. For example, you can use a snippet like the below to preview blog posts:
// Check to see if the content is live. If so,
// use your site's URL followed by the
// dynamic path you specify.
if(contentModel.isLive) {
return `https://your-site.com/your-directory/${content.data.slug}`
}
// If the site's not live, use a placeholder URL
return `https://your-site.com/your-directory/__builder_editing__`You can customize the Dynamic Preview URL logic on a model so that you can use features such as targeting, custom fields, and localization while previewing. For more details, refer to Dynamic Preview URLs.
If you've integrated and followed all the instructions above but your iframe contents still aren't loading, check out Getting Your Preview URL Working.
