A newbie’s first Gatsby 1.0 blog launch (and why I chose Netlify over Github Pages)

Photo: Kevin Rutherford

If you’re like me, you know barely any JavaScript at all, no React to speak of, and have never deployed anything to Netlify before.

You are a Rubyist or something else taking that deep breath, getting ready to hunker down and finally learn the jays for good.

You found out about Gatsby because you searched for “React” and “static site generator” and that’s what came up.

If you’re gonna learn JS anyway, what better playground than your own blog, right? Plus, React seems like a safe bet.

You may also have heard that the sites Gatsby generates are super (blazing!) fast.

And, like me, you might have based the final decision on the frivolous fact that the default blog starter has pretty typography.

That’s how I got here anyway.

Since I just finished putting up a blog, I figured it’d be good to share with you how you can do it yourself before this knowledge is obsolete.

So here goes.

Not using gatsby new

If you’ve read the docs or checked out other tutorials, you might be tempted to start with gatsby new yourblog https://github.com/gatsbyjs/gatsby-starter-blog.

Two reasons we’re not using gatsby new here:

1. We’re going to ride the 1.0 alpha bleeding edge, not stable master, and there is no way to specify we want the 1.0 branch from the starter repository URL. [No longer true.]
2. When using gatsby new, the command clones the starter repo and removes the .git directory from it. We want to keep that around so it’s easy to merge in new updates from the starter. (That was actually necessary while writing this tutorial.)

No need to upgrade the gatsby executable or install gatsby-dev-cli

Gatsby’s executable picks which Gatsby version to use from the current directory’s package.json. So just using the 1.0 branch from the starter repository is enough. You can upgrade to the latest executable by running yarn global add gatsby@next, but it’s not necessary.

I’ll save you the n00bdive of trying to make sense of gatsby-dev-cli as if it were the development version of the regular gatsby cli. It’s not! it’s a tool for developing on Gatsby itself, so for now, don’t go there.

Just install Gatsby as a regular citizen:

yarn global add gatsby

(I recommend following these instructions to avoid needing sudo for global installs.)

Up and running in development

Let’s get a first look at our soon-to-be-public website. (Replace yourblog with whatever name you choose for it.)

git clone https://github.com/gatsbyjs/gatsby-starter-blog.git \ yourblog
cd yourblog
git checkout -b 1.0 origin/1.0
yarn
gatsby develop

Go to http://0.0.0.0:8000 and you can see it running on your machine. Edit anything, save it, and you can see the change in your browser immediately. Sweet!

A new origin

We want to keep the original gatsby-starter-blog repository as a remote so that it’ll be easier to merge new updates into our blog.

But since we’re going to make changes (like writing posts) and push them to our own GitHub repository, it makes sense to call our repo origin and, the original, gatsbyjs.

git remote rename origin gatsbyjs

Let’s get our new origin set up.

We don’t want to commit .cache so:

echo ".cache" >> .git/info/exclude
git add .
git commit -m "First commmit."

Now start a new repository at https://github.com/new. Let’s assume you’ll call it yourblog.

Don’t check the “Initialize this repository with a README” checkbox.

Don’t add a .gitignore or a license. Click “Create Repository.”

Follow the “…or push an existing repository from the command line” instructions.

git remote add origin git@github.com:yourgithubusername/yourblog.git
git push --set-upstream origin master

Then push your 1.0 branch:

git push origin 1.0

Now if you type git branch -a you’ll see two remotes: origin, which points to your repository, and gatsbyjs, which points to the official blog starter repo.

Why fly Netlify (and not gh-pages)

Using GitHub Pages is so common you don’t even have to put up a disclaimer saying you have no affiliation. It’s a standard.

Netlify is new, so just to be clear: I have no affiliation with Netlify and I don’t get anything out of talking about them.

So why did I choose them over the standard? My main reasons were:

1. Free 1-click SSL for custom domains.
2. Automated build and deploy.

I was sold by #1 right out of the gate, but #2 grew on me as I saw it at work.

GitHub Pages has built-in support for Jekyll.

