Open-Source Pattern Library Tutorial: Part 1 — Setting Up Your Gatsby Application

• Part 1 — Setting Up Your Gatsby Application
• Part 2 — Deploying to Netlify & Netlify-CMS
• Part 3 — Building Pattern Pages
• Part 4 — Searchable List
• Part 5 — Card View

In this first part of the tutorial, we will begin by setting up your Gatsby project, saving it to a repo, and setting up the basic layout for the application.

Prerequisites

This tutorial is written with the assumption that you have some experience with Reactjs. If you are unfamiliar with React, you can still follow this tutorial, I just won’t be explaining any of the React or JavaScript specific code.

It is also assumed that you have some knowledge of git and node and how to use them on the command line.

This tutorial is also written with the assumption that you are using the Mac OS. If you are using Windows or Linux I suggest checking the corresponding link:

Gatsby on Windows

Gatsby on Linux

Creating Your Gatsby Project

First things first, we need to create our Gatsby project. To do that, use your terminal to navigate to wherever you’d like to save your project folder. You can run the following commands to install the gastby-cli globally and create your project or you can use npx to use Gatsby without installing the CLI to your machine:

The Node Package Manager (npm) is an online repository for open-source Node.js packages, and it is also a command line tool that allows you to manage those packages for your own projects. One of the new tools it has is the npx command which allows you to access CLI tools and executables from a package without having to install that entire package.

Gatsby needs node v4.0.0 or higher to work correctly, you can check what version of node you are running by running the command node -v in your terminal.

Running the gatsby new command creates your project a new directory with the name that you specify, so keep that in mind when deciding where to run the command.

When creating a new project, Gatsby may prompt you asking if you prefer to yarn or npm as your package manager. You may choose to use either, but after we create the project I will be using yarn for the remainder of the tutorial.

Installing Gatsby CLI

npm install -g gatsby-cli
gatsby new <project-name>

Using npx

npx gatsby new <project-name>

Change Directories

Now you can change directories into your new <project-name> folder:

cd project-name

Creating a Repo

If you’re not familiar with creating repositories from existing directories, we recommend using GitHub Desktop to create a repo using the directory we just made:

1. If you haven’t already, create an account at github.com
2. Download and install GitHub Desktop from https://desktop.github.com/ and login.
3. Clone the repository you previously created by gatsby new <project-name> :

…. add > add existing repository > directory now called <project-name>

Installing Material-UI

For this project, I chose to use a combination of Material-UI and CSS to style my application. I am going to show you how I built the layout using Material-UI, but feel free to style your pattern library however you like.

To access all of the Material-UI components and icons that I use in this project, you need to run the following commands in your project directory. I’m going to be using yarn to install the rest of the dependencies, but you may use npm if you wish:

Add material-ui core components:

yarn add @material-ui/core

Add material-ui icons:

yarn add @material-ui/icons

Setting Up Your Gatsby-Config

Because Gatsby is a static-site generator and builds all of the assets on the client-side, we need to install a Gatsby plugin for Gatsby to able to build our application with Material-UI components successfully. Run the following command to install the plugin:

yarn add gatsby-plugin-material-ui @material-ui/styles

Now go open up your project in your preferred IDE and find a file in the root directory called gatsby-config.js, it should look something like this:

module.exports = {
  siteMetadata: {
    title: `Gatsby Default Starter`,
    description: `Kick off your next, great Gatsby project with this default starter. This barebones starter ships with the main Gatsby configuration files you might need.`,
    author: `@gatsbyjs`,
  },
  plugins: [
    `gatsby-plugin-react-helmet`,
    {
      resolve: `gatsby-source-filesystem`,
      options: {
        name: `images`,
        path: `${__dirname}/src/images`,
      },
    },
    `gatsby-transformer-sharp`,
    `gatsby-plugin-sharp`,
    {
      resolve: `gatsby-plugin-manifest`,
      options: {
        name: `gatsby-starter-default`,
        short_name: `starter`,
        start_url: `/`,
        background_color: `#663399`,
        theme_color: `#663399`,
        display: `minimal-ui`,
        icon: `src/images/gatsby-icon.png`, // This path is relative to the root of the site.
      },
    },
    // this (optional) plugin enables Progressive Web App + Offline functionality
    // To learn more, visit: https://gatsby.dev/offline
    // `gatsby-plugin-offline`,
  ],
}

We’re going to make a few changes to this file. Namely, we’re going to update the site metadata and add gatsby-plugin-material-ui to the plugins array. Once you're done it should look something like this:

module.exports = {
  siteMetadata: {
    title: `Pattern Library Tutorial`,
    description: `A tutorial to show how to build a pattern library using Gatsby and Netlify-CMS`,
    author: `@marcello.paiva`,
  },
  plugins: [
    `gatsby-plugin-react-helmet`,
    `gatsby-plugin-material-ui`,
    {
      resolve: `gatsby-source-filesystem`,
      options: {
        name: `images`,
        path: `${__dirname}/src/images`,
      },
    },
    `gatsby-transformer-sharp`,
    `gatsby-plugin-sharp`,
    {
      resolve: `gatsby-plugin-manifest`,
      options: {
        name: `gatsby-starter-default`,
        short_name: `starter`,
        start_url: `/`,
        background_color: `#663399`,
        theme_color: `#663399`,
        display: `minimal-ui`,
        icon: `src/images/gatsby-icon.png`, // This path is relative to the root of the site.
      },
    },
    // this (optional) plugin enables Progressive Web App + Offline functionality
    // To learn more, visit: https://gatsby.dev/offline
    // `gatsby-plugin-offline`,
  ],
}

Creating a Custom Theme

