How to build a JAMstack blog with Gatsby.JS, Lumen and Netlify

Zero to production in just a few hours.

Sean Dearnaley

Published in

The Startup

14 min readJan 7, 2020

Introduction

In this article I’m going to show you how to create a personal blog site with Gatsby.JS , we’re going to bootstrap it with the wonderful Lumen Gatsby starter kit, and finally we’ll host it with Netlify… in the process we’ll hopefully learn more about Gatsby, why it is special, how JAMStack applications differ from other application architectures and get some experience with the Netlify platform.

Who is this article for?

This article is written for developers of all levels, if you’re a beginner this is a great way to learn how to build a basic site that provides everything you need to get going, you’ll utilize a powerful framework that is highly extensible and approachable. You can continue to build as you learn, nothing will go to waste. This is a good way to start learning about web development.

If you’re an intermediate or advanced developer you’ll learn how easy it is to get a Gatsby site up and running, you’ll also learn more about the philosophy of the JAMStack architecture. I’ll talk about what Gatsby.JS is, and detail some of the idiosyncrasies/gotchas you may experience.

If you have a background in React.JS, Gatsby will be familiar. Getting content into a Gatsby site is as simple as writing markdown, but the framework is remarkably powerful, there is a huge ecosystem to work with and it’s not limited to small projects.

I’m developing on a Windows platform with a preview version of Microsoft WSL 2, I did experience some snags getting it up and running, so I’ll include some bonus notes for Windows users… once you get it up and running, it works great. If you’re using a Mac or a Linux distro you probably won’t experience these issues / you can skip those sections.

The Gatsby community is very helpful, they are responsive to issues, have a discord and a strong presence on Stack Overflow.

I started this project with no experience of Gatsby, and it’s also my first time using Netlify, my goal was to build a site and write this article in <1 day. I was pleasantly surprised by the experience, I got it done — albeit with a few annoying Windows related bumps in the road. I’m glad to be able to share the fixes for those issues.

Why start a personal blog in 2020?

I wanted to learn Gatsby and more about static site generators but this year I actually needed a good site to showcase my work…

I’ve been working on web applications for over 20 years, I had a music blog in the 90’s, but this is the first time I’ve made a professional blog focused on my own work.

It’s never been more important to establish your online work presence; we have so much work that is already online, it’s good to share your experience with others and a personal blog is a great way to keep your connections up to date. It shows what you’ve been doing and what you have done.

You may be asking, why not use an existing service like Wix, or SquareSpace or Wordpress? These are all great services and I highly recommend using them if you don’t need control over the internals. Use a managed service if you don’t want to learn about development.

I’m a developer, so I want to be able to control what I create, I want to be able to extend it as I see fit. Specifically, I intend to add features related to sharing music, another passion of mine but these future features will require some advanced customization.

I need something that is scalable but also easy to maintain. I must be able to update it quickly; I need it to be found on search engines and preferably I’d like to avoid the overhead of expensive servers. The JAMStack architecture is a good candidate for this kind of application.

What is JAMStack?

JAM stands for Javascript, API and Markup. To be honest, when I first heard the term “JAMStack” in 2016, I rolled my eyes… yet another stack I thought. The tech industry has a knack for repackaging old concepts and marketing them to push the interests of certain individuals and companies.

… so, initially I was skeptical, I didn’t really understand it at first… I thought aren’t these just static sites? Now I understand what the difference is and why it is important. To understand JAM, it’s helpful to talk about the history of stacks, this is slightly beyond the scope of this article but I will try to give a basic primer:

In the early days there were just static sites made of HTML, later, servers got the ability to execute code written in languages like Perl, these were known as Common Gateway Interface (CGI) applications. These server apps would lead the way to the “LAMP” stack which stood for Linux, Apache, MySQL and PHP.

This combination of server software proved to be very powerful and incredibly popular, it led to a new generation of server-side applications, static HTML was generated and served from the server side. Note: there was also WAMP and MAMP stacks, used on Windows and Macintosh respectively.

Later the fashion would become MEAN stacks (MongoDB, Express.js, AngularJS, and Node.js) and their equivalents. AJAX introduced sites that were dynamic in nature, more logic moved to the client, mostly using JavaScript to connect to application programming interfaces (API’s). The client was decoupled from the server, but you still had servers to contend with.

The JAM stack arrives with the advent of the cloud and serverless applications.

…what makes JAM special is that it doesn’t need servers… or more specifically it relies on a serverless architecture…. we can get in to the semantics of ‘serverless’ because technically servers are involved… but the difference is that the server part is no longer your responsibility, you don’t have to setup up servers to scale, and your API’s can make use of managed services, for example, you can use AWS AppSync to have an API that uses Lambda’s for server logic, and delegates things like database work to services like Dynamo. There are comparable features like Microsoft Azure or Netlify functions.

