DEV Community: 🌈 Josh

Generate an SEO-Friendly Sitemap for your Gatsby Site

🌈 Josh — Tue, 10 Mar 2020 22:09:51 +0000

This is a cross-post from my personal blog, where you'll find many other posts on React and Gatsby!

So here's the thing. I really don't want to have to care about SEO. It's all very nebulous, and it attracts so many snake-oil salespeople. SEO websites are the worst. And yet, if you want people to see the stuff that you build, SEO remains super important.

Happily, we don't need to become SEO experts. A few key optimizations can play a big role in our search engine results!

I was intrigued by a recent blog post about how the Ghost team moved their blog to Gatsby. The move had a profound impact on their SEO:

In that article, the author explains how adding an XML sitemap (among other factors) helped them achieve remarkable organic traffic gains. So today, this tutorial will walk you through how to generate a sitemap for your Gatsby blog.

What is an XML Sitemap?

An XML sitemap is a raw document designed to help machines learn about the structure of a website. They look like this:

This is different from the "sitemap" sometimes linked to in the footers of websites. No human is meant to look at this, and they shouldn't be linked to. This is a document exclusively for Googlebot and its cousins.

Leveraging the ecosystem

Whenever I run into a new problem when working on a Gatsby project, my first instinct is always to check and see if a solution has been created by the community. A quick search reveals gatsby-plugin-sitemap, an officially-maintained plugin that solves this exact problem! 🎉

Let's install it, either using yarn or npm:

yarn add gatsby-plugin-sitemap

Next, we can add it to our gatsby-config.js:

module.exports = {
  siteMetadata: {
    // ✂️
  },
  plugins: [
    'gatsby-plugin-sitemap',
    // ✂️
  ],
}

Whenever we build our site, this plugin will generate a sitemap.xml file, alongside all the other files that Gatsby builds.

Critically, this plugin only runs when building for production. This means that you won't be able to test it when running in development mode. Let's build, and spin up a static server with serve:

yarn build && serve public

serve is an NPM package that will serve the files on your local filesystem. If you've never used it before, you'll first need to install it with yarn add -g serve.

We pass public as an argument, since Gatsby builds into the /public directory; that's where all our static files will be served from.

You should now be able to open localhost:5000/sitemap.xml, and see a beautiful ugly XML document.

Excluding certain paths

Unless you're extremely lucky, it's likely that this sitemap isn't quite right.

One of the biggest reasons to add a sitemap is to tell Google which pages not to worry about. For example, my blog had the following sites specified in the original version of my sitemap:

<url>
  <loc>https://www.joshwcomeau.com/admin</loc>
  <changefreq>daily</changefreq>
  <priority>0.5</priority>
</url>
<url>
  <loc>https://www.joshwcomeau.com/confirmed</loc>
  <changefreq>daily</changefreq>
  <priority>0.5</priority>
</url>

admin is an authenticated route I use for viewing stats about the website, and confirmed is shown when users join my newsletter. Neither of these pages makes sense to include in search results.

Happily, we can customize the plugin to pass an array of paths to exclude:

// gatsby-config.js

module.exports = {
  siteMetadata: {
    // ✂️
  },
  plugins: [
    {
      resolve: 'gatsby-plugin-sitemap',
      options: {
        exclude: ['/admin', '/confirmed'],
      },
    }
    // ✂️
  ],
}

Advanced customizations

When reading the Google sitemap recommendations, I found this bit of information:

List only canonical URLs in your sitemaps. If you have two versions of a page, list only the (Google-selected) canonical in the sitemap.

A "canonical" URL is the "true home" for a specific entity. If you have multiple URLs that contain the same content, you need to mark one as "canonical" for search engines to use.

If you don't do this, Google will penalize you, and it can hurt your search result rankings 😬

In addition to this sitemap stuff, it is also a good idea to add a <link rel="canonical"> tag to the head of each page with React Helmet. I'll be writing another post about this soon – subscribe to my newsletter so you don't miss it!

On my blog, post URLs are in the following format: /:category/:slug. This presents a problem, since posts can belong to multiple categories. For example, the post that you're reading right now can be reached through both of these URLs:

