Developer's Gym - Gatsby Workshop

Hands-on workshop on Gatsby.

Recap of the workshop

Hello my fellow junior developers!!

Last Saturday, this happened:

oembed: https://twitter.com/JuniorDevSG/status/1121997068678000641

If you missed it, too bad 🙉 And so we're here again to make it less bad. Here's a bit of wrap up of what we did in the workshop.

In this recap, we'll share more about the imperative knowledge as well as pulling a bunch of resources together so you can refer back to where you'd like to go for your next step.

What is Gatsby

Gatsby is a static site generator based on React and GraphQL. Both libraries bring their elements (?) into Gatsby that comprise of Gatsby's unique strengths:

It is blazing fast. It follows the PRPL Pattern, automatically optimizes your sites, and it embraces the next billion users.

Its simplicity sparks joy.

And it offers full range of customizability.

We then browsed through the starters library as well as the plugins. Before you jump right in to getting your site up and running, you may check out the following articles that we mentioned during the workshop:

By the way, if you missed the workshop but would like to have the chance to learn to build Gatsby sites, I recommend that you follow the tutorial from Gatsby's official doc. It'll probably take you a good half day. This set-by-step tutorial is truly a gem that you should not miss. The quality and the completeness of the materials are unmatched.

Up and running

To use Gatsby, you'd need at least git and Node (>8) installed on your system. Then, you'll need Gatsby CLI installed globally.

The Gatsby CLI provides a set of command line interface that will help you create your site. Check out their docs for more details. For our workshop, we'd use the following extensively:

  • gatsby new creates your repo from a starter
  • gatsby develop started a hot reload dev server that you'll use

So we've installed Gatsby CLI, and we created our first site with gatsby new. There is no magic here, it simply clones your repo, copies the necessary files, and initializes the first git commit.

I now have a personal tip — when even your favorite starter still got here and there that don't fit your need, fork it, and make changes to it to make it your own.

We then went ahead try to understand a bit more about what's going on within a Gatsby site. Read gatsby-config.js and gatsby-node.js, they specify site configuration and site generation, repsectively.

Inside gatsby-config.js, you'll likely write a bunch of meta data as well as plugins and their options.

In gatsby-node.js, you'd write the Node APIs that control your site generation. Note that you don't have to know how to write everything from scratch for now. Most starters already write those for you. But it's helpful if you understand what they're doing. Plus the existing starters are a good place to learn the good practices of those tasks.

Here is the list of docs we mentioned in this section:

And a couple of starters you may want to look at:

Layouts

The front end website of your Gatsby project is simply going to be a React app. This means the layouts, the reusable UI parts, the interface, they all gonna be React components.

They will live in the src/ directory of your project. A typical file structure of your may look like this:

$ tree src -L 2
src
├── components
│   ├── About
│   ├── Disqus
│   ├── Footer
│   ├── PostListing
│   ├── PostTags
│   ├── SEO
│   ├── SocialLinks
│   ├── UserInfo
│   └── UserLinks
├── favicon.png -> ../static/logos/logo-48.png
├── layout
│   ├── index.css
│   └── index.jsx
├── pages
│   ├── about.jsx
│   └── index.jsx
└── templates
    ├── b16-tomorrow-dark.css
    ├── category.jsx
    ├── post.css
    ├── post.jsx
    └── tag.jsx

Everything under src/ages/ will become a page. Try creating one on your own. If you're unlucky and named your page to something like test.jsx, it won't work because Gatsby filters out a few reserved words and test happens to be one of them. You'd only know if you read the docs by yourself.

The next thing we did was to play around with our layout, adding a header and an intro to layout, etc. Even if you are not familiar with React, you'd find yourself writing React components anyway. Maybe it's a good excuse to pick it up yo?

Some further materials you may be interested in:

Queries, GraphQL, and I should even load my assets with it?!

Our next segments were about GraphQL. This part was led by my co-instructor Nut. I am absolutely in love with him now. He's so amazingly knowledgeable about GraphQL, picks up Gatsby like he's owning it already. Plus he answers all my questions in his unique Thai style softness that just gets me like 🤩 Anyway, that is why this segment will take on a different tone — one more of a student than of a speaker.

Turns out, while GraphQL was born as a query language run on a server, Gatsby's adaptation of it at build time should create a eureka moment for its brilliance. With GraphQL, all my static assets are now infused into a JSON object, split by routes, pre-cached, and easily consumed by my React components.

Furthermore, we get GraphQL's features for free. Predictability, for instance, we'd get a guaranteed shape for most of the data objects in our components now. It's eye-opening to see a hairy problem in one system becomes a non-problem in another.

You may want to check out this article Why Gatsby Uses GraphQL for more understanding about Gatsby's choice of GraphQL.

