How to Create a Gatsby Starter

What is a Starter?

A major feature of the Gatsby.js framework is the option to start a project with a starter, which is some boilerplate code to get you going fast on whatever you need to work on. You can read about the basics of starters here, and view the library of starters here. In this post, I'll discuss why I authored a starter, what went into it, and how to submit a starter to the Gatsby starter community library.

Why I Made A Starter and What It Includes

As I've experimented with Gatsby more and more, I've found myself getting annoyed at the amount of code that I needed to delete from the gatsby-default-starter, and it eventually dawned on me that it would be a good lesson for me to author a theme that fits my needs a bit more closely while saving me the trouble of creating a Gatsby site from scratch. What I wound up with was the Gatsby-Minimalist-Starter.

What I liked and kept from the gatsby-default-starter was:

• The base plugins of gatsby-image, gatsby-source-filesystem, gatsby-plugin-sharp, gatsby-transformer-sharp, gatsby-plugin-manifest, and gatsby-plugin-react-helmet. These plugins are either essential or extremely useful to my usual web development flow on Gatsby.

• Starting boilerplate for an <Image /> StaticQuery and the seo.js component.

What I added or changed:

• I use Emotion.js for styling, so I added that library and the gatsby-plugin-emotion plugin.

• The major sticking point I've had with the default starter as of late was how verbose the layout.css file was, and how I found myself constantly needing to overwrite styles, so I reduced the styles to a mere:
  

html,
body {
  box-sizing: border-box;
  margin: 0;
  padding: 0;
}

body {
  overflow-x: hidden;
}

• I am always trying to improve my design chops and to be able to build good-looking sites faster, so I added comments in the layout.css file to guide me to make initial design system decisions:

/*

Step 1: Define initial sizing scale, for example:
  4px, 8px, 12px, 16px, 24px, 32px, 48px, 64px, 96px, 128px, 192px, 256px, 384px, 512px, 640px, 768px

Step 2: Define initial font scale, for example:
  12px, 14px, 16px, 18px, 20px, 24px, 30px, 36px, 48px, 60px, 72px

Step 3: Define initial color scales, one for color, one for black and white.

Step 4: Select typefaces. Favor sans-serif for UI components, and try to select typefaces with a
 minimum of 5 weights. That said, you generally really only need heavy (600, 700) and normal (400, 500) weights in your UI.

*/

-Other than that, I removed all other starting styles, pages, and templates to that I had as close to a blank starting slate as I could stand.

I will almost certainly update and improve the base CSS in future iterations of this starter, but that's about all there is to it. This step can best be described as "get your starter in the shape you want".

One last thing: It's not explicitly mentioned in the Gatsby docs pertaining to starter libraries, but make sure that the README.md file in your repo has instructions on how to download and use your starter, typically something like git clone <MY-REPO>, cd <MY-REPO>, npm install && npm start.
Now we're ready to submit!

Contributing to Gatsby

The Gatsby docs are excellent, so this process is very clear.

• First, you'll want to follow the steps outlined here to get your local dev environment set up and a fork of Gatsby ready.

• Next, take note of the section on opening a pull request, taking special note of the heading "Documentation PRs", as this has a useful directive on titling your git branch for this type of PR.

• Now, follow the instructions on this page relevant to submitting a starter. This is all fairly straightforward, but I will mention that I needed to make some tweaks due to casing in the tags not quite being 100% correct, so save yourself some effort and cross-check those with other starters to ensure they won't need to be changed during code review of the PR.

-Once you're done with that, follow the instructions on the previously linked page on Gatsby PRs, and you're good to go!

I hope you got something out of this guide, and I'd love to hear your thoughts. Have you created a Gatsby starter? I'd love to see it!