Gatsby on Haseeb Majid

Why I moved from Gatsby to Hugo for this blog?

Me — Thu, 17 Nov 2022 00:00:00 +0000

About This Site

This site was built with hugo and the PaperModX Theme (using a fork of a fork at the moment).

I decided to go with an existing theme rather than creating my own this time, to one save time but also to give the site a more consistent feel. I am no designer and I felt my last website (v3), really felt like a bunch of different websites thrown together. It was a great way to learn React, TailwindCSS and a bunch of other technologies.

Technologies Used

Hugo
- PaperModX Theme
  - My fork (of a fork, of a fork)
Goatcounter for Analytics
Hosted by Netlify
Using NetlifyCMS for content management

Why Move to Hugo?

I also had a bunch of issues even building the site recently. I had a scheduled job to rebuild it so that the stats page would update with the most viewed articles etc. The final straw for me was not being to easily add a new page for talks. I recently was lucky enough to give a talk at Europython and wanted to share that on my website but realised with my old Gatsby site that would be a bit of a pain to add. I could also no longer easily upgrade my site to the latest version of Gatsby v4 due to the old plugins I relied on. Mostly it was essentially an issue with me, that I no longer wanted to put in the effort to maintain the site.

So I decided to take a look at something easier to maintain but that would still look great. I have been learning Golang and decided to take a look at Hugo. One thing I noticed right away was how fast it was to build the site. Roughly speaking the old site used to take ~120 seconds to build and this site takes < 1 second.

Anecdotally I noticed the hot reloader seems to work better but again I was using a v2 of Gatsby. Overall I am pretty happy with this new site. Using Hugo archetypes and page-bundles. I have moved all of my articles within this repo, making it far easier to create new blog posts and test draft posts.

So hopefully I will be blogging more often 🤣 (I’m looking at you 2 posts in 2022, as of the time of writing)!

👴 Older iterations:

You can find older iterations of this site here:

Testing a Gatsby application with Cypress on Gitlab CI

Me — Mon, 22 Mar 2021 00:00:00 +0000

In this blog post, we will go over how we can automatically test a Gatsby site end-to-end (e2e), using Cypress on Gitlab CI.

Introduction

Gatsby

Gatsby is a static site generator (SSG) built upon React. It allows us to create “blazing” fast websites. In this example, we will use a simple blog starter template available and add a Cypress test.

Cypress

Fast, easy and reliable testing for anything that runs in a browser. - Cypress README

Cypress allows us to test a web application, how a real user would use the application. Cypress will be used to test our Gatsby application, though if it’s a site you can test it using Cypress.

Gitlab CI

Gitlab CI is a continuous integration pipeline that will allow us to run our tests automatically, such as when we merge code into the master branch.

Getting Started

Gatsby

Create a new Gatsby site, using this default Gatsby starter:

gatsby new gatsby-starter-blog https://github.com/gatsbyjs/gatsby-starter-blog
cd gatsby-starter-blog

(Optional) Typescript

Adding Typescript to a Gatsby web application.

yarn add typescript @types/react @types/react-dom @types/node -D
yarn add gatsby-plugin-typescript

Add the following to your gatsby-config.js.

module.exports = {
  plugins: [
    {
      resolve: `gatsby-plugin-typescript`,
      options: {
        isTSX: true, // defaults to false
        jsxPragma: `jsx`, // defaults to "React"
        allExtensions: true, // defaults to false
      },
    },
  ],
}

Then create a new file tsconfig.json (in the project root, where the gatsby-config.js is).

{
  "compilerOptions": {
    "module": "commonjs",
    "target": "esnext",
    "jsx": "preserve",
    "lib": ["dom", "esnext"],
    "strict": true,
    "noEmit": true,
    "isolatedModules": true,
    "esModuleInterop": true,
    "noUnusedLocals": false,
    "allowJs": true
  },
  "exclude": ["node_modules", "public", ".cache"]
}

Cypress

Now to finally add Cypress to our application so we can test it. First, install the dependencies.

yarn add -D cypress cypress-axe axe-core start-server-and-test
# Add types
yarn add -D @types/cypress-axe

Next, let’s create a cypress.json folder in the project root.

{
  "baseUrl": "http://localhost:8000/",
   "integrationFolder": "cypress/e2e"
}

Next, let’s add some new “scripts” to the package.json file.

  "scripts": {
    "cy:open": "cypress open",
    "cy:run": "cypress run",
    "build": "gatsby build",
    "develop": "gatsby develop",
    "format": "prettier --write \"**/*.{js,jsx,ts,tsx,json,md}\"",
    "start": "npm run develop",
    "serve": "gatsby serve",
    "clean": "gatsby clean",
    "test": "echo \"Write tests! -> https://gatsby.dev/unit-testing\" && exit 1",
    "test:e2e": "start-server-and-test 'yarn develop' http://localhost:8000 'yarn cy:open'",
    "test:e2e:ci": "start-server-and-test 'yarn develop' http://localhost:8000 'yarn cy:run'"
  }

These scripts allow us to start Cypress, cy:open opens a GUI to visualise our tests whereas cy:run does it all in the terminal (the browser runs in headless mode). Where we will run test:e2e:ci in our CI pipeline, here we use the start-server-and-test command to start our Gatsby server using yarn develop. Then we run cy:run to start our tests.

Structure

Create a new folder called cypress which will look something like this.

.
├── e2e
│   └── accessibility.test.ts
├── fixtures
│   └── graphql.json
├── plugins
│   └── index.js
├── support
│   ├── commands.js
│   ├── index.d.ts
│   └── index.js
└── tsconfig.json

mkdir -p cypress/support

Create a file at cypress/support/commands.js

Cypress.Commands.add(`assertRoute`, (route) => {
  cy.url().should(`equal`, `${window.location.origin}${route}`);
});

Add some custom types for Cypress index.d.ts if you are using Typescript.

/// 

declare namespace Cypress {
  interface Chainable<Subject> {
    /**
     * Assert the current URL
     * @param route
     * @example cy.assertRoute('/page-2')
     */
    assertRoute(route: string): Chainable<any>;

    /**
     * Waits for Gatsby to finish the route change, in order to ensure event handlers are properly setup
     */
    waitForRouteChange(): Chainable<any>;
  }
}

Next create the index.js file, which should look something like this.

import "cypress-axe"
import "./commands"

Next, let’s create a plugin folder mkdir -p cypress/plugins.

// / 
// ***********************************************************
// This example plugins/index.js can be used to load plugins
//
// You can change the location of this file or turn off loading
// the plugins file with the 'pluginsFile' configuration option.
//
// You can read more here:
// https://on.cypress.io/plugins-guide
// ***********************************************************

// This function is called when a project is opened or re-opened (e.g. due to
// the project's config changing)

/**
 * @type {Cypress.PluginConfig}
 */
module.exports = (on, config) => {
  // `on` is used to hook into various events Cypress emits
  // `config` is the resolved Cypress config
  return config
}

Now finally let’s create our tests folder mkdir -p cypress/e2e.

cypress-axe

In this blog post we won’t go over any complicated Cypress test we will simply use cypress-axe to test the accessibility of our (a11y) of our website.

/// 
/// 
/// 

describe("Component accessibility test", () => {
  it("Main Page", () => {
    cy.visit("/")
    cy.wait(500)
    cy.injectAxe()
    cy.checkA11y({
      include: [["#___gatsby"]],
    })
  })
})

