Debugging HTML Builds
Errors while building static HTML files (the build-time React SSR process) or while using
getServerData (the runtime SSR process) generally happen for one of the following reasons:
Some of your code references “browser globals” like
documentthat aren’t available in Node.js. If this is your problem you should see an error above like “window is not defined”. To fix this, find the offending code and either a) check before calling the code if window is defined so the code doesn’t run while Gatsby is building (see code sample below) or b) if the code is in the render function of a React.js component, move that code into a
componentDidMountlifecycle or into a
useEffecthook, which ensures the code doesn’t run unless it’s in the browser.
Check that each of your JS files listed in your
pagesdirectory (and any sub-directories) are exporting either a React component or string. Gatsby treats any JS file listed under the
pagesdir as a page component, so it must have a default export that’s a component or string.
You mix up
requirecalls in the same file. This might lead to “WebpackError: Invariant Violation: Minified React error #130” since webpack 4 is stricter than v3. The solution is to only use
importand this also extends to
Your app doesn’t correctly hydrate in the client, which results in gatsby develop and gatsby build being inconsistent. It’s possible that a change in a file like
gatsby-browserhas a structure that is not reflected in the other file, meaning that there is a mismatch between client and server output.
Some other reason :-) #1 is the most common reason building static files fail. If it’s another reason, you have to be a bit more creative in figuring out the problem. The
DEV_SSRfeature can help you with this.
How to check if
window is defined
window in a React component.
When requiring a module:
In case the module needs to be defined for the code to run, you can use a ternary operator
Fixing third-party modules
So, the worst has happened and you’re using an npm module that expects
to be defined. You may be able to file an issue and get the module patched, but
what to do in the meantime?
One solution is to customize your webpack configuration to replace the offending module with a dummy module during server rendering.
gatsby-node.js in the project root:
Another solution is to use a package like loadable-components. The module that tries to use
window will be dynamically loaded only on the client side (and not during SSR).
Server-Side render (SSR) pages on full reloads during
gatsby develop. This helps you detect SSR bugs and fix them without needing to do full builds with
gatsby build. Once enabled, go to your desired page and do a full reload (e.g. Ctrl + R or F5).
DEV_SSR flag to your
Please give feedback in the DEV_SSR umbrella discussion.