/gatsby/seo-friendly-sitemap/
/seo/seo-friendly-sitemap/

The posts on my blog are all written using MDX. In the frontmatter for the posts, I have data that looks like this:

---
title: "Generate an SEO-Friendly Sitemap for your Gatsby Site"
type: tutorial
publishedOn: 2020-03-09T09:30:00-0400
categories: ['gatsby', 'seo']
---

Categories are listed in priority order, so the first category should always form the canonical URL.

The challenge is clear: I need to fetch the categories from my MDX frontmatter and use it to filter the sites generated in the sitemap. Delightfully, this is an option with the plugin!

Querying data with GraphQL

Inside our gatsby-config.js, we can write a GraphQL query to pull whatever data we need:

module.exports = {
    siteMetadata: {
    // ✂️
  },
  plugins: [
    {
      resolve: 'gatsby-plugin-sitemap',
      options: {
        exclude: ['/admin', '/confirmed'],
        query: `
          {
            site {
              siteMetadata {
                siteUrl
              }
            }

            allSitePage {
              edges {
                node {
                  path
                }
              }
            }
          }
        `,
      },
    },
  ],
};

By default, the plugin uses a query like this, but we can overwrite it. Here it fetches the siteUrl, which in my case is http://www.joshwcomeau.com, and then it fetches the path for every page node (eg. /gatsby/seo-friendly-sitemap). It stitches those two strings together for every page it finds, and produces a sitemap.

In order to filter out non-canonical results, we first need to expose the right data to GraphQL!

allSitePage is an index of every page created, either by putting a React component in src/pages, or using the createPage API. In my case, I'm generating all articles/tutorials programmatically with createPage.

Here's what a typical createPage call looks like, inside gatsby-node.js:

createPage({
  path: pathname,
  component: path.resolve(...),
  context: {
    /* component props */
  },
});

If you're building a blog with Markdown or MDX, you're probably already using this to generate your pages. You provide it a path to live, a component to mount, and some contextual data that the component might need. Anything passed to context becomes available to the component via props.

Happily, it turns out that context also gets exposed to GraphQL!

I added a new piece of data to context:

createPage({
  path: pathname,
  component: path.resolve(...),
  context: {
    isCanonical: currentCategory === canonicalCategory
  },
});

The currentCategory and canonicalCategory variables were already available to me, since I was iterating through all my data and using it to create these pages.

With this data added, I could update the GraphQL query passed to query, in my gatsby-config.js:

query: `
  {
    site {
      siteMetadata {
        siteUrl
      }
    }

    allSitePage {
      edges {
        node {
          path
          context {
            isCanonical
          }
        }
      }
    }
  }
`,

One of the most common stumbling blocks for Gatsby developers is GraphQL. It's a powerful tool, but it has a pretty steep learning curve. The Gatsby GraphQL Concepts doc should help clarify some of what we're doing here.

Filtering pages

We've now exposed each page's "canonical status" to GraphQL, and written it into the query that gatsby-plugin-sitemap will use. The final piece of this puzzle: overwriting the default "serializer" to specify what should be done with this queried data.

Here's what that looks like:

{
  resolve: `gatsby-plugin-sitemap`,
  options: {
    exclude: ['/admin', '/confirmed'],
    query: /* ✂️ */,
    serialize: ({ site, allSitePage }) => {
      return allSitePage.edges
        .filter(({ node }) => (
          node.context.isCanonical !== false
        ))
        .map(({ node }) => {
          return {
            url: site.siteMetadata.siteUrl + node.path,
            changefreq: 'daily',
            priority: 0.7,
          };
        });
    },
  },
}

serialize is a function that transforms the data from the query into an array of "sitemappy" objects. The items we return will be used as the raw data to generate the sitemap.

Now that we've specified it in GraphQL, we can access node.context.isCanonical to filter out duplicate pages.

You'll notice we're explicitly checking to see if isCanonical is false. This is important, since isCanonical will be undefined for all the non-blog-post pages, and these pages are totally worth including in the sitemap. We only want to remove pages that are false, not ones that are falsy.