Note the /// comments at the top used to add types for cypress. The test above will go to our home page and test if it has any a11y violations and if so will fail the test.

We can now run our tests locally by running this command:

yarn run test:e2e

Gitlab CI

Now how can we automate this, so the tests will run say every time we make changes on the master branch to make sure we haven’t broken any a11y. Create a new .gitlab-ci.yml or add the following job to an existing CI file.

image: node:12.14.1

variables:
  CYPRESS_CACHE_FOLDER: "$CI_PROJECT_DIR/cache/Cypress"

cache:
  key: ${CI_COMMIT_REF_SLUG}
  paths:
    - cache/Cypress
    - node_modules

stages:
  - test

before_script:
  - yarn install

tests:
  image: cypress/browsers:node12.14.1-chrome83-ff77
  stage: test
  script:
    - yarn test:e2e:ci

I won’t go into the details of what makes up a Gitlab CI file. At the top of the file, we will cache the node_modules file so we can share it between the job and the Cypress cache. The job itself is very simple it uses a cypress/browsers:node12.14.1-chrome83-ff77 Docker image which provides a headless chrome browser that Cypress can leverage to run the tests. As we won’t have access to a GUI in the Gitlab CI runner. The tests job is very simple it runs yarn test:e2e:ci to run our Cypress tests.

That’s it, quite simple to add Cypress tests that run in our CI pipeline.

Appendix

How to add a ToC in Gatsby

Me — Wed, 11 Nov 2020 00:00:00 +0000

A lot of people, I included, are using Gatsby to build their own blogs. One of the things I wanted to add to my blog was a table of contents (ToC) 📝. A ToC will show you all the headings of an article and when you click on a heading it’ll take you directly to that heading. It’s a nice little feature to have on your blog, which makes it easier for users to navigate and find the information they are looking for.

Prerequisite

So before we get started you can find the source code here. In this article, I will be using the gatsby-starter-blog.

# If you don't have the CLI installed, run this command.
npm -g install gatsby-cli

gatsby new my-gatsby-project https://github.com/gatsbyjs/gatsby-starter-blog

If you already have an existing Gatsby site, you can make the changes directly there instead of using this starter.

Plugins

We need to get some extra plugins installed for the ToC to work properly.

yarn add gatsby-remark-autolink-headers gatsby-plugin-emotion

The plugin gatsby-remark-autolink-headers turns all of the headers into anchor links. This means we can link to the headers.

Emotion

How to source your Gatsby posts from another repo

Me — Fri, 18 Sep 2020 00:00:00 +0000

In this article, we will go over how you can manage your markdown blog posts from another git repository (repo). Separate to the git repository for your Gatsby site. This is the same process that I use to manage this repo.

So what this entails is the source code for my Gatsby site is in a repo called portfolio-site on Gitlab. Then I have another repo for all of my blog posts (in markdown) called articles. During build time of the Gatsby blog, we will import the markdown files from our articles git repo and use it as a source of data for our Gatsby blog.

Git Plugin

First, install the Gatsby git plugin, so that we can source our data from git.

yarn add gatsby-source-git

Then add the plugin to your gatsby-config.js to tell it where to source its data from.

Gatsby Filesystem

Add an 'edit post' button to your Gatsby blog

Me — Mon, 07 Sep 2020 00:00:00 +0000

In this article, we will look at how we can add an “edit post” button, to your Gatsby blog. When this button is clicked it will take the user to your markdown file, on github/gitlab that was used to generate the blog post they are currently viewing.

Setup

Before we add the edit button to a Gatsby blog, let’s set up a simple Gatsby site using the Gatsby blog starter. You can skip this step and add the button to an existing site.

npm -g install gatsby-cli
gatsby new my-blog-starter https://github.com/gatsbyjs/gatsby-starter-blog

If you don’t use the start above, you will need to make sure you have the gatsby-source-filesystem plugin installed. To import our markdown files. Your gatsby-config.js looks like this:

  {
    resolve: `gatsby-source-filesystem`,
    options: {
      path: `${__dirname}/content/blog`,
      name: `blog`,
    },
  },

Then make sure you also have the gatsby-transformer-remark plugin installed and it should be in your gatsby-config.js like so:

  {
    resolve: `gatsby-transformer-remark`,
    options: {
      // ...
    },
  },

(Optional) Blog Post

Let’s assume our gatsby-node.js file looks like this:

exports.createPages = async ({ graphql, actions }) => {
  const { createPage } = actions;

  const blogPost = path.resolve(`./src/templates/blog-post.js`);
  const result = await graphql(
    `
      {
        allMarkdownRemark(
          sort: { fields: [frontmatter___date], order: DESC }
          limit: 1000
        ) {
          edges {
            node {
              fields {
                slug
              }
              frontmatter {
                title
              }
            }
          }
        }
      }
    `
  );

  if (result.errors) {
    throw result.errors;
  }

  // Create blog posts pages.
  const posts = result.data.allMarkdownRemark.edges;

  posts.forEach((post, index) => {
    const previous = index === posts.length - 1 ? null : posts[index + 1].node;
    const next = index === 0 ? null : posts[index - 1].node;

    createPage({
      path: post.node.fields.slug,
      component: blogPost,
      context: {
        slug: post.node.fields.slug,
        previous,
        next,
      },
    });
  });
};

This is how we create a new blog post for each of our markdown files. You can read more about how markdown works with Gatsby here.

Also let’s use a simple template file for your blogs posts. So our blog-post.js looks like this:

import React from "react";
import { Link, graphql } from "gatsby";

// ...

const BlogPostTemplate = ({ data, pageContext, location }) => {
  const post = data.markdownRemark;
  const siteTitle = data.site.siteMetadata.title;
  const { previous, next } = pageContext;

  return (
    <Layout location={location} title={siteTitle}>
      <SEO
        title={post.frontmatter.title}
        description={post.frontmatter.description || post.excerpt}
      />
      // ...
    Layout>
  );
};

export default BlogPostTemplate;

export const pageQuery = graphql`
  query BlogPostBySlug($slug: String!) {
    site {
      siteMetadata {
        title
      }
    }
    markdownRemark(fields: { slug: { eq: $slug } }) {
      id
      excerpt(pruneLength: 160)
      html
      frontmatter {
        title
        date(formatString: "MMMM DD, YYYY")
        description
      }
    }
  }
`;

Edit Button

Ok, now we need two pieces of information the location of our project on git where our markdown files are stored. In this example, it’s here https://gitlab.com/hmajid2301/articles. We also need the path to the markdown file in the git repo. So we can combine these two pieces of information together to get a URL to the markdown file on git.

First, we need a way to get the file path of the markdown file, we can do this with using our GraphQL query. The same query we use to get other information such as title and contents. All we need to add is fileAbsolutePath to the markdownRemark part of our query. This will return, as the name suggests, the absolute path to the file, i.e. /home/haseeb/projects/personal/articles/34. Gatsby edit button/source_code/content/blog/hello-world/index.md.

export const pageQuery = graphql`
  query BlogPostBySlug($slug: String!) {
    site {
      siteMetadata {
        title
      }
    }
    markdownRemark(fields: { slug: { eq: $slug } }) {
      id
      excerpt(pruneLength: 160)
      html
      fileAbsolutePath
      frontmatter {
        title
        date(formatString: "MMMM DD, YYYY")
        description
      }
    }
  }
`;