JAMStack sites live entirely in Git, they’re easy to clone and when hosted on a site like Netlify can be served up directly from a CDN. Apps that live close to ‘the edge’ tend to offer a better user experience, they scale easily so you don’t have to worry about provisioning.

To cut a long story short, it’s early days but JAM promises better performance, higher security, cheaper/easier scaling, and a better developer experience.

What is Gatsby.JS?

Gatsby.JS was released July 2017. It is a static site generator, more specifically it generates progressive web applications (PWA’s). It is based on React.JS which is the most popular reactive framework (3.5 million users), it also heavily utilizes GraphQL to build an internal data layer.

You don’t need to know React or GraphQL to use Gatsby. You can use Gatsby to generate websites from Markdown, JSON files or other content API’s. Gatsby’s internal engine scan’s your content and builds a local data layer with GraphQL, when you hit build, it creates static content that is highly performant, and can be easily hosted, and indexed by search engines. Plugins are used to generate sitemaps for search engines like Google.

Something really special about Gatsby is its eco-system of plugins, themes and starter kits. It’s got a huge number of easily approachable extensions.

In this tutorial, we’ll be generating our site from simple markdown files that can be edited directly in a text editor or with a WYSIWYG interface provided by Netlify CMS.

What is Markdown?

Markdown is a lightweight markup language with plain text formatting syntax. Markdown has a philosophy that text documents should be readable, specifically making writing for the web easier as it converts to HTML easily.

Markdown is relatively easy to write, and is used by a lot of applications, notably Medium, Stack Overflow, Skype, Slack and Wikipedia. You can read about Markdown syntax here.

What is Lumen Starter Kit and why should I use it?

One of the coolest things about Gatsby is that it has a huge eco-system. Lumen is one the most popular blog starter kits, a ‘starter kit’ gives you a predefined set of things you need to get going… you can use it to bootstrap your development efforts… often, Gatsby starter kits give you everything you need with minimal modification necessary… usually you are working with just a config file and markdown files.

Lumen provides the following features out of the box:

Lost Grid — Lost Grid is a powerful grid system built in PostCSS that works with any preprocessor and even vanilla CSS.
Modern font stack.
Beautiful typography inspired by matejlatin/Gutenberg.
Syntax highlighting in code blocks using PrismJS.
Mobile-First approach in development.
Archive organized by tags and categories.
Pagination support.
Netlify CMS support.
Google Analytics.
Disqus Comments.
Flow static type checking.

What is Netlify?

Netlify is an all-in-one platform for automating modern web projects. They provide a variety of services including hosting and server-less functions. Our project uses Netlify for hosting and DNS, we’re also using Netlify CMS to edit markdown content but you don’t actually need to use that. You can just edit the markdown directly and push to your branch.

Netlify provides a really easy build service that can pull directly from your Git repo and trigger a build + deployment to Netlify hosting services. It’s also a simple process to publish your site and get it live with a proper custom domain.

Netlify provides packages for starters, pros and businesses. We’re going to be using the starter tier which will cost us nothing… with the free tier you still get Git integration, continuous deployment and custom domains.

Netlify CMS

Netlify CMS is an open source, single page app written in React that lets you edit content and data files in your Git repository. Storing raw content right in the static site repository is an ideal approach, allowing both code and content to be versioned together, but that requires non-technical editors to interact with a service like GitHub. Netlify CMS was created specifically to bridge this gap, providing a solid interface that works well for technical and non-technical users alike, and interacts with your static site repository via API so that every change results in a commit.
A primary focus of Netlify CMS is to work well with modern site generators like Gatsby. Installation typically requires just an index.html file and a YAML configuration file, but you’re going to leverage the Gatsby plugin for Netlify CMS to automatically install and build the CMS along with a static site.

Prerequisites

OK, so what do we need to get started!

I recommend using Ubuntu LTS, but technically these instructions should work for Windows with WSL, most Linux distros or Mac. I’m going to be installing with Windows Subsystem for Linux version 2.

Gatsby recommends you install Node LTS which at the time of writing is version 12. I’ve included some install instructions below. There are various ways to install Node, you can find official instructions here.

You’ll need NPM and Yarn, installation instructions are provided. You can find the official Yarn installation instructions here.

You’ll need a Github account and Git.

(optional) You may want to buy a custom domain, I recommend GoDaddy for cheap domains. You can however just use the provided free starter Netlify URL.

Windows Gotchas

There is an issue with Gatsby and Windows paths, if you’re using WSL, Windows can attempt to coerce path names because Windows is case insensitive, if you follow the instructions you will be OK but in general you have to type in the correct case for Linux. You can read about this issue on the official Gatsby issue page.

Avoid using the /mnt/ drives if you’re using WSL 2, now Linux disks are Virtual Hard Disks, and anything outside the Linux system has poor performance, not only that but hot module reloading (HMR) will not work. You need to create the repo in the Linux system, I have included that in the install notes.

You can read about my experience with WSL 2 here.

Install Notes

I’m going to be installing with Ubuntu LTS 18.04 on WSL 2.

