Getting to know Gatsby

Getting to know Gatsby

It wasn’t without hurdles

So, I moved in into this cottage in New York next to a mysterious mansion. I got it for a good price but I felt someone was watching me from the mansion. I believe it was Mr. Gatsby. Ahem..

Sorry that’s a different story. Let’s start over.

This week I started my first Gatsby project. Gatsby is a react-based framework for creating the statically generated websites and apps. Its ecosystem contains Plugins, Themes and so called Recipes, that automate certain tasks. The official website says:

Create a complete website in the time it usually takes to build a prototype

I was very excited to try it and see if the above is true. I had a good first impression, but encountered some obstacles. Not all were related to Gatsby though. Let’s see how it went.

Photo by [CHUTTERSNAP]( on [Unsplash]( by CHUTTERSNAP on Unsplash

The initial setup was quite straightforward. You can run the following commands to get the project running:

npm install -g gatsby-cli
gatsby new projectname
cd projectname
gatsby develop

What’s next? We could create some React components and display for example the header. But is there any structure I should follow? Let’s ask Mr. Gatsby.js. It turns out we have /pages and /templates folders inside /src. There are many config files too!

|-- /.cache
|-- /plugins
|-- /public
|-- /src
    |-- /pages
    |-- /templates
    |-- html.js
|-- /static
|-- gatsby-config.js
|-- gatsby-node.js
|-- gatsby-ssr.js
|-- gatsby-browser.js

I don’t need to create many pages because my project is a one pager :-) So I will keep only index.js file in there. What about the other folders?

  • /plugins folder hosts any project-specific (“local”) plugins that aren’t published as an npm package.

  • /public folder is automatically generated when we run gatsby build

  • /static — you can put here any file that you don’t want to be processed by webpack. They will be copied to public folder untouched.

The static folder is interesting, because I would assume I could put there the assets like images for example. You might want to minify your images though so it turns out the static folder is useful only for a few less common scenarios.

Ok, where do I put the assets then? I created /images folder inside /src. I did the same for components. Let’s take a look at the plugins now.

Plugins and styling

Plugins are npm packages you can install using command line as you are already used to if you worked on any front end project. You can find a plugin for responsive images, SEO, typescript support and thousands more.

I was thinking how to go about styling. There are also many options to choose from:

  • Using global CSS files with or without youu..Ehm I mean a Layout component

  • Using styled components

  • Using CSS modules

I am not very familiar with CSS in JS approaches yet but I knew I wanted to use Sass. There’s only 1 page I need to style anyway so I don’t need anything fancy. It turns out there is also a plugin for using Sass in Gatsby called gatsby-plugin-sass.

I installed the plugin with the following command (note also node-sass)

npm install node-sass gatsby-plugin-sass

Then we need to edit gatsby-config.js file and add:

plugins: [`gatsby-plugin-sass`]

Here is where the first issue appeared. Trying to run my project I read in the console:

Node Sass version 5.0.0 is incompatible with ^4.0.0.

After some other suggestions, I found out that LibSass and Node Sass are deprecated. What? Who remember implementation in Ruby? The lyrics from Madonna’s song Hang up “Time goes by so slowly” certainly haven’t proved right when it comes to web development. Nevertheless, there is a new Dart implementation so I tried that.

npm install --save-dev sass

and in gatsby-config.js

plugins: [
    resolve: `gatsby-plugin-sass`,
    options: {
      implementation: require("sass"),

Great, this works fine and I can style the components simply by importing it to index.js:

*import* '../styles/styles.scss'

They could update the plugin and set Dart implementation as default.


There must be a plugin for everything, so I searched for ‘fonts’ in the Gatsby repository. The first result was gatsby-plugin-webfonts so I installed that.

// with npm
npm install gatsby-plugin-webfonts

// with yarn
yarn add gatsby-plugin-webfonts

Oh, another error:

error “gatsby-plugin-webfonts” threw an error while running the onPreBootstrap lifecycle:

I am not sure what’s wrong. This package has been downloaded 34.8k times.

Tip: Stick to 1 package management system. Use either npm or yarn

I did another search and this time chose **gatsby-plugin-web-font-loader **(106.1k) that worked just fine.

How to comment out JSX

One last thing I had a bit of difficulty with was JSX. I commented out the code with a shortcut as always but it looked like this:

// <div>
//     <span>some text</span>
// </div>

This is not a proper syntax so I had to investigate again. I reviewed my extensions and found out where the problem lies. I had to do the following:

Uninstall **Babel ES6/ES7 plugin** by dzannotti

Install **Babel JavaScript** by Michael McDermott

The right syntax looks like this:

     <span>some text</span> 


There are many things I haven’t covered and have to learn, but I like Gatsby so far. It’s evolving very quickly and I am excited also about Recipes (new feature). As they put it in the recent press release

It’s a challenge when users enter the Gatsby ecosystem, they have to translate “I want to do x” to how “x” is done in Gatsby

That’s right, I found myself doing that also. Recipes are run from the CLI and automate common tasks like creating pages and layouts, installing plugins and many more. I am coming to React world with some experience of Angular (which uses Angular CLI) so I can only appreciate this step towards better tooling and giving the developers more opinionated ways to build blazing fast web apps. I also found IntelliSense (code completion) lag behind Angular, but that’s maybe by design or my lack of knowledge/extension setup so I would appreciate your thought on this.

Have you tried Gatsby? What are your favourite plugins?

Bonus — VS Code shortcuts:

text to lowercase => CTRL + K & CTRL + L text to uppercase => CTRL + K & CTRL + U It’s Miro’s fault! Newsletter about web front-end