How to debug a publish or optimization warning


How to debug a publish or optimization warning

When publishing your site, there are two types of errors you may encounter.

Publishing error

A toast will be displayed saying: “Failed to publish because there is an error on a page.” The toast will also include a Review button.

Publishing errors are typically caused by code in custom components, whether they were created by you or by a component author (such as one you used from the insert menu).

When you click the review button, you will be directed to a page that contains an element with an error. There are a few common reasons for publishing failures that we investigate:

  • Dynamic runtime errors: The site compiler was waiting for a component to finish building within the given time, but it didn't. This usually generates errors in the web inspector, such as "ensureComponentsInLoader: Component loader not updated in time." You can often resolve this by retrying, but if that doesn't work, you'll need to fix or remove the problematic component.

  • Missing used component: Sometimes a component is no longer available due to a file or function rename, or due to a networking loading error. Clicking the review button will take you to the missing component, which will be indicated by an alert in the layer panel. The component will be displayed as a grey error placeholder. You will need to fix or replace the component.

Optimization error

Framer sites are built in React. Without optimization, visitors would see a blank page until React loads and renders the site. Optimization involves "pre-rendering" the site on our servers. This allows visitors to immediately see the pre-rendered version while React continues to load in the background. Optimization is crucial for SEO as it ensures that your website is not empty to search engines.

Optimization occurs after publishing your site. You can check its status in Settings → Domains or Settings → Versions.

How to fix optimization errors

The most common cause of optimization issues is using custom code components or overrides that depend on web browser-specific APIs.

When we pre-render pages on our server, we must ensure that the pre-rendered version works correctly regardless of the visitor's browser. Since we don't have information about their browser settings, window size, etc., we pre-render without a browser. This means that APIs like window, document, navigator, etc. are unavailable, and if custom code relies on them for rendering, it will cause errors.

The best solution to these errors is to write JavaScript that doesn't rely on browser APIs for rendering. For instance, instead of using window.innerWidth, use CSS media queries.

But what if you need to customize your components based on the user's logged-in status (document.cookie) or navigator.language? In this case, when pre-rendering the site, we don't have this information. Therefore, you need to write a component that displays a placeholder while the page is loading and updates its status after the page has loaded. Here’s an example: framer-optim-1.jsx

You could also completely “opt out” your component from optimization: framer-optim-2.jsx. Note that the content of the component will not be accessible to search engines. It will appear after the page has finished loading. It might be a good idea to create a placeholder instead. You can use the same trick in your overrides: framer-optim-3.jsx

Nested links

Your pages may fail to optimize due to nested links. Please refer to the following article: How to fix nested links