By using the query and serialize escape hatches built into gatsby-plugin-sitemap, we are given far greater control over the generated sitemap. It also allows us to fine-tune some page-specific options!

Page-specific options

When generating the XML sitemap, you may have noticed a couple additional fields being shown:

<url>
  <loc>https://www.your-website.com/page-1</loc>
  <changefreq>daily</changefreq>
  <priority>0.5</priority>
</url>
<url>
  <loc>https://www.your-website.com/page-2</loc>
  <changefreq>daily</changefreq>
  <priority>0.5</priority>
</url>

In fact, there are a handful of options that can be used to tweak each page, for optimal effects.

changefreq

changefreq is a measure of how often your page changes. From the Sitemaps protocol:

This value provides general information to search engines and may not correlate exactly to how often they crawl the page. Valid values are:

always

hourly

daily

weekly

monthly

yearly

never

The value "always" should be used to describe documents that change each time they are accessed. The value "never" should be used to describe archived URLs.

For a blog, I feel like daily fits most usecases pretty well.

priority

priority is a relative measure of a page's importance. You can use this to signal to the crawler which pages it should care about, and which aren't so important. There are 11 values available to you: 0.0 through 1.0.

On this blog, I'm using it to rank article pages like this one above "index" pages like the latest content page.

If you're a clever trickster, you might be concocting a devious plan: set every page to a 1.0 priority, and watch as your site rockets to the top of the search results!

Unfortunately, this scheme doesn't work—priority is a relative measure of importance. It won't affect how your site compares to other sites.

lastmod

Finally, we can add a date-time stamp to indicate when the page was last modified.

I'm honestly not sure how valuable this is, since presumably Googlebot is smart enough to detect when a page's content has changed, but correctly following a specification can't hurt!

Even more customizations

If you feel like you're limited by the options presented by this plugin, the folks at Ghost created their own advanced sitemap plugin. It uses XSL templating for a much prettier output! Because it's a newer and less-battle-tested plugin, I opted to stick with the standard one for my blog, but this could be a powerful option for folks with advanced usecases!

Submitting your sitemap

Once your sitemap has been generated, and your site's been deployed, you'll need to let Google know that it exists!

For this, there are a number of options. I opted to submit it via the Google Search Console tool, though there are other options outlined in their documentation.

The Perils of Rehydration: An Eye-Opening Realization about Gatsby and React

🌈 Josh — Tue, 03 Mar 2020 22:18:53 +0000

This is a cross-post from my personal blog. View it there for at least 35% more whimsy!

I ran into the strangest issue recently. Everything was groovy in development, but in production, the bottom of my blog was doing something… unintended:

A bit of digging into the Elements tab in the devtools revealed the culprit… My React component was rendering in the wrong spot!

<!-- In development, things are correct -->
<main>
  <div class="ContentFooter">
    Last updated: <strong>Sometime</strong>
  </div>

  <div class="NewsletterSignup">
    <form>
      <!-- Newsletter signup form stuff -->
    </form>
  </div>
</main>


<!-- In production, things had teleported! -->  
<main>
  <div class="ContentFooter">
    Last updated: <strong>Sometime</strong>

    <div class="NewsletterSignup">
      <form>
        <!-- Newsletter signup form stuff -->
      </form>
    </div>
  </div>
</main>

How could this be? Had I discovered a bug in React? I checked the React Devtools "⚛️ Components" tab, and it told a different story, one in which everything was fine, and the pieces were all where they were supposed to be. What a liar!

It turns out, I had a fundamental misunderstanding about how React works in a server-side-rendering context. And I think many React devs share this misunderstanding! And it can have some pretty serious ramifications.

Some problematic code

Here's an example of code that can cause the kind of rendering issue shown above. Can you spot the problem?

function Navigation() {
  if (typeof window === 'undefined') {
    return null;
  }

  // Pretend that this function exists,
  // and returns either a user object or `null`.
  const user = getUser();

  if (user) {
    return (
      <AuthenticatedNav
        user={user}
      />
    );
  }

  return (
    <nav>
      <a href="/login">Login</a>
    </nav>
  );
};

