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

This will happen after publishing, when we try to pre-render your site on the server. Your published version will have a Warning label under Settings → Versions or in the Publish Sheet.

Versions with Warning will just work as usual, but not be pre-rendered into static html. That means that your site will load slower and won’t be as optimized for SEO.

You can find the actual error in Settings → Domains under the ... menu. It will contain an error stack from our server trying to render your site to html (using React renderToString()).

⚠️ Note: If the download error file is not available, the pre-rendering process likely timed out on the server (after 30s). Contact support and we can help you out.

How to fix optimization errors

The most common reasons for failing are custom code components that use code that might rely on things not available in our server environment (Node.js). This typically results in an error that window , document or navigator (or any of their properties) is not defined, because they simply don’t exist on the server.

You can simply fix these errors by making window , document or navigator conditional. You can write a simple browser check like this:

https://gist.github.com/koenbok/e02a078e90c5ac7a5c1327c7960e4629

⚠️ Note: Some server side rendering systems actually mock or fake the window object so that some things work without making the code explicitly check for it. But it’s considered bad practice because:

The mocked methods often cannot provide a sensible result on the server, for example there is no window.innerWidth because there is no actual window and you can’t check if it’s a mobile device with navigator.userAgent because it’s a server.

Because you can’t mock everything it becomes very hard to know what you can rely on server side. The explicit rule that nothing is supported is much easier.

Skip Server Side Rendering

Sometimes, you can’t edit a component to fix it like above because you don’t own it; for example with a npm module that you use or external library. In that case, you should skip rendering the component server side so it only renders client side.

Let’s say we have a component that we use called WontEverWorkWithSSR that is imported from somewhere and can’t work server side, but we still want to use it:

https://gist.github.com/koenbok/93c5c55de7041afd4a5d385d31fdac14

This will throw the following optimization error (because window does not exist on the server) after publishing:

Pages that failed to optimize:

### Home ReferenceError: window is not defined import-map:

<https://framerusercontent.com/modules/GCFoT7BoEJDeJSxLzpBE/wrmI4ekO6ljcYPjpDpKG/NoSSR.js:5> const size = `${window.innerWidth} x ${window.innerHeight}`; ^

So we want to skip rendering the component on the server side. For that we can simply make a small utility that you can use to wrap the component that doesn’t work on the server:

https://gist.github.com/koenbok/1e06fc2f3c8eb20f8581a20cbd550fbd

Now your optimization errors will be gone and your component will still work as soon as the page is loaded on in the browser.

Overrides

Overrides are similar to components; avoid the use of window, document, etc.

More Context

Server side is great but this can be an annoying issue that nobody really solved yet. You can see how other frameworks solve this and copy an approach that works for you: Advanced Features: Dynamic Import | Next.js

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

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

This will happen after publishing, when we try to pre-render your site on the server. Your published version will have a Warning label under Settings → Versions or in the Publish Sheet.

Versions with Warning will just work as usual, but not be pre-rendered into static html. That means that your site will load slower and won’t be as optimized for SEO.

You can find the actual error in Settings → Domains under the ... menu. It will contain an error stack from our server trying to render your site to html (using React renderToString()).

⚠️ Note: If the download error file is not available, the pre-rendering process likely timed out on the server (after 30s). Contact support and we can help you out.

How to fix optimization errors

The most common reasons for failing are custom code components that use code that might rely on things not available in our server environment (Node.js). This typically results in an error that window , document or navigator (or any of their properties) is not defined, because they simply don’t exist on the server.

You can simply fix these errors by making window , document or navigator conditional. You can write a simple browser check like this:

https://gist.github.com/koenbok/e02a078e90c5ac7a5c1327c7960e4629

⚠️ Note: Some server side rendering systems actually mock or fake the window object so that some things work without making the code explicitly check for it. But it’s considered bad practice because:

The mocked methods often cannot provide a sensible result on the server, for example there is no window.innerWidth because there is no actual window and you can’t check if it’s a mobile device with navigator.userAgent because it’s a server.

Because you can’t mock everything it becomes very hard to know what you can rely on server side. The explicit rule that nothing is supported is much easier.