Now we need a way to use this file path to link to this page on Gitlab. Since I know that articles/ is a git repo, we want to remove /home/haseeb/projects/personal/articles from /home/haseeb/projects/personal/articles/34. Gatsby edit button/source_code/content/blog/hello-world/index.md.

Then assuming the git URL of our repo, where the markdown files exists, is https://gitlab.com/hmajid2301/articles. The path to our markdown file on git could be something like https://gitlab.com/hmajid2301/articles/-/blob/master/34. Gatsby edit button/source_code/content/blog/hello-world/index.md.

So let’s add logic to our blog-post.js file to generate this git URL. After we have updated our GraphQL query, we can add the some logic to our code to workout the git URL path. Let’s create a new function called getGitMarkdownUrl().

const BlogPostTemplate = ({ data, pageContext, location }) => {
  const post = data.markdownRemark;
  const siteTitle = data.site.siteMetadata.title;
  const { previous, next } = pageContext;

  function getGitMarkdownUrl() {
    const pathConst = "/articles/";
    const gitURL = "https://gitlab.com/hmajid2301/articles";
    const sliceIndex =
      post.fileAbsolutePath.indexOf(pathConst) + pathConst.length;
    const markdownFileGitPath = post.fileAbsolutePath.slice(sliceIndex);
    const blogPostOnGit = `${gitURL}/-/blob/master/${markdownFileGitPath}`;
    return blogPostOnGit;
  }

  const gitMarkdownUrl = getGitMarkdownUrl();

  // ....
};

Warn: Don’t forget to change the gitURL variable in your project!

Where the following two lines remove everything before /articles/, so we get 34. Gatsby edit button/source_code/content/blog/hello-world/index.md.

const sliceIndex = post.fileAbsolutePath.indexOf(pathConst) + pathConst.length;
const markdownFileGitPath = post.fileAbsolutePath.slice(sliceIndex);

Then we combine this with our git URL to end up with the path to the markdown file https://gitlab.com/hmajid2301/articles/-/blob/master/34. Gatsby edit button/source_code/content/blog/hello-world/index.md.

const blogPostOnGit = `${gitURL}/-/blob/master/${markdownFileGitPath}`;

Finally, all we need to do is add the edit button and have it link to this gitMarkdownUrl. You can do something like this below:

<a href={gitMarkdownUrl} rel="noreferrer" target="_blank">
  EDIT THIS POST
a>

If you want to make it look fancier, you can use react-icons to get a proper edit icon (as shown in the gif above).

That’s it! That’s all we needed to do when the user clicks on the edit button it’ll take them to the git repo where the markdown files exist. They can then perhaps fork the project make their edit and open a new merge or pull request (GitLab vs GitHub) and add in the changes they want (if approved by you).

Appendix

How to add offline search to a Gatsby blog

Me — Thu, 20 Aug 2020 00:00:00 +0000

Let’s take a look at how we can add offline local search 🔍 to a Gatsby blog. There are two main types of search we can use an offline search like elasticlunr and external API search engines like ElasticSearch. These are typically more scalable but also more expensive.

You can find more info here.

In this article, I will show you how to add offline search to your Gatsby blog using elasticlunr. This means your website needs to be indexed locally and will increase the bundle size as this index needs to be loaded by the client but with the scale and size of personal blogs (100s, not 1000s of blog post) this shouldn’t make a massive difference. We will also look at how we can add highlighting to our search results.

Note that you need to be careful with offline search because the entire search index has to be brought into the client, which can affect the bundle size significantly - GatsbyJS

Setup

Before we add search Gatsby blog, let’s setup a simple Gatsby site using the Gatsby blog starter, you can of course skip this step and add search to an existing site.

npm -g install gatsby-cli
gatsby new my-blog-starter https://github.com/gatsbyjs/gatsby-starter-blog

Markdown

The search component will use the data within our markdown and index it, so that the client can search with this data later. In this example I will assume your markdown files look something like the example below:

---
title: Hello World
date: "2015-05-01"
tags: ["food", "duck"]
---

This is my first post on my new fake blog! How exciting!

I'm sure I'll write a lot more interesting things in the future.

...

The top part of a markdown file between the --- is known as the front matter, often we can access this data as a key/value (like a Python dictionary).

Note: In this example, we will be using the MarkdownRemark, but you can use search for anything just adjust the examples below as required.

Search

Now onto adding search to our site.

Elasticlunr

We will use elasticlunr for our offline/local search. Luckily there is a Gatsby plugin we can use, which makes integrating it into our site very easy. First install the following plugin and the library: yarn add @gatsby-contrib/gatsby-plugin-elasticlunr-search elasticlunr.

Then open your gatsby-config.js and add the following:

{
    resolve: `@gatsby-contrib/gatsby-plugin-elasticlunr-search`,
    options: {
      fields: [`title`, `tags`],
      resolvers: {
        MarkdownRemark: {
          title: (node) => node.frontmatter.title,
          tags: (node) => node.frontmatter.tags,
          path: (node) => node.frontmatter.slug,
        },
      },
    },
  },

Here we are telling the search plugin what (GraphQL) fields to index. In this example, we want to index the title and tags. We could also index the content if we wanted by adding the following line after path html: (node) => node.internal.content, and adding html to the fields array. You can index any field available in GraphQL, provided by the MarkdownRemark plugin (or whichever plugin you are using).

GraphQL (Optional)

Slight aside here but if you wish to explore and take a look at the data available/provided by the MarkdownRemark plugin, you can start your Gatsby site, typically using yarn develop and once the command has finished doing it’s magic 🎉, visit this page http://localhost:8000/___graphql. This provides us with our GraphQL playground (an IDE) and is a great way to understand what is going on with our GraphQL queries if you don’t understand.

For example, if you type the following into the main field and press the play button at the top.

query MyQuery {
  allMarkdownRemark(
    sort: { order: DESC, fields: [frontmatter___date] }
    filter: { frontmatter: { title: { ne: "Uses" } } }
  ) {
    edges {
      node {
        id
        excerpt(pruneLength: 100)
        frontmatter {
          date(formatString: "YYYY-MM-DD")
          title
          tags
        }
      }
    }
  }
}

You should see something like (in this example):

{
  "data": {
    "allMarkdownRemark": {
      "edges": [
        {
          "node": {
            "id": "1a7e02d4-620a-5268-8149-2d8cbf26a20a",
            "excerpt": "Far far away, behind the word mountains, far from the countries Vokalia and\nConsonantia, there live…",
            "frontmatter": {
              "date": "2015-05-28",
              "title": "New Beginnings",
              "tags": ["deer", "horse"]
            }
          }
        },
        {
          "node": {
            "id": "fe83f167-8f86-51fe-a981-c5189625e270",
            "excerpt": "Wow! I love blogging so much already. Did you know that “despite its name, salted duck eggs can also…",
            "frontmatter": {
              "date": "2015-05-06",
              "title": "My Second Post!",
              "tags": ["food", "blog"]
            }
          }
        },
        {
          "node": {
            "id": "4e865c18-e797-5da8-a46d-902949a00c7f",
            "excerpt": "This is my first post on my new fake blog! How exciting! I’m sure I’ll write a lot more interesting…",
            "frontmatter": {
              "date": "2015-05-01",
              "title": "Hello World",
              "tags": ["food", "duck"]
            }
          }
        }
      ]
    }
  },
  "extensions": {}
}

As you can see this is a very familiar structure to the one we described in our search config above. If you play around with the fields on the left-hand side of the IDE, you should be able to get a better understanding of all fields you can index.

