In this article I will tell how to build "Related Reads" section for a [gatsby](https://www.gatsbyjs.org/) blog, like the one you can find at the bottom of this page.

As a prerequisite I expect, that you are already familiar with gatsby or even have an app with some source `[-plugin]`where you pull your articles from.

I use [netlify cms](https://www.netlifycms.org/) and store all my articles next to the source code [in git](https://github.com/kitos/kitos.github.io/tree/develop/src/_content/blog) as markdown files. So `gatsby-source-filesystem` and `gatsby-transformer-remark` plugins are responsible for making them available in graphql. E.g. here is how I can query all articles:

```graphql
query BlogPostList {
  allMarkdownRemark {
    nodes {
      frontmatter {
        title
      }
    }
  }
}
```

But enough about me, let's get back to business.

## Setup local plugin

First of all, I want to implement this feature as a local plugin (instead of root `gatsby-node.js`). I find this approach more idiomatic and clear. Creating one is a piece of cake and gatsby has [a decent documentation about it](https://www.gatsbyjs.org/docs/creating-a-local-plugin/), so check it out if you haven't yet.

As a result, we should have `/plugins/related-reads/gatsby-node.js` along with empty `package.json` and name (equal to name of the folder!) of our plugin listed in `gatsby-config.js`.

## Extend graphql

The next step would be extending graphql schema, generated by `gatsby-transformer-remark`. So along with a content of an article, we can also request a list of articles about similar topic[s]. Like this:

```graphql
query BlogPostList {
  allMarkdownRemark {
    nodes {
      frontmatter {
        title
      }

      // highlight-start
      relatedReads {
        slug
        title
      }
      // highlight-end
    }
  }
}
```

[A while ego](https://www.gatsbyjs.org/blog/2019-03-04-new-schema-customization/) gatsby team provided very nice way to achieve this - [schema customization API](https://www.gatsbyjs.org/docs/schema-customization). And we are going to leverage it, particularly `createResolvers`:

```js
exports.createResolvers = ({ createResolvers }) =>
  createResolvers({
    // node type we want to extend
    MarkdownRemark: {
      // name of the field we want to add
      relatedReads: {
        // we return an array of other articles
        type: '[MarkdownRemark!]',
        // let's allow to specify number of articles returned
        args: { limit: 'Int' },

        async resolve(
          source, // the node we extend
          args,
          // collection of helpers
          // including access to internal store - nodeModel
          ctx

        ) {
          return []
        },
      },
    },
  })
```

No we can implement the last bit - the logic of _Relative Reads_. In my blog each post have a list of tags, so I gonna use it to measure similarity.

```js
const intersection = require('lodash.intersection')

// I've extracted the resolve function just to get rid of extra noise
let resolve = async (source, args, ctx) {
  let { frontmatter: { slug, lang, tags } } = source
  let { limit = Number.MAX_SAFE_INTEGER } = args

  // request all other posts
  let otherPosts = await ctx.nodeModel.runQuery({
    firstOnly: false, // we want to get an array
    type: 'MarkdownRemark',
    query: {
      filter: {
        frontmatter: {
          slug: { ne: slug }, // not current article or translation
          lang: { eq: lang }, // same lang
        },
      },
    },
  })

  return otherPosts
    .map((p) => ({
      ...p,
      // measure the similarity by the size of tags intersection
      similarity: intersection(p.frontmatter.tags, tags).length,
    }))
    .filter(({ similarity }) => similarity !== 0)
    .sort(
      (a, b) =>
        b.similarity - a.similarity ||
        b.frontmatter.date.localeCompare(a.frontmatter.date)
    )
    .slice(0, limit)
}
```

That is it! Pretty easy implementation and zero runtime cost - everything is requested ahead of time and build into your html pages, that is the strongest point if gatsby and JAMStack.

Did you like this post? Want to hear more stories about gatby? Please leave comment about things you'd like to know about.


Build "Related Reads" for your gatsby blog


## Mystique

While working on migration of part our [main web-site](https://tourlane.de) to [gatsby](http://gatsbyjs.org), we faced really weird problem: one of a links in navigation menu wasn't styled on initial load. It was reproducible only on the desktop.

![Navigation menu with unstyled link](/uploads/broken-link.jpg 'Unstyled link')

Once you opened some other page (using client-side routing), styles get in place 🤯.

The fact that component, responsible for this menu, worked absolutely fine in the old app (which is using _nextjs_), made everything even more weird 👻.

## Investigation

Without a second thought I opened DOM inspector and discovered that this link had css-classes related to mobile menu, while I was obviously on the desktop 🤪.

_"React messes up DOM during_ [_hydration_](https://ru.reactjs.org/docs/react-dom.html#hydrate)_"_ - I thought to myself. It was hard to believe: such crucial issue should have been discovered long time ago, and everything is fine IN THE OLD APP.

I revised hydration contract:

> React expects that the rendered content is identical between the server and the client.

I dig into source code of the component 🕵️‍♂️:

```jsx
// simplified NavBar.js
import React from 'react'
import Media from 'react-media'

export const NavBar = () => (
  <Media queries={{ maxWidth: 599 }}>
    {matches => (matches ? <MobileNav /> : <DesktopNav />)}
  </Media>
)
```

## Verdict

Do you see a problem here?

- [react-media](https://github.com/ReactTraining/react-media) is used to serve different markup for desktop and mobile
- we are migrating our app to _gatsby_, which means all our pages are statically built (SSR is happening during build time). And on this stage, we obviously do not have any information about _width_ of the screen. By default `react-media` matches all media queries, so in our case we build mobile layout.

This results in next workflow:

1. desktop browser requests page and receive mobile html (user sees it on first contentful paint)
2. react messes up DOM during _hydration_ (absolutely legally, since we produced 2 different trees on the _"server"_ and client)

## How to fix this?

To avoid such problems we can:

- prefer regular css media queries to [matchMedia](https://developer.mozilla.org/en-US/docs/Web/API/Window/matchMedia)\
  \
  Even if you cannot style same piece of html to fit your adaptive design, you can _"duplicate"_ it (html) and display one _"copy"_ per breakpoint.

  ```jsx
  let DesktopOnly = styled.div`
    @media (max-width: 599px) {
      display: none;
    }
  `

  let MobileOnly = styled.div`...`

  export const NavBar = () => (
    <>
      <MobileOnly>
        <MobileNav />
      </MobileOnly>

      <DesktopOnly>
        <DesktopNav />
      </DesktopOnly>
    </>
  )
  ```

  In this case not only you will avoid problems with _hydration_, but also end-user will get better experience: there will be no layout flickering during page load, since browser will render the page according to your html/css, and hydration will give it life.

- only in case the approach above doesn't work for you, use `react-media` (or similar solutions). E.g.:
  - SEO might suffer (I haven't faced such problems, but I assume that duplication of content, its growth... can influence it 💁‍♂️. Write a comment if you are aware of such cases)
  - performance might suffer, in case you render some complex element only for the desktop.\
    \
    **ATTENTION PLEASE!** Do not optimize prematurely! Always measure performance before you introduce any improvements. The fact that _react_ will have to render 50 more html elements shouldn't bother you.
  - something else might suffer 🤷‍♂️

But what about problems with hydration we experienced using second approach?

Well, as I mentioned at the beginning, such issue shouldn't have been left out, so it has a solution - two-pass rendering:

- choose a default layout you'd like to use by default:
  - if you are using runtime SSR, you can do it based on _User Agent_
  - for static sites based on usage statistics (in most cases it should be mobile, since devices are less performant, and it doesn't make sense to make them render tree twice)
- render three using this default during SSR and client hydration
- run an extra render in case actual layout didn't match default one

Official documentation [suggests](https://ru.reactjs.org/docs/react-dom.html#hydrate) to use state variable to implement this and `react-media` also [supports this](https://github.com/ReactTraining/react-media#server-side-rendering-ssr) via `defaultMatches` prop:

```jsx{3-6}
export const NavBar = () => (
  <Media
    queries={{ mobile: { maxWidth: 599 } }}
    defaultMatches={{ mobile: true }}
  >
    {matches => (matches.mobile ? <MobileNav /> : <DesktopNav />)}
  </Media>
)
```

### P.S.

"Why didn't you experience the same issue in your old app?" - a careful reader might wonder 🤨. Indeed, we use SSR there as well and do not use knowledge about browser (_User Agent_). To be honest, I didn't dig into legacy project in order to learn its secrets. But I guess it's about some extra render initiated by parent components 😬.


React SSR pitfalls in building adaptive layouts


## First steps

First time I thought about creating personal site was when I was taking java courses at EPAM Systems. The main motivation was to learn new things. So I've created a list of technologies I wanted to build my blog with:

![List of technologies](/uploads/blog-tech-stack.jpg 'Technologies')

At that moment I haven't worked with either of them (except MySQL I guess) and hardly understood how I could wire them all together. Also you might noticed that I didn't write a word about infrastructure and deployment of my future site (I had no idea about it).

Time went on, I got a job, started to get familiar with technologies from my list: we actively used Liquibase on my first project; I figured out that I can use fancy groovy and gradle instead of xml and maven to write build scripts; but the main frontend library was jQuery, and it was clear that I wouldn't like to use it in personal project. In a year I joined project with AngularJS, one more year later I had realized that I would not use either :-)

## Getting closer to right stack

Meanwhile react was getting more and more popular. And I decided to give it a try: colleagues of mine and I started local frontend community - WebPurple and to be true frontend community it must have its own site. Its first version has under the hood: react, redux,material-ui, koa, mongoose and was deployed to some VPS. I've learned a couple of things:

- Material Design fits tools best (not sites)
- managing content manually is bad idea
- IaaS is overkill (also painful) as well as PaaS (after a couple of months fighting with manual setup of all infrastructure to VM I've moved to heroku and mlab) for promo site
- I don't want to pay for hosting (or a at least it to be cheap)
- I want WebPurple site to be BLAZING fast (without much effort)

## Love at second sight

Any ideas on what I am gonna talking about? Static site generation, JAMStack, GastbyJS! In early 2018, I began to hear more and more about Gatsby. I don't know why didn't pay much attention to it when I first time heard about it (I might thought it is not applicable for my cases). But after I started to investigate the approach (JAMStack) it offers I had fallen in love 😍. It took me about 2 weeks to migrate the whole (thought it is not that big) site from koa, mongodb and heroku to gatsby, netlify-cms and netlify.

- ⚡️site had perfect performance by default
  - static markup (first load)
  - code splitting
  - image optimization
  - prefetch...
- 💃content is easily managed via CMS
  - user friendly UI
  - extensible (build on react)
  - content stored alongside your code (in git repo!)...
- 🙈infrastructure is the simplest (ADN aka better CDN)
  - CD - deploy on every git push
  - automatic PR preview
  - https, custom domains, AWS lambdas...

You can checkout the result - www.webpurple.net (source). I've even given a talk (russian) about it.

Later I've applied gatsby for one of my customers news site, but with a bit different setup: strapi as a CMS and Jenkins as a CD tool.

## Happy end

Finally I felt like I've found best toolchain and it was time to get my hands on personal site. Since I fill pretty comfortable with technical stack (although this time I use contentful as CMS, travis as CI/CD and github pages as a hosting), my motivation is less about learning new things and more about improving my english (via writing articles about amazing things I deal with) and a bit of showing off 🤓. I hope you enjoy the site (its unique design 😇). And you started to think about building your one (using great gatsby of course). Keep in mind that gatsby is suitable not only for blogs or promo-sites, it can make any of your sites performant (even for e-commerce project).

### P.S.

By the way I've started to develop my site before it had become mainstream 😂.


Blog #gatsbyjs

Build "Related Reads" for your gatsby blog

React SSR pitfalls in building adaptive layouts

Better late than never