How to debug a publish or optimization warning
If you are publishing your site, there are two types of errors you can get.
Publishing Error
This will show a toast: “Failed to publish because there is an error on a page” with a Review button.
⚠️ Publishing errors are almost always due to code in custom components, either created by you or by a component author (like something you used from the insert menu).
Clicking the review button will send you to a page that has an element with an error. There are a few common reasons that publishing can fail that we're looking for:
Dynamic runtime errors. The compiler that builds the site was waiting on a component to finish building in time, which it didn't. Unfortunately this only provides errors in the web inspector ("ensureComponentsInLoader: Component loader not updated in time."). You can often fix this by just retrying, but otherwise you'll have to fix or remove the component.
Could not find a used component. Sometimes a component has gone missing due to a file or function rename, or simply a networking loading error. The review button will take you to the missing component (and it will be marked with an alert in the layer panel). The component will have a grey error placeholder. You will need to fix or replace the component.
Optimization Error
Framer sites are built in React, which means that without optimization, the visitor would see a blank page until React loads and renders the site. With optimization, we “pre-render” the site on our servers. The visitor will see the pre-rendered version immediately, while React continues loading in the background. This is also very important for SEO: without optimization, your website might appear empty to search engines.
Optimization happens after you publish your site, and you can track its status in Settings → Domains, or Settings → Versions.
If you see a Warning, this means that one or more pages failed to optimize. You can find the actual error in Settings → Domains under the ... menu, or in Settings → Versions by clicking on the “Warning.”
⚠️ Note: If Download Error File is not available, this means an unexpected problem during optimization. If the problem persist as you keep publishing, contact support and we can help you out.
How to fix optimization errors
The most common reasons for optimization issues are custom code components or overrides that rely on things (APIs) that are only available in web browsers.
When we pre-render pages on our server, we need to make sure that the pre-rendered version will work regardless of what browser the visitors might be using. We don’t know the size of their windows, their language settings, etc., so … we pre-render without a browser at all. That means things like window, document, navigator, etc. are not available, and if custom code relies on them for rendering, it’ll crash.
🥇 The best way to fix these errors is to write JavaScript that doesn’t rely on browser APIs for rendering. For example, instead of using window.innerWidth, use CSS media queries, etc.
🥈 But what if you need to customize your components based on e.g. the user’s logged-in status (document.cookie) or navigator.language? Again, when we pre-render the site, we don’t know these things, so you’ll need to write a component that renders some kind of placeholder while the page is loading, and updates its status after the page loads. Here’s an example:
🥉 You could also completely “opt out” your component from optimization by doing:
Just keep in mind that the component’s content won’t be accessible to search engines, and it’ll “pop in” after the page loads. Coming up with a nice placeholder might be a better idea.
You can use the same trick in your overrides:
Nested links & CSS errors
Your pages can also fail to optimize because of nested links or CSS errors. See:
Packages
Sites don’t support packages (an older code distribution system we had before modules). It should never happen, but if a package made it to your site you will get server side rendering errors like:
Error: Framer Store package @framer/framer.default/Icon.js cannot be used outside of Framer