For a long time, I would have believed that this code was A-OK. Right up until my blog started impersonating a Picasso painting.

This tutorial will peek behind the curtain to help us understand how server-side rendering works. We'll see why the logic shown here can be problematic, and how a different approach can accomplish the same goal.

Server-side rendering 101

To understand the problem, we need to first dig a little into how frameworks like Gatsby and Next.js differ from traditional client-side apps built with React.

When you use React with something like create-react-app, all of the rendering happens in the browser. It doesn't matter how large your application is, the browser still receives an initial HTML document that looks something like this:

<!DOCTYPE html>
<html lang="en">
  <head>
    <!-- Maybe some stuff here -->
  </head>

  <body>
    <div id="root"></div>
    <script
      src="/static/bundle.js"
    ></script>
    <script
      src="/static/0.chunk.js"
    ></script>
    <script
      src="/static/main.chunk.js"
    ></script>
  </body>
</html>

The page is fundamentally empty, but it includes a couple JS scripts. Once the browser downloads and parses those scripts, React will build up a picture of what the page should look like, and inject a bunch of DOM nodes to make it so. This is known as client-side rendering, since all the rendering happens on the client (the user's browser).

All of that stuff takes time, and while the browser and React are working their magic, the user is staring at a blank white screen. Not the best experience.

Smart people realized that if we could do that rendering on the server, we could send the user a fully-formed HTML document. That way, they'd have something to look at while the browser downloads, parses, and executes the JS. This is known as server-side rendering (SSR).

Server-side rendering can be a performance win, but the thing is, that work still needs to be done on-demand. When you request your-website.com, React has to transform your React components into HTML, and you'll still be staring at a blank screen while you wait for it. It's just that the work is being done on the server, not on the user's computer.

The galaxy-brain realization is that huge chunks of many websites and apps are static, and they can be built at compile-time. We can generate the initial HTML way ahead of time, on our development machines, and distribute it immediately when a user requests it. Our React apps can load as quickly as a vanilla HTML site!

This is exactly what Gatsby does (along with Next.js, in certain configurations). When you run yarn build, it generates 1 HTML document for every route on your site. Every side page, every blog post, every store item — an HTML file is created for each of them, ready to be served up immediately.

Is this all just server-side rendering? Unfortunately, a lot of this language is used interchangeably, and it can be kinda hard to follow. Technically, what Gatsby does is server-side rendering, since it renders the React app using Node.js using the same ReactDOMServer APIs as a more traditional server-side render. In my mind, though, it's conceptually different; "server-side rendering" happens on your live production server in real-time, in response to a request, whereas this compile-time render happens much earlier, as part of the build process.

Some folks have started calling it SSG, which either stands for "Static Site Generation" or "Server-Side Generated", depending on who you ask.

Code on the client

The apps we build nowadays are interactive and dynamic—users are accustomed to experiences that can't be accomplished with HTML and CSS alone! So we still need to run client-side JS.

The client-side JS includes the same React code used to generate it at compile-time. It runs on the user's device, and builds up a picture of what the world should look like. It then compares it to the HTML built into the document. This is a process known as rehydration.

Critically, rehydration is not the same thing as a render. In a typical render, when props or state change, React is prepared to reconcile any differences and update the DOM. In a rehydration, React assumes that the DOM won't change. It's just trying to adopt the existing DOM.

Dynamic sections

This takes us back to our code snippet. As a reminder:

const Navigation = () => {
  if (typeof window === 'undefined') {
    return null;
  }

  // Pretend that this function exists,
  // and returns either a user object or `null`.
  const user = getUser();

  if (user) {
    return (
      <AuthenticatedNav
        user={user}
      />
    );
  }

  return (
    <nav>
      <a href="/login">Login</a>
    </nav>
  );
};

This component is designed to have three possible outcomes:

If the user is logged in, render the <AuthenticatedNav> component
If the user is NOT logged in, render the <UnauthenticatedNav> component.
If we don't know if the user is logged in or not, render nothing.

Schrodinger's user

In a macabre thought experiment, Austrian physicist Erwin Schrödinger describes a situation: a cat is placed in a box with a toxin that has a 50% chance of being released within an hour. After an hour, there is an equal probability that the cat is alive or dead. But until you open the box and find out, the cat can be thought of as both alive and dead.

In our webapp, we face a similar predicament; for the first few moments that a user is on our site, we don't know whether they are logged in or not.

This is because the HTML file is built at compile-time. Every single user gets an identical copy of that HTML, regardless of whether they're logged in or not. Once the JS bundle is parsed and executed, we can update the UI to reflect the user's state, but there is a significant gap of time before that happens. Remember, the whole point of SSG is to give the user something to look at while we download, parse, and rehydrate the app, which can be a lengthy process on slow networks/devices.

Many webapps choose to show the "logged out" state by default, and this leads to a flicker you've probably run into before.

I took the liberty of building a mini Gatsby app that reproduces this issue. Visit this demo app, and click "Login" to simulate a login. Notice when refreshing the page, you get a flicker!

A noble but flawed attempt

In the shared code snippet, we attempt to solve for this problem in the first few lines:

const Navigation = () => {
  if (typeof window === 'undefined') {
    return null;
  }

The idea here is sound: Our initial compile-time build happens in Node.js, a server runtime. We can detect whether or not we're rendering on the server by checking to see if window exists. If it doesn't, we can abort the render early.

The problem is that in doing so, we're breaking the rules. 😬

Rehydration ≠ render

When a React app rehydrates, it assumes that the DOM structure will match.

When the React app runs on the client for the first time, it builds up a mental picture of what the DOM should look like, by mounting all of your components. Then it squints at the DOM nodes already on the page, and tries to fit the two together. It's not playing the “spot-the-differences” game it does during a typical update, it's just trying to snap the two together, so that future updates will be handled correctly.

By rendering something different depending on whether we're within the server-side render or not, we're hacking the system. We're rendering one thing on the server, but then telling React to expect something else on the client:

<!-- The initial HTML
     generated at compile-time -->
    
<header>
  <h1>Your Site</h1>
</header>


<!-- What React expects
     after rehydration -->
    
<header>
  <h1>Your Site</h1>
  <nav>
    <a href="/login">Login</a>
  </nav>
</header>

Somewhat remarkably, React can still handle this situation sometimes. You may have done this yourself, and gotten away with it. But you're playing with fire. The rehydration process is optimized to be ⚡️ fast ⚡️, not to catch and fix mismatches.

About Gatsby in particular

The React team knows that rehydration mismatches can lead to funky issues, and they've made sure to highlight mismatches with a console message:

Unfortunately, Gatsby only uses the server-side rendering APIs when building for production. And because React warnings in general only fire in development, it means that these warnings are never shown when building with Gatsby 😱

This is a trade-off. By opting out of server-side-rendering in dev, Gatsby is optimizing for a short feedback loop. Being able to quickly see the changes you make is so, so important. Gatsby prioritizes speed over accuracy.

This is kind of a significant problem, though; folks in an open issue are advocating for a change, and we may start seeing hydration warnings.

Until then, though, it is especially important to be mindful of this when developing with Gatsby!

The solution

To avoid issues, we need to ensure that the rehydrated app matches the original HTML. How do we manage "dynamic" data then?

Here's what the solution looks like:

function Navigation() {
  const [hasMounted, setHasMounted] = React.useState(false);

  React.useEffect(() => {
    setHasMounted(true);
  }, []);

  if (!hasMounted) {
    return null;
  }

  const user = getUser();

  if (user) {
    return (
      <AuthenticatedNav
        user={user}
      />
    );
  }

  return (
    <nav>
      <a href="/login">Login</a>
    </nav>
  );
};

We initialize a piece of state, hasMounted, to false. While it's false, we don't bother rendering the "real" content.

Inside the useEffect call, we immediately trigger a re-render, setting hasMounted to true. When this value is true, the "real" content gets rendered.

The difference from our earlier solution: useEffect only fires after the component has mounted. When the React app adopts the DOM during rehydration, useEffect hasn't been called yet, and so we're meeting React's expectation:

<!-- The initial HTML
     generated at compile-time -->
    
<header>
  <h1>Your Site</h1>
</header>

<!-- What React expects
     after rehydration -->
    
<header>
  <h1>Your Site</h1>
</header>

Immediately after this comparison, we trigger a re-render, and this allows React to do a proper reconciliation. It'll notice that there's some new content to render here—either an authenticated menu, or a login link—and update the DOM accordingly.

Two-pass rendering

Have you ever noticed that the expiration date on cereal clearly wasn't printed at the same time as the rest of the box? It's stamped on, after the fact:

There's a logic to this: cereal-box printing is a two-step process. First, all of the "universal" stuff is printed: the logo, the cartoon leprechaun, the enlarged-to-show-texture photograph, the random pics of smart-watches. Because these things are static, they can be mass-produced, printed millions at a time, months in advance.

They can't do that with expiration dates, though. At that moment in time, the manufacturers have no idea what the expiration date should be; the cereal that will fill those boxes probably doesn't even exist yet! So they print an empty blue rectangle instead. Much later, after cereal has been produced and injected into the box, they can stamp on a white expiration date and pack it up for shipment.

Two-pass rendering is the same idea. The first pass, at compile-time, produces all of the static non-personal content, and leaves holes where the dynamic content will go. Then, after the React app has mounted on the user's device, a second pass stamps in all the dynamic bits that depend on client state.

Performance implications

The downside to two-pass rendering is that it can delay time-to-interactive. Forcing a render right after mount is generally frowned upon.

That said, for most applications, this shouldn't make a big difference. Usually the amount of dynamic content is relatively small, and can be quickly reconciled. If huge chunks of your app are dynamic, you'll miss out on many of the benefits of pre-rendering, but this is unavoidable; dynamic sections can't be produced ahead of time by definition.

As always, it's best to do some experimentation of your own if you have concerns around performance.

Abstractions

On this blog, I wound up needing to defer a handful of rendering decisions to the second pass, and I was sick of writing the same logic over and over again. I created a <ClientOnly> component to abstract it:

function ClientOnly({ children, ...delegated }) {
  const [hasMounted, setHasMounted] = React.useState(false);

  React.useEffect(() => {
    setHasMounted(true);
  }, []);

  if (!hasMounted) {
    return null;
  }

  return (
    <div {...delegated}>
      {children}
    </div>
  );
}

Then you can wrap it around whichever elements you want to defer:

<ClientOnly>
  <Navigation />
</ClientOnly>

We could also use a custom hook:

function useHasMounted() {
  const [hasMounted, setHasMounted] = React.useState(false);

  React.useEffect(() => {
    setHasMounted(true);
  }, []);

  return hasMounted;
}

function Navigation() {
  const hasMounted = useHasMounted();

  if (!hasMounted) {
    return null;
  }

  const user = getUser();

  if (user) {
    return (
      <AuthenticatedNav
        user={user}
      />
    );
  }

  return (
    <nav>
      <a href="/login">Login</a>
    </nav>
  );
};

With this trick up my sleeve, I was able to solve my rendering issue. The day was saved!

Mental models

While neat, the abstractions aren't the most important part of this tutorial. The critical bit is the mental model.

When working in Gatsby apps, I've found it really helpful to think in terms of a two-pass render. The first pass happens at compile-time, wayyy ahead of time, and sets the foundation for the page, filling in everything that is universal for all users. Then, much later, a second-pass render will fill in the stateful bits that vary from person to person.

Gatsby is sometimes called a "static site generator", but that name feels limiting—you can build rich, dynamic web applications with Gatsby! It does require a bit of special consideration, but with the right mental model, just about anything is possible 💫

Persisting React State in localStorage

🌈 Josh — Mon, 24 Feb 2020 22:37:16 +0000

This is a cross-post from my personal blog. View it there for at least 35% more whimsy!

Let's say we're building a calendar app, like Google Calendar. The app lets you toggle between three different displays: month, week, and day.

Personally, I always want to see the "Week" view. It gives me everything I need to know about the current day, while also giving me a peek at what's coming up in the next couple of days.

Thankfully, calendar apps know that users have strong preferences around this kind of thing, and the toggle is sticky. If I switch from “week” to “month” and refresh the page, the “month” view is the new default; it sticks.

Conversely, it's super annoying when form controls aren't sticky. For example: every month, I create 4-5 expenses through Expensify. Every single time, I have to swap the default currency from USD to CAD. Why can't it remember that I'm Canadian??

In this tutorial we'll see how we can create a custom React hook to abstract away the "stickiness", so we get it for free whenever we need it.

Show me the code

Here's what our custom hook looks like:

function useStickyState(defaultValue, key) {
  const [value, setValue] = React.useState(() => {
    const stickyValue =
      window.localStorage.getItem(key);

    return stickyValue !== null
      ? JSON.parse(stickyValue)
      : defaultValue;
  });

  React.useEffect(() => {
    window.localStorage.setItem(
      key, 
      JSON.stringify(value)
    );
  }, [key, value]);

  return [value, setValue];
}

What about SSR? If your app is server-rendered (with a framework like Next.js or Gatsby), you'll get an error if you try using this hook as-is.

This is actually a pretty tricky problem, because that first render on the server doesn't have access to your computer's localStorage; it can't possibly know what the initial value should be!

Dynamic content in a server-rendered app is a complex subject, but fortunately, my very next blog post will shed some light on this! Join my newsletter to make sure you don't miss it.

If this code isn't clear to you, fear not! The rest of this tutorial explains it in greater detail 💫

In practice

This hook makes a single assumption, which is reasonably safe in React apps: the value powering a form input is held in React state.

Here's a non-sticky implementation of a form control to switch between values:

const CalendarView = () => {
  const [mode, setMode] = React.useState('day');

  return (
    <>
      <select onChange={ev => setMode(ev.target.value)}>
        <option value="day">Day</option>
        <option value="week">Week</option>
        <option value="month">Month</option>
      </select>

      {/* Calendar stuff here */}
    </>
  )
}

We can use our new "sticky" variant by swapping out the hook:

const CalendarView = () => {
  const [mode, setMode] = useStickyState('day', 'calendar-view');

  // Everything else unchanged
}

While the useState hook only takes 1 argument—the initial value—our useStickyState hook takes two arguments. The second argument is the key that will be used to get and set the value persisted in localStorage. The label you give it has to be unique, but it otherwise doesn't matter what it is.

How it works

Fundamentally, this hook is a wrapper around useState. It just does some other stuff too.

Lazy initialization

First, it takes advantage of lazy initialization. This lets us pass a function to useState instead of a value, and that function will only be executed the first time the component renders, when the state is created.

const [value, setValue] = React.useState(() => {
  const stickyValue =
    window.localStorage.getItem(key);

  return stickyValue !== null
    ? JSON.parse(stickyValue)
    : defaultValue;
});

In our case, we're using it to check for the value in localStorage. If the value exists, we'll use that as our initial value. Otherwise, we'll use the default value passed to the hook ("day", in our earlier example).

Keeping localStorage in sync

The final step to this is to make sure that we update localStorage whenever the state value changes. For that, our trusty friend useEffect comes in handy:

React.useEffect(() => {
  window.localStorage.setItem(name, JSON.stringify(value));
}, [name, value]);

If the state value changes rapidly (like, many times a second), you may wish to throttle or debounce the updates to localStorage. Because localStorage is a synchronous API, it can cause performance problems if it's done too rapidly.

Don't take this an excuse to prematurely optimize, though! The profiler will show you whether or not your updates need to be throttled.

Wrapping up

This hook is a small but powerful example of how custom hooks let us invent our own APIs for things. While packages exist that solve this problem for us, I think there's a lot of value in seeing how to solve these problems ourselves 🧙🏻‍♂️

Special thanks to Satyajit Sahoo for a couple refactor suggestions 🌠