This documentation isn’t up to date with the latest version of Gatsby.
Outdated areas are:
- Load page resources section needs to be updated
You can help by making a PR to update this documentation.
develop-html. This section deals with the
The config is quite large, but here are some of the important values in the final output.
There’s a lot going on here. And this is just a sample of the output that doesn’t include the loaders, rules, etc. We won’t go over everything here, but most of it is geared towards proper code splitting of your application.
Once webpack has finished compilation, it will have produced a few key types of bundles:
This bundle is produced from production-app.js which will mostly be discussed in this section. It is configured in webpack entry
This contains the small webpack-runtime as a separate bundle (configured in
optimization section). In practice, the app and webpack-runtime are always needed together.
The framework bundle contains the React framework. Based on user behavior, React hardly gets upgraded to a newer version. Creating a separate bundle improves users’ browser cache hit rate as this bundle is likely not going to be updated often.
This is a separate bundle for each page. The mechanics for how these are split off from the main production app are covered in Code Splitting.
This is the entry point to webpack that outputs
app-[contenthash].js bundle. It is responsible for navigation and page loading once the initial HTML has been loaded.
To show how
production-app works, let’s imagine that you’ve just refreshed the browser on your site’s
/blog/2 page. The HTML loads immediately, painting your page quickly. It includes a CDATA section which injects page information into the
Then, the app, webpack-runtime, component, shared libraries, and data JSON bundles are loaded via
<script> (see HTML tag generation). Now, your
production-app code starts running.
The first thing your app does is run the onClientEntry browser API. This allows plugins to perform any operations before you hit the rest of the page loading logic. For example gatsby-plugin-glamor will call rehydrate.
It’s worth noting that the browser API runner is completely different to
api-runner-node which is explained in How APIs/Plugins Are Run.
api-runner-node runs in Node.js and has to deal with complex server based execution paths. Whereas running APIs on the browser is a matter of iterating through the site’s registered browser plugins and running them one after the other (see api-runner-browser.js).
One thing to note is that it gets the list of plugins from
./cache/api-runner-browser-plugins.js, which is generated early in bootstrap.
hydrate() is a ReactDOM function which is the same as
render(), except that instead of generating a new DOM tree and inserting it into the document, it expects that a React DOM already exists with exactly the same structure as the React Model. It therefore descends this tree and attaches the appropriate event listeners to it so that it becomes a live React DOM. Since your HTML was rendered with exactly the same code as you’re running in your browser, these will (and have to) match perfectly. The hydration occurs on the
<div id="___gatsby">...</div> element defined in default-html.js.
The hydration requires a new React component to “replace” the existing DOM with. Gatsby uses reach router for this. Within it, Gatsby provides a RouteHandler component that uses PageRenderer to create the navigated to page.
PageRenderer’s constructor loads the page resources for the path. On first load though, these will have already been requested from the server by
<link rel="preload" ... /> in the page’s original HTML (see Link Preloads in HTML Generation Docs). The loaded page resources includes the imported component, with which Gatsby creates the actual page component using React.createElement(). This element is returned to the RouteHandler which hands it off to Reach Router for rendering.
Load page resources
Before hydration occurs, Gatsby kicks off the loading of resources in the background. As mentioned above, the current page’s resources will have already been requested by
link tags in the HTML. So, technically, there’s nothing more required for this page load. But we can start loading resources required to navigate to other pages.
This occurs in loader.js. The main function here is getResourcesForPathname(). Given a path, it will find its page, and import its component module JSON query results. But to do this, it needs access to that information. This is provided by async-requires.js which contains the list of all pages in the site, and all their dataPaths. fetchPageResourcesMap() takes care of requesting that file, which occurs the first time
getResourcesForPathname() is called.
Gatsby attaches global state to the
window object via
window.___somevar variables so they can be used by plugins (though this is technically unsupported). Here are a few:
This is a reference to the loader.js object that can be used for getting page resources and enqueueing prefetch commands. It is used by gatsby-link to prefetch pages. And by gatsby-plugin-guess-js to implement its own prefetching algorithm.
Only used during
gatsby develop lifecycle
chunk-map.json. See Code Splitting for more.
These are set in init navigation. Used by
gatsby-link to override navigation behavior so that it loads pages before using reach to navigate.