How to Use Recoil.js Library in Gatsby

How to solve the problem of persisting state between pages using Recoil library in a Gatsby site.

Putra Aryotama
Oct 9, 2020 · 5 min read
Photo by Kevin Ku on Unsplash

According to its official documentation, Recoil is “a state management library for React”. There are a couple of reasons why Recoil is best chosen to manage states in a react application rather than using React’s built-in state management capabilities (including context).

Gatsby, on the other hand, “is a React-based open source framework for creating websites and apps”. Building web application using Gatsby can be fast and easy. Inside the Gatsby application, state management can be handled using Recoil.js.

Integrating Recoil in an existing React application, according to its documentation, is simple enough. After installing the Recoil package using either npm or yarn, one could just import RecoilRoot component at the top of the application’s component tree and voila! atom and selector can be used instead of React’s own state management(useState).

What better way than to show it through code examples. Here, a new Gatsby project is started using the default Gatsby starter (gatsby-default-starter).

Gatsby Default Starter default view

The states should persist across components and pages in the Gatsby site. In the components folder (src/components), two components have been created: Input and Display components. They are then imported into IndexPage page:

Input component
Display input
Index page

When a word (name) is entered in the Input component, the Display component in the Index page should persist and display the name and number of characters states of the particular input. The SecondPage page should also persist and display the name and number of characters states through the Display component.

Second page

One could leverage React’s own state and props to accomplish these tasks. However, we will try to accomplish these using Recoil. Let us follow the Recoil documentation to incorporate Recoil into our simple application.

After installing Recoil, RecoilRoot component is then placed at the top of the IndexPage component tree:

Index page with RecoilRoot at the top

The name and number of characters atom and selector, namely nameState and charState, is then created in a different file under the components folder (src/components) to be exported and used inside the IndexPage and SecondPage pages:

states.js file where name and characters atom and selector is placed

The nameState atom and charState selector from state.js file is imported to Input and Display components created earlier as follows:

Input component with recoil state (nameState atom)
Display component with recoil state (nameState atom and charState selector)

Now voila! Preserving states between components in the IndexPage is done using Recoil .

Voila!

What about keeping states across different pages? In the SecondPage (page-2.js file), nameState and charState should also be persisted through the Display component.

Second Page

Let recoil be incorporated into the SecondPage by adding RecoilRoot component and placing it at the top of the component tree. The Display component should then be imported and placed inside the SecondPage component.

Second page

The result?

The state in the IndexPage (index.js file) cannot be persisted to the SecondPage (page-2.js)

Why doesn’t the state seem to persist between pages? According to the documentation for Recoil, RecoilRoot component needs to appear somewhere in the parent tree. Pages in the Gatsby site are on different components of their own. So what is the parent tree of all the pages in Gatsby site?

Gatsby has this one particular file called gatsby-browser.js (it lives outside of the src folder) where, according to Gatsby’s documentation, “let’s you respond to actions within the browser and wrap your site in additional components”. That last part is important. You can now put a component in gatsby-browser.js that can wrap around all Gatsby pages (as the parent component). That is where RecoilRoot component should live!

To wrap all the pages in a component, a particular function from Gatsby Browser API is needed which is called wrapPageElement. wrapPageElement sets wrapper components around pages that won’t get unmounted on page changes. To use the wrapPageElement function, it needs to be exported from gatsby-browser.js.

RecoilRoot component needs to be imported and placed inside the wrapPageElement function. It also needs to be removed from each of the pages (IndexPage and SecondPage) that have been added earlier. RecoilRoot component is now hoisted to the wrapper element for pages.

gatsby-browser.js
IndexPage (RecoilRoot component removed)
SecondPage (RecoilRoot component removed)

The result?

Voila!

Voila! The state now persists in different pages.

To use Recoil library to persist state between components, RecoilRoot component needs to be placed at the top of the component tree. To persist state between pages in a Gatsby site, we leverage the use of wrapPageElement function from Gatsby Browser API to wrap around all the pages. RecoilRoot component is placed inside the wrapPageElement function, which is then exported from the gatsby-browser.js file.

The Startup

Get smarter at building your thing. Join The Startup’s +724K followers.

Putra Aryotama

Written by

I write for fun! I write about my field of work (tax, accounting, and economics) and hobby (programming, javascript, react). Sometimes in Indo, usually in Eng

The Startup

Get smarter at building your thing. Follow to join The Startup’s +8 million monthly readers & +724K followers.

Putra Aryotama

Written by

I write for fun! I write about my field of work (tax, accounting, and economics) and hobby (programming, javascript, react). Sometimes in Indo, usually in Eng

The Startup

Get smarter at building your thing. Follow to join The Startup’s +8 million monthly readers & +724K followers.

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store