Getting Started With Gatsby

My goal isn’t to give you a thorough tutorial on how to use Gatsby: There are, in fact, tons of great resources on the internet. You can check the official documentation, for instance.

But here are some steps to a quick start:

Prepare your environment

Install Node and npm. If you’re using a Mac, for instance, you can launch this command assuming you have Homebrew.

brew install node

If you’re using Windows or a Linux distribution, you can check the documentation. It’s pretty straightforward.

Install Git

Install the Gatbsy CLI by launching this command

npm install -g gatsby-cli

The following part is borrowed from the documentation:

Now you are ready to use the Gatsby CLI tool to create your first Gatsby site. Using the tool, you can download “starters” (partially built sites with some default configuration) to help you get moving faster on creating a certain type of site. The “Hello World” starter you’ll be using here is a starter with the bare essentials needed for a Gatsby site. Open up your terminal. Run gatsby new hello-world https://github.com/gatsbyjs/gatsby-starter-hello-world. (Note: Depending on your download speed, the amount of time this takes will vary. For brevity’s sake, the gif below was paused during part of the install). Run cd hello-world . Run gatsby develop .

That’s pretty much it. Now you have a static website running locally. Try to modify its content, and you’ll see (after saving) your modifications being updated in real time.

Use a preexisting template

If you’re not a front-end ninja like me, you can look up a template you like on the Showcase tab of the official website.

There are tons of open-source websites and portfolios built using Gatsby.

Examples of websites and portfolios built using Gatsby

Gatsby plugins

Now the most interesting part of the Gatsby framework: the Gatsby Plugin Library.

If you want to extend the capabilities of your website by adding, for example, image responsiveness, SEO, Google Analytics, offline support, a sitemap, a robot.txt, and more, here is where you can find everything you need.

The community is vibrant and the plugins are well supported. You can search for them in the search bar.

Gatsby plugins

If you want to have great SEO for your blog or your portfolio, I found this repo that enumerates a list of useful Gatsby plugins.

Deploy

Once you’re happy with your website, you can generate static files ready for deployment by running the build command at the root of your project.

gatsby build

This command creates a static version of your website that’s ready to go live on the internet and resides in the public folder. You can either copy it to your server, push it to GitHub Pages, or use deployment service (such as Netlify). I personally chose Netlify because I found it easily automated my workflows.

Netlify homepage

The documentation is great, and you can find many blog posts that walk you through the process of deploying a Gatsby site on Netlify. Here’s a great one from gatsbyjs.org and another one from netlify.com.

A few questions you might have

So what happens to your old posts?

My blog has been live since 2016, so I definitely won’t throw away my old posts. Fortunately rewriting them as Markdown files in Gatsby was easy, so I did it. It was even an opportunity to better reorganize the structure of the folders.

The URL structure of the new blog is different. What happens if a user clicks on an old link?

I used gatsby-plugin-netlify to create permanent URL redirections (with 301 HTTP code) by specifying a mapping between old and new URLs. When the build command is executed, this plugin generates a _redirects text file at the root of the public folder that writes this mapping and tells Netlify to execute these redirections properly. I found this solution very convenient.

Here’s an example of a _redirects file:

A mapping between old and new URLs

What happens to your old Disqus comments? Will they be lost?

Hopefully not. Disqus provides a migration service called URL Mapper that requires manually entering a CSV mapping between old and new URLs.

Here’s a tutorial that walks you through the process.

What about Google Analytics? Do you create a new account or keep the old one?

I searched for an answer to this issue, and I found a Stack Overflow thread talking about it.

The recommended solution is to do … nothing. You just have to reuse your old GA account on your new website.

What about your AddThis account? Do you lose your previous stats on social shares?

Sadly, yes. AddThis processes each URL differently, and there’s no way for it to tell the new URL should be treated as the old one.