Logic

Now we will add the relevant JSX components we need for search to our site.

TailwindCSS (Optional)

You can follow this tutorial to add TailwindCSS. We will add TailwindCSS to this Gatsby project and we will use this to style our components. First install the following dependencies:

yarn add tailwindcss gatsby-plugin-postcss @emotion/core @emotion/styled gatsby-plugin-emotion
yarn add -D twin.macro # twin.macro allows us to use css-in-js a bit like emotion/styled-components except for tailwind
npx tailwindcss init

Then add the following to your gatsby-config.js:

plugins: [`gatsby-plugin-postcss`, `gatsby-plugin-emotion`],

Then create a new file:

vim main.css
#...

# Contents of the file
@tailwind base;
@tailwind components;
@tailwind utilities;

# ...

Then add the following line to gatsby-browser.js:

import "./src/main.css";

Finally create a new file postcss.config.js and add the following:

module.exports = () => ({
  plugins: [require("tailwindcss")],
});

Components

We will create all of the components in the following src/components folder. First, let’s create the Input.jsx component for the text input, which looks something like this:

import React from "react"
import tw from "twin.macro"

const Input = React.forwardRef(
  ({ className, label, onChange, placeholder = "", value }, ref) => (
    <TextInput
      ref={ref}
      aria-label={label}
      className={`bg-background text-header placeholder-main ${className}`}
      onChange={onChange}
      placeholder={placeholder}
      type="text"
      value={value}
    />
  )
)

const TextInput = tw.input`inline px-2 h-full w-full text-left inline text-lg transition duration-300`

export default Input

Since we are using twin.macro we can use syntax like const TextInput = tw.input``. Hence we can use the name TextInput. in our component, where TextInput is just an input with some tailwindcss styles we’ve defined.

Note we added a React forward ref so that, we can autofocus on this input later on. So when the input is shown to the client we are already focused into the input.

Next, let’s create a component for SearchItem.jsx. This is a single search item found. In this case, we will only show the title and read more button. Note we are using the react-highlight-words library to highlight words from the search query.

The prop query is the search query the user typed in. In the Highlighter component the searchWords prop is given a list of words to highlight, hence we need to split the string into an array. For example, if we had the search query "A blog post", it would become ["A", "blog", "post"], and will highlight either of those words in the title (A, blog or post).

Note: Again you can extend this to include perhaps a description of the blog post (first 160 characters) etc. We are just keeping it simple for this example.

import { Link } from "gatsby"
import React from "react"
import Highlighter from "react-highlight-words"
import tw from "twin.macro"

const SearchItem = ({ path, title, query }) => (
  <SearchItemContainer>
    <SearchTitle>
      <Link
        className="hover:text-white hover:bg-blue-500 hover:p-1 rounded"
        to={path}
      >
        <Highlighter
          autoEscape
          highlightStyle={{ backgroundColor: "#ffd54f" }}
          searchWords={query.split(" ")}
          textToHighlight={title}
        />
      Link>
    SearchTitle>
    <ReadMore className="hover:text-blue-500 text-lg py-2" type="button">
      <Link to={path}>Read MoreLink>
    ReadMore>
  SearchItemContainer>
)

const SearchItemContainer = tw.div`my-10`

const SearchTitle = tw.h2`text-2xl font-semibold`

const ReadMore = tw.button`hover:text-blue-500 text-lg py-2`

export default SearchItem

Next, we have a component we will call SearchItems.jsx, which will be a list of the search results and look something like:

import React from "react"

import SearchItem from "./SearchItem"

const SearchItems = ({ results, query }) => (
  <ul>
    {results.map(page => (
      <li key={page.id}>
        <SearchItem path={`${page.path}`} query={query} title={page.title} />
      li>
    ))}
  ul>
)

export default SearchItems

Now onto the main component, the component that will actually work out the results to show to the client. We will call this component Search.jsx:

import { Index } from "elasticlunr"
import React, { useState, useEffect } from "react"
import tw from "twin.macro"

import Input from "./Input"
import SearchItems from "./SearchItems"

const Search = ({ searchIndex }) => {
  const index = Index.load(searchIndex)
  const [query, setQuery] = useState("")
  const [results, setResults] = useState([])
  const searchInput = React.createRef()

  useEffect(() => {
    searchResults("blog")
    searchInput.current.focus()
  }, [])

  function searchResults(searchQuery) {
    const res = index.search(searchQuery, { expand: true }).map(({ ref }) => {
      return index.documentStore.getDoc(ref)
    })
    setResults(res)
  }

  return (
    <SearchContainer>
      <SearchInputContainer>
        <Input
          ref={searchInput}
          className="px-2"
          label="Search"
          onChange={event => {
            const searchQuery = event.target.value
            setQuery(searchQuery)
            searchResults(searchQuery)
          }}
          placeholder="Search"
          value={query}
        />
      SearchInputContainer>
      <SearchItems query={query} results={results} />
    SearchContainer>
  )
}

const SearchContainer = tw.div`max-w-screen-md mx-auto pt-8`

const SearchInputContainer = tw.div`flex w-full text-left h-12 text-lg focus-within:shadow-outline my-8`

export default Search

Let’s break this down:

const index = Index.load(searchIndex);
const [query, setQuery] = useState("");
const [results, setResults] = useState([]);
const searchInput = React.createRef();

The first part will be used to store some variables we need later on. Like storing the current query the client has typed into the search, the current search results and a reference to the search input so we can focus into it.

useEffect(() => {
  searchResults("blog");
  searchInput.current.focus();
}, []);

Next, the useEffect hook is called as soon as the component mounts, so as soon as the component mounts we will focus into the searchInput component searchInput.current.focus() and we pre-fill the search with any blog post with "blog" in it’s title/tags searchResults("blog").

function searchResults(searchQuery) {
  const res = index.search(searchQuery, { expand: true }).map(({ ref }) => {
    return index.documentStore.getDoc(ref);
  });
  setResults(res);
}

This is the actual function which gets our search results. It makes the query with elasticlunr and stores the results in out state hook variable result using the set function setResults(res). The first part of the function does most of the heavy lifting returning a list of possible results to show to the client.

<Input
  ref={searchInput}
  className="px-2"
  label="Search"
  onChange={(e) => {
    const searchQuery = event.target.value;
    setQuery(searchQuery);
    searchResults(searchQuery);
  }}
  placeholder="Search"
  value={query}
/>

Note: e.target.query is the current value in the text input.

Finally when taking a look at the input you can see the ref={searchInput} we defined above being assigned here, so we can focus on this component. Next on any change i.e. a keypress we call the onChange function. Where we update the query with the new search query setQuery(searchQuery) again using a state hook. Then we call the searchResults(searchQuery) function which will update the results.

This is then shown to the client using our SearchItems component defined above like so: .

Finally, we have a “SearchBar.tsx”, this is the component we will use to tie everything together.

import styled from "@emotion/styled"
import { graphql, StaticQuery } from "gatsby"
import React, { useState } from "react"
import tw from "twin.macro"

import Search from "./Search"