My Ubuntu installation is clean, so I don’t even have node on there. Before installing the latest version of Node.js, you must add its PPA… run the commands below to install required dependencies….

Lets install Node 12. You can’t just do `apt-get nodejs` because the packages need to be updated:

sudo apt update

Note: apt-get update doesn't actually install new versions of software. Instead, it updates the package lists for upgrades for packages that need upgrading, as well as new packages that have just come to the repositories.

Next enter this command (you can enter ‘Y’ when prompted and choose <Yes> to restart services without asking):

sudo apt install build-essential apt-transport-https lsb-release ca-certificates curl

Now we can curl Node 12 with the following commands:

sudo apt-get install curl
curl -sL https://deb.nodesource.com/setup_12.x | sudo -E bash -

Finally we can enter the install nodejs command:

sudo apt-get install -y nodejs

Now check the node + npm versions, make sure they are correct:

node -v
npm -v

2. Install Yarn in a similar fashion, we will take the precaution of uninstalling the old version in case it is present because it has a different behavior, enter the following commands:

curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list

Lets remove cmdtest to make sure we have the right version of yarn installed:

sudo apt remove cmdtest

Then finally:

sudo apt update && sudo apt install yarn

3. Configure Git if you haven’t already with the following commands:

git config --global user.email "you@example.com" 
git config --global user.name "Your Name"

4. Next we will install the Gatsby CLI globally:

npm install -g gatsby-cli

5. Next we need to switch our home directory where we’ll pull in the starter repo, note if you’re using Windows WSL this is especially important, as hosting on the /mnt/ folders is problematic (see Windows gotchas, Windows mounts are outside of the Linux file-system and Gatsby CLI will not pick up file changes for hot module reloading), replace your_linux_username with your linux username:

cd /home/your_linux_username

6. Now we can start Gatsby with the Lumen starter kit with the following commands (note: it’s a good idea to do Yarn upgrade as written before develop, otherwise it will ask you to do it next):

gatsby new myblog https://github.com/alxshelepenok/gatsby-starter-lumencd myblogyarn upgradegatsby develop

Your site is now running at http://localhost:8000

You’ll also see a second link: http://localhost:8000/___graphql. This is a tool you can use to experiment with querying your data. Learn more about using this tool in the Gatsby tutorial.

Open the blog directory in your code editor of choice and edit src/templates/index-template.js. Save your changes and the browser should update in real time.

7. Next we will publish our Git repo, we’ll need this for Netlify, I’m using Github for Windows, but you can use the equivalent commands (replace your_username and myproject :

git remote add origin  https://github.com/your_username/myproject.gitgit push origin master

Note: here I’m using WSL 2, and it’s actually in a network drive in Windows 10. Using the Windows file system will result in bugs and performance degradation.

8. Next step we’re going to sign up with Netlify and then login:

9. Next step is to add a site from Git, a window will pop up to authorize, click the ‘New site from Git’ button:

Note you may have to click the ‘Configure the Netlify app on GitHub’ link if you don’t see your repository.

Next we click ‘Deploy site’:

If all goes well your site will be deployed and from here you can setup a custom domain and HTTPS (follow onscreen instructions):

Note: you can now click the site link in the top panel, your site should be live!:

10. OK, so how do you go about updating the site?… there is a config.js file in the root of the app with various options for contact links, bio, title etc. the other important folder is content/pages , here you will find the various markdown files that have been used to generate the site, if ‘gatsby develop’ is running, you simply have to update the markdown and the local app should reload automatically, then it’s simply a matter of pushing your changes to git.

Note: updating config.js does not auto reload like the markdown files.

location of content + config.js in VS Code

11. You can use Netlify CMS to update the site in production using a user friendly WYSIWYG editor, but you will first need to enable Netlify Identity and Git Gateway in Netlify Identity settings:

Now, you should be able to access the /admin folder on your site and click ‘Login with Netlify Identity’

Pick the content you want to edit or Add New Pages

You can publish changes directly from the app, and Netlify will start deploying the newly generated build.

et voilà ! -your very own JAMstack personal blog, hosted on Netlify.

Next Steps

If you’re using VS code you’ll want to install the Flow typing's extension:

If you’ve got a custom domain, you’ll want to register your site with Google , this involves adding a TXT record to your DNS server to verify the identity of the site.

The config.js has a field for AnalyticsID, it’s a good idea to register for Google Analytics and get your own ID so that you can track your usage and who is linking your site.

The Gatsby/Lumen starter kit also generates a sitemap automatically, you can register your site via the Google Search Console.

Conclusion

I hope you enjoyed this article. There is loads to explore with Gatsby, I think it’s a great project, make sure you check out the plugin library. JAMStack’s are very exciting. This is just the beginning.

… as I mentioned I built my own personal blog just today ;) you can read it here. I’ve made all the source code available on Github. Many thanks to the Gatsby team, and the folks over at Lumen & Netlify.

Good luck with your project!