One of the ways that I will be styling this application is by using Material-UI’s theme generator to configure the theme used by the MUI components. Create a new file in your src/components/ directory called theme-provider.js and paste in the following code:

import React from "react"
import { createMuiTheme, ThemeProvider } from '@material-ui/core'

const theme = createMuiTheme({
    typography: {
      fontFamily: [
        'KnowledgeLight',
        'Raleway',
        'Helvetica',
        'Arial',
        'sans-serif',
        '"Apple Color Emoji"',
        '"Segoe UI Emoji"',
        '"Segoe UI Symbol"',
      ].join(','),
    },
    palette: {
      primary: {
        main: '#ff8001'
      },
    }
  })

  const Theme = ({ path, children }) => {
    return (
      <ThemeProvider theme={theme}>
          {children}
      </ThemeProvider>
    )
  }
  export default Theme

Great! Now we have to wrap our entire application in the ThemeProvider so that the MUI components in our applications are inheriting these styles. Let’s create another file in our root directory called wrap-with-context.js. We're going to use the wrapRootElement function from the Gatsby Browser and SSR APIs to wrap our application with this theme. Copy the following code into the file you just made:

const React = require("react")
const ThemeProvider = require('./src/components/theme-provider').default

exports.wrapRootElement = ({ element }) => {
  return (
    <ThemeProvider>
      {element}
    </ThemeProvider>
  )
}

Now go to the gatsby-browser.js and gatsby-ssr.js files and paste this block of code underneath the comment block in each file:

const { wrapRootElement } = require('./wrap-with-context')

exports.wrapRootElement = wrapRootElement

And now you can make use of your custom theme across your app.

Setting Up App Layout & Styles

Index.css

Create a new directory within src/ called styles/ and within that directory create a new file called index.css. Paste the following code into src/styles/index.css:

body {
  font-family: KnowledgeLight, Raleway, Helvetica, Arial, sans-serif;
  background-color: #f3f3f3;
}

Index.js

Make your way to the src/pages/index.js file. This file will serve as the home page of your site. Right now it's populated with the default landing page that Gatsby provides. Let's strip all that down and replace it with this:

import React from "react"
import '../styles/index.css'
import Layout from "../components/layout"
import SEO from "../components/seo"

const IndexPage = () => (
  <Layout>
    <SEO title="Pattern Library" />
  </Layout>
)

export default IndexPage

Layout

That’s better, now let’s take a look at the src/components/layout.js. Similarly, we're going to want to remove the default styles from there and replace it with our own styles with the makeStyles() function from Material-UI like so:

/**
 * Layout component that queries for data
 * with Gatsby's useStaticQuery component
 *
 * See: https://www.gatsbyjs.org/docs/use-static-query/
 */

import React from "react"
import PropTypes from "prop-types"
import { useStaticQuery, graphql } from "gatsby"
import { makeStyles } from '@material-ui/core'
import Header from "./header"

const useStyles = makeStyles({
  main: {
    display: 'flex',
    flexDirection: 'column',
    alignItems: 'center',
    margin: '0 auto',
    maxWidth: '80%',
    marginTop: '64px',
  },
})

const Layout = ({ children }) => {
  const classes = useStyles()
  const data = useStaticQuery(graphql`
    query SiteTitleQuery {
      site {
        siteMetadata {
          title
        }
      }
    }
  `)

  return (
    <>
      <Header siteTitle={data.site.siteMetadata.title} />
      <main className={classes.main}>{children}</main>
    </>
  )
}

Layout.propTypes = {
  children: PropTypes.node.isRequired,
}

export default Layout

Header

Now that our Layout component is all set, let’s get our header set up. Find the src/components/header.js file and replace it with the following code:

import { Link } from 'gatsby'
import PropTypes from 'prop-types'
import React from 'react'
import { AppBar, Toolbar, Typography, makeStyles } from '@material-ui/core'
import HomeIcon from '@material-ui/icons/Home';

const useStyles = makeStyles(theme => ({
  link: {
    textDecoration: 'none',
    color: 'inherit',
    display: 'flex',
    alignItems: 'center',
    flexGrow: 1
  },
  header: {
    backgroundColor: '#333333',
    borderTop: 'solid 2px #ff8001',
    position: 'fixed',
  },
  title: {
    margin: theme.spacing(1),
    color: '#fff',
  },
  linkContainer: {
    width: '100%',
    display: 'flex',
    justifyContent: 'center',
  },
  toolbar: {
    width: '80%'
  }
}))

const Header = ({ siteTitle }) => {
  const classes = useStyles()
  return (
    <AppBar className={classes.header}>
      <div className={classes.linkContainer}>
        <Toolbar className={classes.toolbar}>
          <Link to='/' className={classes.link}>
            <HomeIcon className={classes.title} />
            <Typography variant='h6' component='h1' className={classes.title}>{ siteTitle }</Typography>
          </Link>
        </Toolbar>
      </div>
    </AppBar>
  )
}

Header.propTypes = {
  siteTitle: PropTypes.string,
}

Header.defaultProps = {
  siteTitle: ``,
}

export default Header

Run Your Application

We’ve finished setting up the foundation for our application’s UI! Now, let’s see it in action. From your terminal run the following commands to install all of the project’s dependencies and run it locally:

yarn
yarn develop

Now you should be able to check out our application with our styled header that we built! In the next part of the tutorial, we’ll start deploying to Netlify and start setting up our Netlify-CMS backend.

If you are having issues or want to look at the source code for this part, you can checkout the part1 branch of the plib-tutorial

Part 2 — Deploying to Netlify & Netlify-CMS

If you are having issues or want to look at the source code for this part, you can checkout the part1 branch of the plib-tutorial repo:

MarcelloPaiva/plib-tutorial