const SearchBar = () => {
  const [showSearch, setShowSearch] = useState(false)

  function hideSearch(event) {
    if (event.target.placeholder !== "Search") {
      setShowSearch(false)
    }
  }

  return (
    <SearchComponent>
      <h1
        className="hover:cursor-pointer text-orange-800 text-2xl my-10"
        onClick={() => setShowSearch(!showSearch)}
      >
        Search
      h1>

      <SearchOverlay
        onClick={e => hideSearch(e)}
        onKeyPress={e => hideSearch(e)}
        role="presentation"
        showSearch={showSearch}
      >
        <StaticQuery
          query={graphql`
            query SearchIndexQuery {
              siteSearchIndex {
                index
              }
            }
          `}
          render={data => (
            <SearchContainer>
              {showSearch && (
                <Search searchIndex={data.siteSearchIndex.index} />
              )}
            SearchContainer>
          )}
        />
      SearchOverlay>
    SearchComponent>
  )
}

const SearchComponent = tw.div`flex-grow flex`

const SearchContainer = tw.div`overflow-y-scroll h-screen w-full`

const SearchOverlay = styled.div`
  opacity: ${props => (props.showSearch ? 1 : 0)};
  display: ${props => (props.showSearch ? "flex" : "none")};
  transition: opacity 150ms linear 0s;
  background: rgba(255, 255, 255, 0.9);
  ${tw`fixed inset-0 bg-opacity-50 z-50 m-0 items-center justify-center h-screen w-screen`};
`

export default SearchBar

Normally I would use a search icon which when pressed would show the search overlay. However to keep things simple we will just use the text “Search”, which when clicked on will show our search overlay to the client.

<h1
  className="hover:cursor-pointer text-orange-800 text-2xl my-10"
  onClick={() => setShowSearch(!showSearch)}
>
  Search
h1>

The main job of this component is to toggle the search on/off. To do this we use a state hook like so:

const [showSearch, setShowSearch] = useState(false);

function hideSearch(event) {
  if (event.target.placeholder !== "Search") {
    setShowSearch(false);
  }
}

Where we have a function to hide the search if the user clicks anything outside of the search. Hence the if statement event.target.placeholder.

<StaticQuery
  query={graphql`
    query SearchIndexQuery {
      siteSearchIndex {
        index
      }
    }
  `}
  render={(data) => (
    <SearchContainer>
      {showSearch && <Search searchIndex={data.siteSearchIndex.index} />}
    SearchContainer>
  )}
/>

The next interesting part is the Graphql query to get the search index from elasticlunr. We this pass as searchIndex prop to our Search component we created above. This is the same search index we search against the current user query. We also use conditional rendering we only show the Search component when showSearch is true.

And that’s it! We successfully added search to our Gatsby blog alongside search highlighting. Thanks for reading.

Appendix

How to use Storybooks with MDX

Me — Mon, 20 Jul 2020 00:00:00 +0000

This article (sort of) continues on from my previous article How to use Storybooks, Gatsby, Babel, Tailwind, Typescript together. In this article, we will document our React components using Storybook with MDX.

You can find an example project using this here, you can also find a demo site for said project.

Prerequisite

Just to make sure everyone’s on the same page let’s follow the same steps to setup Storybook as we had in the last article. We will use the latest versions of Storybook (v6) so we can access the latest features. We will go over how we can use these features in the next article.

First, remove any lines in your package.json that start with @storybook. In my case, I removed @storybook/addon-actions, @storybook/add-links, @storybook/addons and @storybook/react. The typescript docgen modules will be used to parse our components and retrieve the props information for Storybook. We will see a bit later with the control addon.

yarn add --dev @storybook/addon-docs@6.0.0-beta.20 @storybook/addon-essentials@6.0.0-beta.20 \
@storybook/addon-storysource@6.0.0-beta.20  @storybook/preset-typescript@1.2.0 \
@storybook/react@6.0.0-beta.20 core-js@2.6.5 react-docgen-typescript@1.16.5 \
react-docgen-typescript-loader@3.6.0

npx -p @storybook/cli sb init -f
vim .storybook/main.js
vim .storybook/preview.js
vim preview-head.html
vim webpack.config.js

Next, we will update the main.js file. This will tell Storybook where to look for the stories, in this case in the src folder any file called x.stories.mdx or x.stories.tsx.

module.exports = {
  stories: ["../src/**/*.stories.@(tsx|mdx)"],
  addons: [
    "@storybook/addon-essentials",
    "@storybook/addon-docs",
    "@storybook/preset-typescript",
  ],
};

Next, let’s update the preview file. Here you can define global parameters and decorators. Again will see more of this in the next article.

import React from 'react';

import { withA11y } from '@storybook/addon-a11y';
import { action } from '@storybook/addon-actions';
import { configure, addDecorator, addParameters } from '@storybook/react';
import { INITIAL_VIEWPORTS } from '@storybook/addon-viewport';

// We will address this later.
import '../src/styles/globals.css';
import './main.css';

// automatically import all files ending in *.stories.js
configure(require.context('../src', true, /\.stories\.mdx$/), module);

// Gatsby Setup
// ============================================
// Gatsby's Link overrides:
// Gatsby defines a global called ___loader to prevent its method calls from creating console errors you override it here
global.___loader = {
  enqueue: () => {},
  hovering: () => {},
};
// Gatsby internal mocking to prevent unnecessary errors in storybook testing environment
global.__PATH_PREFIX__ = '';
// This is to utilized to override the window.___navigate method Gatsby defines and uses to report what path a Link would be taking us to if it wasn't inside a storybook
window.___navigate = (pathname) => {
  action('NavigateTo:')(pathname);
};

// Storybook Addons
// ============================================
addParameters({
  viewport: {
    viewports: INITIAL_VIEWPORTS,
    defaultViewport: 'responsive',
  },
  options: {
    panelPosition: 'right',
    storySort: (a, b) =>
      a[1].kind === b[1].kind
        ? 0
        : a[1].id.localeCompare(b[1].id, undefined, { numeric: true }),
  },
  inline: true,
});

// Storybook Decorators
// ============================================
addDecorator(withA11y);

If we want to use any custom fonts, such as google fonts or other styles within our Tailwind, we need to define them here.

<link
  href="https://fonts.googleapis.com/css2?family=Inter:wght@600,900&display=swap"
  rel="stylesheet"
/>

Storybook uses webpack, so if we want to add extra webpack options, we do that here. This allows us to use things like Babel and PostCSS loader.

module.exports = ({ config }) => {
  config.module.rules[0].use[0].loader = require.resolve("babel-loader");
  config.module.rules[0].use[0].options.presets = [
    require.resolve("@babel/preset-react"),
    require.resolve("@babel/preset-env"),
  ];

  config.module.rules.push({
    test: /\.(ts|tsx)$/,
    loader: require.resolve("babel-loader"),
    options: {
      presets: [["react-app", { flow: false, typescript: true }]],
      plugins: [],
    },
  });

  config.module.rules.push({
    test: /\.css$/,
    use: [
      {
        loader: "postcss-loader",
        options: {
          sourceMap: true,
          config: {
            path: "./.storybook/",
          },
        },
      },
    ],
  });

  return config;
};

Add-ons

Let’s install the extra add-ons we will use with storybooks:

a11y: Will list any accessibility issues with your component
controls: Is the new version of the addon-knobs and will let you control the props you pass in
viewport: Allows you to test how your component looks, with different viewports like iPhone, 13" etc

yarn add --dev @storybook/addon-a11y@6.0.0-beta.20 @storybook/addon-controls@6.0.0-beta.15 \
                @storybook/addon-viewport@6.0.0-beta.20

Let’s update the .storybook/main.js so that Storybook uses the new addons we’ve just installed.