So Nut led us through a brief intro to GraphQL's features. Then he showed us how to play around GrahiQL, a graphical interactive in-browser GraphQL IDE, to help our development process — simply copy over the query in the component and see its return! Then, we dived into our code to learn to customize GraphQL schema / queries for our own features.

Another topic we covered was how, together with Gatsby Image, Gatsby Transformer Sharp, and querying with GraphQL, we can have fast, optimized, and responsive images in our site. Below is a gif that showcases a stable user interface where images are lazily loaded, hold their spaces, and display a lower resolution version when the network is not that reliable. You may as well want to read this article Image Processing with gatsby-transformer-sharp to learn more.

That was a contentful hour. Here's a list for you to dive in more:

Some more resources on learning GraphQL:

Styling

Am I exaggerating by saying us front end developers are overly concerned about styling? For this workshop, we chose a starter that particularly avoids the battle of styling — there is (nearly) no styling to the site at all.

For our workshop today, we styled our site using SASS + CSS Modules. The setup once again involves installing packages and adding them to plugins inside gatsby-config.js. And you shall see a pattern here. I mean, this kind of consistency also makes it feel a lot easier to work with than having to go all over the places for configurations.

Once our styling is in place, we went ahead to style our components using CSS Modules, and see our class names scoped. If you are not familiar with CSS Modules yet, you're not alone! Most of us weren't entering that workshop neither. Time to try something new 👋

Then, we also talked about how when we may not want to write too much styling at all other than just making sure our site is reader-friendly, we have the choice of using TypographyJS with an existing typography theme. After all, typography is an integral part to most of the text-centered sites.

We were running over time so quite a few of the styling topics were left off. Maybe here is a chance to make up a bit for that:

Using a style guide

When we add styling to our sites, it is often helpful to build a style guide first. This would be a page that tries to contain all sample cases of your content. For instance, a nice style guide to my blog would be one markdown post that contains all headings, code blocks, lists, block quotes, etc etc. Once you have a style guide, you can simply refer to that as you add styling. This saves a lot of time having to go back to styling once you hit an edge case.

Our beloved CSS master Huijing has a nice style guide on her website. If your site is mainly markdown posts, you may check out this gist for style guide as well. Here is the style guide in action in the sample site I have been building for this workshop.

Dark mode

Dark mode is hot. Nearly all apps have a dark mode now. Overreacted also has dark mode. There are ways to do this and since I now have the luxury of making references, check out here or here. These are the serious ways. What about my personal way of doing it? Maybe you can look here 🙈.

Now for a list of references for this segment.

Reaching

Your site would not be complete until it reaches your audience.

If you are keen on the SEO side of things, you may want to start with this article Putting SEO First with Gatsby. Meanwhile, adding Google Analytics to your site is only one plugin plus one trackingId away.

And now we finally come to deployment. My hand and mind are not working anymore but since my demo must have left an impression, I'm just gonna throw in Netlify here and say that thanks to that great product, my first Gatsby site took a mere matter of minutes from start to deploy.

Community

Now we're nearly closing our first ever intro to Gatsby workshop. What's next? Build your own site of course! But I'd like to share with you in order of accessibility of where you can reach out to find a community around Gatsby.

Local

There is already a nice vibe in our local community around Gatsby.

Thomas Chia gave a talk in Gatsby Gatsby: Back to the Future! in Mar 2019 issue of ReactJS Singapore.

In the same event, Thorsten Schaeff ran a JAMStack session Hands-on: building an e-commerce site with Gatsby, Netlify, and Stripe on using Stripe with React Hooks.

And can you believe it, in the same week, Max Ong Zong Bao gave a talk on JAMStack Building a developer blog through JAM stack at a JuniorDev meet up.

Furthermore, if you miss our workshop, there will be another one by swyx at JSConf Asia this year. And even if you were at this past workshop, you should still go to learn more!

I really really love this vibrant community and I'm sure so do you. Thomas Chia suggested that we should start a community around JAMStack. I mean, why not??? And if that's an idea you like as well, please hop on and let's do it :]

... and beyond

Beyond the scope of our tropical home, the online community around Gatsby is also incredibly supportive.

The official docs are well written and maintained. Their official tutorial is one you should spend a good afternoon with.

If you've got interesting things to share with @gatsby they'd likely respond to you on twitter.

Gatsby also offers an interesting interactive activities with us, pair programming, where you have the chance to work on a topic of your choice with an expert Gatsby developer. You may want to check out this article for someone's pair programming experience with Gatsby.

Once you feel Gatsby is your think, you should contribute to it. Why? Because they give out free swags for contributors. Not just that. Since it's such a lovely community, aren't you excited to join them?

There are a number of more resources you can find in the list below:

Finally finally got to wrap up. It has been a great journey to work on the content for this workshop as well. I really hope you've learned something new. And next time, I hope I'll be hearing from you on things you find inspiring. Please share with us!