One of the features I really like about Gatsby is the
ability to control the root of the application. In
gatsby-browser.js we have two APIs
that we'll be talking about today.
The first API is
wrapRootElement, which takes an object
argument that has an
element to render and that's it. As
long as you render this element you can do whatever you want
here, like import CSS or anything else. The docs mention
using this for providers, which is the most common use case.
This is useful to setup any Providers component that will wrap your application. For setting persistent UI elements around pages use wrapPageElement.
In gatsby-mdx we use a custom loader to run additional filesystem work and provide the result to the application through React's context. This means as a plugin we can do some processing and store the result of that computation in a place the entire Gatsby application can access.
This API is also used in CSS-in-JS solutions that need to
initialized stylesheets for SSR. For example,
wrapRootElement to do
setup that could be error-prone if users had to rewrite it
in each application.
That doesn't mean this is necessary for all CSS-in-JS
plugins though. For example,
use this API because its SSR solution doesn't need
The alternative to
This API enables you to wrap the application with a
component that will not be unmounted when each page is
rendered... but what is this useful for?
This is useful for setting wrapper component around pages that won’t get unmounted on page change. For setting Provider components use wrapRootElement.
TylerBarnes' gatsby-plugin-transition-link is one such application. It uses a number of components to enable per-Link transitions.
Another potential application of
gatsby-mdx in the future is to use dynamic import statements
that correspond to a page or group of pages instead of
pre-compiling the scope and putting it all in the root.
In any case,
good APIs to know about if you're writing plugins, using any
Provider, or need to implement complex state
management of pages like transitions.