module.exports = {
  stories: ["../src/**/*.stories.@(tsx|mdx)"],
  addons: [
    "@storybook/addon-a11y",
    "@storybook/addon-controls",
    "@storybook/addon-essentials",
    "@storybook/preset-typescript",
    "@storybook/addon-viewport",
  ],
};

Next, let’s update .storybook/preview.js so it looks like:

import React from 'react';

import { withA11y } from '@storybook/addon-a11y';
import { action } from '@storybook/addon-actions';
import { configure, addDecorator, addParameters } from '@storybook/react';
import { INITIAL_VIEWPORTS } from '@storybook/addon-viewport';

// We will address this later.
import '../src/styles/globals.css';
import './main.css';

// automatically import all files ending in *.stories.js
configure(require.context('../src', true, /\.stories\.mdx$/), module);

// Gatsby Setup
// ============================================
// Gatsby's Link overrides:
// Gatsby defines a global called ___loader to prevent its method calls from creating console errors you override it here
global.___loader = {
  enqueue: () => {},
  hovering: () => {},
};
// Gatsby internal mocking to prevent unnecessary errors in storybook testing environment
global.__PATH_PREFIX__ = '';
// This is to utilized to override the window.___navigate method Gatsby defines and uses to report what path a Link would be taking us to if it wasn't inside a storybook
window.___navigate = (pathname) => {
  action('NavigateTo:')(pathname);
};

// Storybook Addons
// ============================================
addParameters({
  viewport: {
    viewports: INITIAL_VIEWPORTS,
    defaultViewport: 'responsive',
  },
  options: {
    panelPosition: 'right',
    storySort: (a, b) =>
      a[1].kind === b[1].kind
        ? 0
        : a[1].id.localeCompare(b[1].id, undefined, { numeric: true }),
  },
  inline: true,
});

// Storybook Decorators
// ============================================
addDecorator(withA11y);

The following snippet allows Storybook to show the default list of viewports. You can customise this list by following this README here.

viewport: {
  viewports: INITIAL_VIEWPORTS,
  defaultViewport: "responsive",
}

This part of the addParameters sorts all of our storybook components in descending capital order (in the left panel).

options: {
  panelPosition: "right",
  storySort: (a, b) =>
    a[1].kind === b[1].kind
      ? 0
      : a[1].id.localeCompare(b[1].id, undefined, { numeric: true }),
},

The final part will add a panel which will list accessibility (a11y) issues with our components, such as missing an alt in an tag.

addDecorator(withA11y);

MDX

MDX is markdown mixed with JSX, it lets us render “React” code within markdown files, whilst providing all the features of markdown as well as headers and hyperlinks. So I feel it is a perfect way to document your Storybooks.

Introduction MDX

This file is an example of a story which will not render any of our components. It’s simply there for documentation. This file will list the colour palette of the app. It will get the colours from our tailwind.config.js (mixed with the default one). So if you changed the values in the tailwind config file, it’ll also change them in this story.

import {
  Meta,
  ColorPalette,
  ColorItem,
  Typeset,
} from "@storybook/addon-docs/blocks";

import { Themes } from "~/styles";
import { theme } from "~/utils/tailwindConfig";



# Introduction

This project uses Tailwindcss so a lot of colour props are passed in as CSS classes that
Tailwind applies styling to i.e. `text-blue-500` to use the primary blue. You can find the
full colour palette [here](https://tailwindcss.com/docs/customizing-colors/#default-color-palette).

## Colours

### Light Theme


      title="theme.color.background"
    subtitle="White"
    colors={[theme.colors.white]}
  />
      title="theme.color.text"
    subtitle="Black"
    colors={[theme.colors.black]}
  />
      title="theme.color.header"
    subtitle="Grey"
    colors={[theme.colors.gray[700]]}
  />


### Dark Theme


      title="theme.color.background"
    subtitle="White"
    colors={[theme.colors.gray[900]]}
  />
      title="theme.color.text"
    subtitle="White"
    colors={[theme.colors.white]}
  />
      title="theme.color.header"
    subtitle="Grey"
    colors={[theme.colors.gray[200]]}
  />


### Shared


      title="theme.color.primary"
    subtitle="Blue"
    colors={[theme.colors.blue[500]]}
  />
      title="theme.color.secondary"
    subtitle="Orange"
    colors={[theme.colors.orange[500]]}
  />
      title="theme.color.tertiary"
    subtitle="Grey"
    colors={[theme.colors.gray[500]]}
  />
      title="Monochrome"
    colors={[
      theme.colors.monochrome[900],
      theme.colors.monochrome[800],
      theme.colors.monochrome[700],
      theme.colors.monochrome[600],
      theme.colors.monochrome[500],
      theme.colors.monochrome[400],
      theme.colors.monochrome[300],
      theme.colors.monochrome[200],
      theme.colors.monochrome[100],
    ]}
  />


## Typography

### Header

**Font**: Inter
**Weight**: 900

The first part contains our imports so we can render the colours correctly. It also includes a meta tag where we list the title of the page, each of our stories should have one of these meta tags.

import {
Meta,
ColorPalette,
ColorItem,
Typeset,
} from "@storybook/addon-docs/blocks";

import { Themes } from "~/styles";
import { theme } from "~/utils/tailwindConfig";

Utils

We use this simple script to resolve the values of the tailwind config so we can use them like so theme.colors.orange[500]. We pass the script our current config, it then combines it with the default config and generates a final tailwind config. From this, we get the theme part as this is all we need to retrieve our colours. So with a class name of say text-blue-500 to get the colour, we would do theme.colors.blue[500].

import resolveConfig from 'tailwindcss/resolveConfig';

import tailwindConfig from '../../tailwind.config';

const config = resolveConfig(tailwindConfig);
const { theme } = config;

export default config;
export { theme };

Component

Now let’s take a look at how to create a Storybook story for one of our components.

Logo

Say we have a component that looks like:

import React from 'react';
import tw from 'twin.macro';

export interface Props {
  /** The colour of the opening and closing tags. */
  accent?: string;
  /** The colour of main text. */
  color?: string;
  /** The colour when you hover over the logo. */
  hoverColor?: string;
  /** The main text of the logo for example, your name. */
  text: string;
  /** The size of the main text  */
  size?: 'xs' | 'sm' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl';
}

const Logo = ({
  accent = 'black',
  color = 'black',
  hoverColor = 'blue-500',
  text,
  size = '2xl',
}: Props) => (
  <LogoContainer
    className={`hover:text-${hoverColor} text-${color} lg:text-${size}
    md:text-xl sm:text-md text-sm`}
  >
    <Tag className={`text-${accent}`} data-testid="OpeningTag">
      &lt;
    Tag>
    {text}
    <Tag className={`text-${accent}`} data-testid="ClosingTag">
      /&gt;
    Tag>
  LogoContainer>
);

const LogoContainer = tw.div`cursor-pointer font-header font-black tracking-wide `;

const Tag = tw.span``;

export default Logo;

Since we are using Typescript, we define our props as an interface. The comments above each item in the interface will be parsed by docgen and shown in our story (we will see this a bit later). It will let the user know what the prop is so they know how to adjust it. We will also see in a little bit.

The rest of the file is a normal React component, nothing special here. So how do we document this with Storybooks UI?

Logo.stories.mdx

So now onto the real meat and potatoes of this article, let’s document a React component. So I think one of the coolest parts of the new Storybook is the controls add-on we installed earlier. So how we do this is to provide the props as args object. Then we pass this onto the component give a name called Basic below.

import { Meta, Story, Preview, Props } from "@storybook/addon-docs/blocks";

import { theme } from "~/styles";
import Logo from "./Logo";



# Logo


      name="Basic"
    args={{
      accent: "gray-500",
      color: "black",
      hoverColor: "blue-500",
      text: "Haseeb",
    }}
  >
    {(args) => }
  




## Accent

You can adjust the accent (tags) color by passing the `accent` prop.


  
    
              accent="gray-500"
        color="blue-500"
        text="Haseeb"
        hoverColor="blue-500"
      />
              accent="gray-500"
        color="black"
        text="Haseeb"
        hoverColor="blue-500"
      />
    
  


## Colour

You can change the default colour of the logo by passing the `color` prop.


  
    
              accent="gray-500"
        color="gray-500"
        text="Haseeb"
        hoverColor="blue-500"
      />
              accent="gray-500"
        color="blue-500"
        text="Haseeb"
        hoverColor="blue-500"
      />
    
  


## Hover Color

You can change the hover colour of the logo by passing the `hoverColor` prop.


  
    
              accent="gray-500"
        color="gray-500"
        text="Haseeb"
        hoverColor="blue-500"
      />
              accent="gray-500"
        color="gray-500"
        text="Haseeb"
        hoverColor="gray-500"
      />
    
  


## Text

You must set the main text for the logo, such as a name using the `text` prop.


  
    
      
      
      
      
    
  


## Size

You can also adjust the size of the logo by passing the `size` prop.


  
    
      
      
      
      
      
      
      
    
  


## Dark Mode

Example dark mode component.


  
    `bg-${theme.dark.background} p-5`}>
              accent="gray-500"
        color={theme.dark.text}
        hoverColor={theme.colors.primary}
        text="Haseeb"
      />

