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.
This document covers the following:
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
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.
To set a preview URL that persists until refresh or until you leave the space but doesn't affect the rest of your team or company, 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 throughout the space. You can navigate out of the Visual Editor and the URL remains. However, when you refresh the browser the preview URL resets.
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 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 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.
Looking to hire a third 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.