That means you can just push a change to one of your pages and it re-renders and deploys your site automatically.

You don’t need a local copy of your repository, you don’t need to run any commands, you can edit and create new posts all from GitHub’s web interface.

On your phone, even.

For Gatsby though, you’d need to generate the static site locally from a copy of your repository (plus all dependencies), then manually push it to gh-pages to see it live.

That’s limiting.

Netlify has built-in support for Gatsby, just like gh-pages has for Jekyll.

So you get the same flexibility and can work on your website from any device.

That also means non-developers can help out with content via tools like Prose.io or any git-based headless CMS.

Netlify has a (obviously biased, but useful nonetheless) detailed comparisonbetween themselves and GitHub Pages in case you want to check out specific features.

Let’s fly!

Time for takeoff 🛫

This is a one time thing you’ll need to do to set up your website on Netlify and hook it up to your GitHub repo.

After this, you don’t need to run any command to deploy. Just commit & push, and Netlify does the rest.

First we install their command-line interface:

yarn global add netlify-cli

Then kick off the process with:

netlify init

That will take you to the web browser to authorize the netlify cli. Authorize it, close the web page and go back to the terminal.

Here’s how you fill out the rest of it:

directory to deploy: public
your build command: gatsby build
looking good: Y
github username: yourgithubusername
github password: **********
No site id specified, create new site? Y

It says “success” and gives you a link. But… it’s still 404.

Don’t panic! Just wait about a minute, come back, and it will be working.

(One minute later…)

Done! :D

Now you don’t want to keep the ugly auto-generated URL, so update the name like this:

netlify update -n yourblog

And voilá, your new blog is live at https://yourblog.netlify.com !!!

👏👏👏👏👏👏

(Not literally, of course, you have to replace yourblog with the unique name you came up with.)

Say my name

You want to keep your site under subdomain.netlify.com? We’re done. (That could even buy you some street cred, who knows.)

If though you’re the vain kind and don’t want no one’s name on your URL but your own, I’ve got you!

Just a few more knobs to turn.

I know naked domains are all the coolness these days. (Naked like https://example.com, without the www.)

But unless you have a DNS provider that supports ALIAS records (most don’t), you don’t want to do that.

Why? Because you’d lose that magic CDN speed, which is one of the main reasons to use static websites in the first place.

By setting an A record pointing at one specific IP address, you make sure your requests are served only from that one server, not from the nearest CDN host.

The alternative is to have a www CNAME and redirect the naked URL to it.

First set up a CNAME record pointing www to yourblog.netlify.com.

Then run:

netlify update -d www.yourdomain.com

It will say “Site updated:” and give you the URL.

Great. Something’s off though… 🤔

1. The URL it returns says http://, not https:// (I thought that came for free!).
2. You see nothing if you visit that URL.

No worries!

For the latter you just have to wait until the new DNS record propagates.

This could take hours. So let’s take care of the former while we wait.

Go to the Netlify admin ui and click “Enable HTTPS” for your new site.

Check the “force TLS connections” checkbox so traffic to HTTP will be redirected to HTTPS.

Aaaand done! Now it’s just a matter of time until you can visit your https://www.yourdomain.com URL and see your site in all its glory 🙌

One more thing

You might have noticed that if you go to https://yourblog.netlify.com, it still works.

So you have two URLs serving the same content.

I’m no SEO expert and I have no idea if you can be penalized for that or not.

But it bothered me to have these two apparent sources of truth.

So here’s how you tell Netlify to redirect the .netlify.com URL to your custom domain:

echo "https://yourblog.netlify.com/* https://www.yourdomain.com/:splat 301!" >> public/_redirects
git add -f public/_redirects

The -f makes sure git adds the file despite /public being in .gitignore. Other files are going to keep being ignored as usual.

Now commit and push, wait a minute for the deploy, and all set! 😅

If you run into any trouble getting your blog up, let me know. I’ll try my best to help.

AB🚢

Written by Helder S Ribeiro, a developer, teacher, and entrepreneur from Brazil. You should follow him on Twitter.