Skip Server Side Rendering

Sometimes, you can’t edit a component to fix it like above because you don’t own it; for example with a npm module that you use or external library. In that case, you should skip rendering the component server side so it only renders client side.

Let’s say we have a component that we use called WontEverWorkWithSSR that is imported from somewhere and can’t work server side, but we still want to use it:

https://gist.github.com/koenbok/93c5c55de7041afd4a5d385d31fdac14

This will throw the following optimization error (because window does not exist on the server) after publishing:

Pages that failed to optimize:

### Home ReferenceError: window is not defined import-map:

<https://framerusercontent.com/modules/GCFoT7BoEJDeJSxLzpBE/wrmI4ekO6ljcYPjpDpKG/NoSSR.js:5> const size = `${window.innerWidth} x ${window.innerHeight}`; ^

So we want to skip rendering the component on the server side. For that we can simply make a small utility that you can use to wrap the component that doesn’t work on the server:

https://gist.github.com/koenbok/1e06fc2f3c8eb20f8581a20cbd550fbd

Now your optimization errors will be gone and your component will still work as soon as the page is loaded on in the browser.

Overrides

Overrides are similar to components; avoid the use of window, document, etc.

More Context

Server side is great but this can be an annoying issue that nobody really solved yet. You can see how other frameworks solve this and copy an approach that works for you: Advanced Features: Dynamic Import | Next.js

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

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

This will happen after publishing, when we try to pre-render your site on the server. Your published version will have a Warning label under Settings → Versions or in the Publish Sheet.

Versions with Warning will just work as usual, but not be pre-rendered into static html. That means that your site will load slower and won’t be as optimized for SEO.

You can find the actual error in Settings → Domains under the ... menu. It will contain an error stack from our server trying to render your site to html (using React renderToString()).

⚠️ Note: If the download error file is not available, the pre-rendering process likely timed out on the server (after 30s). Contact support and we can help you out.

How to fix optimization errors

The most common reasons for failing are custom code components that use code that might rely on things not available in our server environment (Node.js). This typically results in an error that window , document or navigator (or any of their properties) is not defined, because they simply don’t exist on the server.

You can simply fix these errors by making window , document or navigator conditional. You can write a simple browser check like this:

https://gist.github.com/koenbok/e02a078e90c5ac7a5c1327c7960e4629

⚠️ Note: Some server side rendering systems actually mock or fake the window object so that some things work without making the code explicitly check for it. But it’s considered bad practice because:

The mocked methods often cannot provide a sensible result on the server, for example there is no window.innerWidth because there is no actual window and you can’t check if it’s a mobile device with navigator.userAgent because it’s a server.

Because you can’t mock everything it becomes very hard to know what you can rely on server side. The explicit rule that nothing is supported is much easier.

Skip Server Side Rendering

Sometimes, you can’t edit a component to fix it like above because you don’t own it; for example with a npm module that you use or external library. In that case, you should skip rendering the component server side so it only renders client side.

Let’s say we have a component that we use called WontEverWorkWithSSR that is imported from somewhere and can’t work server side, but we still want to use it:

https://gist.github.com/koenbok/93c5c55de7041afd4a5d385d31fdac14

This will throw the following optimization error (because window does not exist on the server) after publishing:

Pages that failed to optimize:

### Home ReferenceError: window is not defined import-map:

<https://framerusercontent.com/modules/GCFoT7BoEJDeJSxLzpBE/wrmI4ekO6ljcYPjpDpKG/NoSSR.js:5> const size = `${window.innerWidth} x ${window.innerHeight}`; ^

So we want to skip rendering the component on the server side. For that we can simply make a small utility that you can use to wrap the component that doesn’t work on the server:

https://gist.github.com/koenbok/1e06fc2f3c8eb20f8581a20cbd550fbd

Now your optimization errors will be gone and your component will still work as soon as the page is loaded on in the browser.

Overrides

Overrides are similar to components; avoid the use of window, document, etc.

More Context

Server side is great but this can be an annoying issue that nobody really solved yet. You can see how other frameworks solve this and copy an approach that works for you: Advanced Features: Dynamic Import | Next.js

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