In the diagram below is the docs tab in Storybook (default is the canvas tab). As you can see in the diagrams below we have a table which is taken from the props in our Logo component. We also have the comments shown as descriptions, any default values we assigned and the current value. Which we set above in the stories file Logo.stories.mdx. We can then edit the values within the controls table, it will automatically re-render our component on the fly. You can see this in the second image.

Then we can define our regular stories components like so:

## Accent

You can adjust the accent (tags) color by passing the `accent` prop.


  
    
              accent="gray-500"
        color="blue-500"
        text="Haseeb"
        hoverColor="blue-500"
      />
              accent="gray-500"
        color="black"
        text="Haseeb"
        hoverColor="blue-500"
      />
    
  


## Colour

You can change the default colour of the logo by passing the `color` prop.


  
    
              accent="gray-500"
        color="gray-500"
        text="Haseeb"
        hoverColor="blue-500"
      />
              accent="gray-500"
        color="blue-500"
        text="Haseeb"
        hoverColor="blue-500"
      />

The example above will be rendered into something shown in the image below. You can see from this example we are now mixing our React component with our normal markdown syntax. This provides a very flexible way to document our components. It allows others to interact with and look at an example of its use.

That’s about it documentation wise! Taking a look at the other features we added you can see the a11y issues in a panel (either on the bottom or on the right of when you are in the canvas tab). You can see this in the diagram below.

Then at the top of the screen, we just adjust the viewport and see how our component would look at different resolutions. The default list we have includes resolutions for devices like various iPhones, Google Pixel and Galaxy Sx. You can see this in the diagram below.

Run

We can run the Storybook UI from our source code like so:

git clone https://gitlab.com/hmajid2301/articles.git
cd articles/30.\ Storybooks,\ Gatsby\ and\ MDX\ II/source_code/
yarn
yarn storybook

With all of this setup now we can focus on a component first approach I like to use atomic design alongside Storybooks UI. To create all of the components of my website before I start work on the pages themselves. This allows me to work out exactly what each page will need, break them down into its core parts and work on them one at a time. Anyways that’s it, thanks for reading!

Appendix

How to use Storybooks, Gatsby, Babel, Tailwind, Typescript together

Me — Mon, 29 Jun 2020 00:00:00 +0000

Recently I started to re-design my website, I decided to use this as an opportunity to learn some new technologies such as Gatsby, Tailwind. I also decided to try using Storybook. For this said project I used MDX to create my Storybook stories. In this article, I will show you how you can create Storybooks stories, for a Gatsby project with TailwindCSS, Typescript using MDX.

You can find an example project using this here. You can also find a demo site for said project.

This article assumes you already familiar with Typescript, TailwindCSS and Gatsby.

Storybook

Storybook is an open source tool for developing UI components in isolation for React, Vue, and Angular. It makes building stunning UIs organized and efficient. - Storybook Website

Storybook allows us to create and test (visually) components in isolation. It can be a great way to both document all of your components but also speed up development as all you need to focus on is one component at a time. Storybook also has a ton of extra plugins/addons which can help to customise storybooks to your liking. One such example being checking for any accessibility issues your components may have.

MDX

MDX is a combination of markdown mixed with JSX. It allows us to “execute” and “render” JSX code from within an MDX document. When used with Storybook it means we get all of the flexibility of markdown. So we can use normal markdown syntax, to document our component. We also get access to MDX-flavored Component Story Format (CSF) which includes a collection of components called “Doc Blocks”, that allow Storybook to translate MDX files into storybook stories.

Setup

OK let’s go over what we need to do, first let’s create our gatsby site by using the gatsby-cli tool.

gatsby new gatsby-site
cd gatsby-site

TailwindCSS

Now let’s see how we add tailwindcss to this site:

yarn add gatsby-plugin-typescript gatsby-plugin-postcss tailwindcss twin.macro postcss-preset-env
vim gatsby-config.js
vim postcss.config.js
vim tailwind.config.js
mkdir -p src/styles/
vim src/styles/globals.css
vim gatsby-browser.js

We need to update the gatsby-config.js file to add support for both typescript and PostCSS. Tailwind is written in PostCSS so we need to include that in our gatsby file. You can either replace the default gatsby-config.js or update the plugins.

const plugins = ["gatsby-plugin-typescript", "gatsby-plugin-postcss"];

module.exports = {
  plugins,
};

Next we add a postcss.config.js file as per the Tailwind instructions found here.

const tailwindcss = require('tailwindcss');

module.exports = () => ({
  plugins: [tailwindcss],
});

Finally, we create a tailwind.config.js file. Here we can add new colours, overwrite existing colours and extend the configuration such as adding news fonts (Inter). This file will get merged with the default config by Tailwind.

module.exports = {
  theme: {
    themeVariants: ["dark"],
    extend: {
      colors: {
        blue: {
          100: "#EBF2FD",
          200: "#CDDFFA",
          300: "#AFCBF6",
          400: "#72A5F0",
          500: "#367EE9",
          600: "#3171D2",
          700: "#204C8C",
          800: "#183969",
          900: "#102646",
        },
        monochrome: {
          900: "#333",
          800: "#444",
          700: "#666",
          600: "#999",
          500: "#ddd",
          400: "#eee",
          300: "#f3f3f3",
          200: "#f8f8f8",
          100: "#fff",
        },
      },
      fontFamily: {
        header: ["Inter"],
      },
    },
  },
  variants: {},
};

Next, to add the Tailwind styles or our app we need to create a CSS file, you can call this file whatever you want, you just need to make sure it gets imported in such a place it can be used by any of your components.

