Redesigning my portfolio page with Gatsby (part 2): the tutorial, what’s different from vanilla React?

5 min readAug 10, 2020

Although Gatsby is built upon React, and many of us are comfortable with the React framework, there are many distinguishing features. So, I thought the best approach would be to comb through the Gatsby team’s official tutorial, for any useful nuggets along the way. I’ll be starting part zero of their tutorial. For each section, I’ll point out things that seems to be unique to the platform versus vanilla React — Hopefully saving your time if you’re already familiar with React and want to get going with Gatsby.

0. Set Up Your Development Environment

Everything here was fairly smooth, and Gatsby has its own CLI tool to provide a modified version of create-react-app called gatsby new. On Ubuntu, my version of node (13.5.0) failed to build with gatsby new, but switching to (11.15.0) temporarily fixed the issue. The rest of the tutorial at this point was basic things I already had taken care of on my machine (git, an IDE, etc).

1. Get to Know Gatsby Building Blocks

Primarily, Gatsby offers two ways of ‘templating’ to get started: starters and themes. The distinction here is that starters can’t be updated after you begin from one, so there’s no going back or rebasing with updates to starter materials. With themes, you’re able to import changes to the theme as their developers introduce them.

With Gatsby pages, anything you put in src/pages/, automatic routing will make the page accessible at localhost:wxyz/pagenamehere. Just like standard React apps hosted on a development server. At this point in the docs, I had a problem with their tutorial:

Using their code, I was initially confused as to why it wouldn’t compile. The hightlight-start and hightlight-end commented out code seemed to be causing an issue, but I wasn’t exactly sure as to why. I looked up React comment syntax and… yup, looked good. After tinkering, I realized that comments need to exist inside of a <div /> element somewhere. Upon emailing them to alert them of the error, I was impressed to see them get back to me within 24 hours!

Hi Corey!
Thanks for pointing that out! Looks like we’ve got a bug with our highlighting syntax — that shouldn’t even be displaying! It should look like the attached. We’ll get it fixed — thanks for letting us know!

The fixed version of their code — The fixed image. A+ for their quick and informative staff!

This section of the tutorial also introduces sub-components, components you wish to reuse in multiple pages (such as a header or footer), which it recognizes in src/components. This is in contrast to page components, which are the automatically routed-to pages mentioned earlier. The rest of this section introduces things that are also React standard, such as the Link component and syntax <Link />. However, the section ends with instructions on how to specifically continuously deploy your Gatsby site using Surge and their very own Gatsby Cloud.

Give your components love and style, swag them out like these figurines. Photo by Jack B on Unsplash

2. Introduction to Styling in Gatsby

Generally, most of what you know in React applies here. Want to use SCSS? Make sure and npm install it. One exception here is for your universal css file (usually styles.css, but in this case must be global.css), you need to declare it within a gatsby-browser.js file, and it will be imported automatically site-wide. Next, component-scoped CSS is introduced, which follows some naming conventions.

import React from "react"
import containerStyles from "./container.module.css"

export default function Container({ children }) {
  return <div className={containerStyles.container}>{children}</div>
}

Then, you create a file called container.module.css with whatever style declarations you desire (in this case, with related to the .container. The entire purpose of scoped styling here is that using files appended with module.css will automatically generate unique class names such as about-css-modules-module-avatar-1ICmi that prevent any conflicts from occurring.

3. Creating Nested Layout Components

Remember the sub-components mentioned above? That’s what we’re working with here, reusable UI and page elements. Here, they introduce the concept of not only React plugins, but Gatsby specific plugins, of which there are plenty of gems to choose from. New to me, is an introduction to the vanilla JS plugin Typography.js and its Gatsby counterpart.

While you can install any plugin you wish to Gatsby, I wanted to install this one to understand how to interact with specific Gatsby-watched files like gatsby-config.js. So, I’ll directly paraphrase part of the docs for a moment to touch on what’s Gatsby unique. If you already use React, not much is new here when installing this plugin and it’s dependencies. npm install --save gatsby-plugin-typography react-typography typography typography-theme-fairy-gates. However, we now need to edit the gatsby-config.js file to include it. Basically, whichever plugins you install, they need to be addressed in the gatsby-config.js file.

module.exports = {
  plugins: [
    {
      resolve: `gatsby-plugin-typography`,
      options: {
        pathToConfigModule: `src/utils/typography`,
      },
    },
  ],
}

NOTE: Let’s talk about ES6 and arrow functions for a moment. If you haven’t noticed by now, the Gatsby docs don’t declare things in the most modern way (I’m assuming to not leave late adopters and legacy code bases out). For example, React boilerplates, via something like the VS Code plugin Code plugin Simple React Snippets, take some extra labor on your part to align with the Gatsby docs. For example:

Gatsby docs explaining out to use a Layout component

import React from "react"

export default function Layout({ children }) {
  return (
    <div style={{ margin: `3rem auto`, maxWidth: 650, padding: `0 1rem` }}>
      <h3>MySweetSite</h3> {/* highlight-line */}
      {children}
    </div>
  )
}

Same idea, with an ES6 arrow function

import React from "react";const Layout = ({ children }) => (
     <div style={{ margin: `3rem auto`, maxWidth: 650, padding: `0 1rem` }}>
       {children}
     </div> );  export default Layout;

The rest of this section centers around the idea of reusable Layout components in React — nothing exclusive here. Although, the next section certainly is and where Gatsby begins to set itself apart.

4. Data in Gatsby…

TO BE CONTINUED…

Check later this next week (of August 10, 2020) for this to be further built out :) Until then!