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
window
ordocument
that 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 acomponentDidMount
lifecycle or into auseEffect
hook, which ensures the code doesn’t run unless it’s in the browser.Check that each of your JS files listed in your
pages
directory (and any sub-directories) are exporting either a React component or string. Gatsby treats any JS file listed under thepages
dir as a page component, so it must have a default export that’s a component or string.You mix up
import
andrequire
calls 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 useimport
and this also extends togatsby-ssr
andgatsby-browser
files.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-ssr
orgatsby-browser
has 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_SSR
feature can help you with this.
How to check if window
is defined
When referencing 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 window
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).
SSR during gatsby develop
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).
Add the DEV_SSR
flag to your gatsby-config.js
:
Please give feedback in the DEV_SSR umbrella discussion.