@tailwind base;
@tailwind components;
@tailwind utilities;

One place we can import this is in the gatsby-brower.js file. It should be empty, add the import shown below. We will add babel later on in the app, which will allow us to use imports in the style we’ve just described. In this example, we will use the ~ to mean src.

import "~/styles/globals.css";

Typescript

Now let’s add typescript to our project:

yarn add --dev react-docgen-typescript react-docgen-typescript-loader ts-loader typescript
vim tsconfig.json

We will add some extra libraries that will be used by Storybooks to parse our Typescript components. Like all Typescript projects, we need to include a tsconfig.json file. Note we add the "paths" so we can have cleaner imports, this will be used alongside Babel.

{
  "compileOnSave": false,
  "compilerOptions": {
    "target": "es5",
    "module": "es6",
    "types": ["node"],
    "moduleResolution": "node",
    "esModuleInterop": true,
    "lib": ["dom", "es2015", "es2017"],
    "jsx": "react",
    "sourceMap": true,
    "strict": true,
    "resolveJsonModule": true,
    "noUnusedLocals": true,
    "noImplicitAny": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true,
    "allowSyntheticDefaultImports": true,
    "downlevelIteration": true,
    "baseUrl": "./",
    "paths": {
      "~/*": ["src/*"]
    }
  },
  "include": ["./src/**/*"],
  "exclude": ["node_modules", "plugins"]
}

Babel

yarn add --dev babel-plugin-module-resolver babel-preset-gatsby babel-preset-react-app @babel/compat-data \
@babel/core @babel/preset-env babel-loader

vim .babelrc

Gatsby automatically uses Babel, however, to customise babel we need to create our own .babelrc file. You can read more about it here. The main reason we want to use it is to allow use to have cleaner imports. So we can use ~ instead of src in imports. So we can do import "~/styles/globals.css"; instead of import "../../../styles/globals.css"'.

You can read more about it here, I wrote a previous article on this topic.

{
  "env": {},
  "plugins": [
    [
      "module-resolver",
      {
        "root": ["./src"],
        "alias": {
          "~": "./src"
        }
      }
    ]
  ],
  "presets": [
    [
      "babel-preset-gatsby",
      {
        "targets": {
          "browsers": [">0.25%", "not dead"]
        }
      }
    ]
  ]
}

Storybook

We will use the latest versions of Storybook (v6) so we can access the latest features. We will go over how we can use these features in the next article.

First remove any lines in your package.json that start with @storybook. In my case, I removed @storybook/addon-actions, @storybook/add-links, @storybook/addons and @storybook/react.

yarn add --dev @storybook/addon-docs@6.0.0-beta.20 @storybook/addon-essentials@6.0.0-beta.20 \
@storybook/addon-storysource@6.0.0-beta.20  @storybook/preset-typescript@1.2.0 \
@storybook/react@6.0.0-beta.20 core-js@2.6.5

npx -p @storybook/cli sb init -f
vim .storybook/main.js
vim .storybook/preview.js
vim preview-head.html
vim webpack.config.js

Next, we will update the main.js file. This will tell Storybook where to look for the stories, in this case in the src folder any file called x.stories.mdx or x.stories.tsx.

module.exports = {
  stories: ["../src/**/*.stories.@(tsx|mdx)"],
  addons: [
    "@storybook/addon-essentials",
    "@storybook/addon-docs",
    "@storybook/preset-typescript",
  ],
};

Next, lets update the preview file. Here is typically you can define global parameters and decorators. Again will see more of this in the next article.

import React from "react";

import { action } from "@storybook/addon-actions";
import { configure } from "@storybook/react";

import "../src/styles/globals.css";
import "./main.css";

configure(require.context("../src", true, /\.stories\.mdx$/), module);

global.___loader = {
  enqueue: () => {},
  hovering: () => {},
};
global.__PATH_PREFIX__ = "";
window.___navigate = (pathname) => {
  action("NavigateTo:")(pathname);
};

If we want to use any custom fonts, such as google fonts or other styles within our Tailwind, we need to define them here.

<link
  href="https://fonts.googleapis.com/css2?family=Inter:wght@600,900&display=swap"
  rel="stylesheet"
/>

Storybook uses webpack, so if we want to add extra webpack options, we do that here. This allows us to use things like Babel and PostCSS loader.

module.exports = ({ config }) => {
  config.module.rules[0].use[0].loader = require.resolve("babel-loader");
  config.module.rules[0].use[0].options.presets = [
    require.resolve("@babel/preset-react"),
    require.resolve("@babel/preset-env"),
  ];

  config.module.rules.push({
    test: /\.(ts|tsx)$/,
    loader: require.resolve("babel-loader"),
    options: {
      presets: [["react-app", { flow: false, typescript: true }]],
      plugins: [],
    },
  });

  config.module.rules.push({
    test: /\.css$/,
    use: [
      {
        loader: "postcss-loader",
        options: {
          sourceMap: true,
          config: {
            path: "./.storybook/",
          },
        },
      },
    ],
  });

  return config;
};

Component

Finally, let’s create a component that we will create a story for. First, create a new folder at src/components/Logo. In that folder let’s create the following files:

Note the comments in the Props will be the comments shown in our story later, if you use the correct addons for Storybook. We will go over this in the next article.

import React from 'react';
import tw from 'twin.macro';

export interface Props {
  /** The colour of the opening and closing tags. */
  accent?: string;
  /** The colour of main text. */
  color?: string;
  /** The colour when you hover over the logo. */
  hoverColor?: string;
  /** The main text of the logo for example, your name. */
  text: string;
  /** The size of the main text  */
  size?: 'xs' | 'sm' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl';
}

const Logo = ({
  accent = 'black',
  color = 'black',
  hoverColor = 'blue-500',
  text,
  size = '2xl',
}: Props) => (
  <LogoContainer
    className={`hover:text-${hoverColor} text-${color} lg:text-${size}
    md:text-xl sm:text-md text-sm`}
  >
    <Tag className={`text-${accent}`} data-testid="OpeningTag">
      &lt;
    Tag>
    {text}
    <Tag className={`text-${accent}`} data-testid="ClosingTag">
      /&gt;
    Tag>
  LogoContainer>
);

const LogoContainer = tw.div`cursor-pointer font-header font-black tracking-wide `;

const Tag = tw.span``;

export default Logo;

This index file makes it easier to import the component from other files. As we don’t have to do import {Logo} from "src/components/Logo/Logo.ts we can use import {Logo} from "src/components/Logo.

export { default as Logo } from './Logo';

Storybook

Now we have set everything up but do we create a story for our component. First, create a new file at src/components/Logo/Logo.stories.mdx. You could keep this in another folder like storybooks/ or keep it in the same folder as your component, it’s all personal preference. Some people will also have all unit tests in the same folder src/components/Logo/.

import { Meta, Story, Preview, Props } from "@storybook/addon-docs/blocks";

import Logo from "./Logo";



# Logo

## Accent

You can adjust the accent (tags) color by passing the `accent` prop.

Add the following to your package.json to the “scripts” section. We need to pass it the NODE_ENV=test environment variable, else the Gatsby Babel plugin will complain.

"storybook": "NODE_ENV=test start-storybook -p 6006",
"build-storybook": "NODE_ENV=test build-storybook"

Now we can run our Storybook by running the following command:

yarn storybook

That’s it! We managed to get Storybook to work with Gatsby. Where Gatsby is using Tailwind, Babel and Typescript.