« Scott Nonnenberg

Static site generation with Gatsby.js

2016 Apr 19

[This is an adaptation of a talk I gave at the Seattle React.js meetup in March 2016. Direct link to screencast. Looking for detailed tips on using Gatsby? I’ve got a post for that! Also, you can get into the deep details now that this blog is open source!]

I’ve been on the web for a long time. I was hand-editing HTML with Notepad all the way back in 1997, uploading to jps.net or Geocities via FTP with my parents’ 14.4 kbit/s modem. So I have a lot of experience running websites from static files.

Gatsby is the first site generation tool I’ve used which feels right to me. It balances its production static file experience with a dynamic, full-fidelity authoring experience.

What is Gatsby?

It’s a node module which weaves together React.js, React-Router, webpack, and webpack-static-site-generator. You get a nice development experience with hot-reload for page contents, styles and page structure, and you’re working with the same markup as what is generated to disk for production builds. It’s as simple as running gatsby develop or gatsby build on the command-line.

It’s particularly interesting for me because these are all the same tools I use to build web applications. Gatsby configures everything for you, resulting in the same benefits with a lot less work setting up a new project.

Big thanks to Kyle Mathews for starting and continuing to maintain the project. He initially released it back in March 2015, and the most recent version is 0.9.1, released April 9 2016. I’ve submitted five pull requests thus far, and I think I’ll continue! :0)

Why static files?

Gatsby’s production build gives you a collection of static files. It’s quite a bit different from tumblr, ghost or wordpress, all generated on-demand from a database.

With static files you can easily serve them with minimal configuration, using your favorite CDN, github pages, or your own server with nginx. You don’t need to worry about updating your published site due to a newly-discovered vulnerability in one of your dependencies. Or maintaining a database. They won’t hog memory or CPU. They’ll continue doing their job through years of operating system and server updates.

Now, you may be thinking “that approach is fine for blogs and other toy sites, but not my site!” It’s true. Blogs, documentation sites, and company or product marketing sites are all ideal cases for static sites. They are modified/deployed only by privileged users, and changed relatively infrequently. But let’s get creative! What about a shopping site?

Let’s really think about it. How often does the list of products change? Stock changes quickly, yes, but the overall set of products? What if you generated your entire site every night, and anything dynamic was via targeted javascript talking to a separate API? You could cache those static files aggressively. Just make sure your users haven’t disabled javascript!

Why single-page web app?

A surprising aspect of Gatsby is that it isn’t just an authoring and basic static file build tool. It also assembles a full javascript Single-Page App (SPA) for your site. Once it’s loaded in a user’s browser, no further page requests are made!

If you’re not familiar with SPAs, they use browser history APIs to make it seem like you are navigating between different pages on a site. But you aren’t. Not really. The loaded app has all it needs to generate each user-requested page on-demand, using cached or newly-requested data from the server. With Gatsby, all posts are loaded up front - as you navigate through the site, the only subsequent requests are for page assets like images.

Why would you want this? Well, perhaps you’re in a coffee shop and you want to download as much as possible while your connection is still new and fresh. Or you’re on a wireless connection where high latency makes each round trip with the server take a while - get the entire site at once, and subsequent navigations will be quick.

But SPAs are not always a good idea. Let’s do some quick math for my blog:

  • Plain HTML files:
    • Initial download: 8-14kb, gzipped
    • Subsequent pages: 8-14kb, gzipped
  • Single-Page App:
    • Initial download: ~230kb, gzipped (218kb bundle.js + 8-14kb for html page)
    • Subsequent pages: none

And what’s the average number of pageviews per session on my blog? Two. That means, the average user will download 200kb more than they need. Not to mention all the effort spent decompressing, parsing and running all that code!

And it will only get worse as I add more posts to my site. So I turned off the SPA. What you’re looking at right now is a flat HTML file generated from markdown and React components at build time.

Getting started

Starting off with Gatsby is a snap, since it has a couple starter kits ready for you. To jump in with the blog starter kit:

git clone https://github.com/gatsbyjs/gatsby-starter-blog
cd gatsby-starter-blog
npm install
npm run dev

Open your browser to localhost:8000 and you’re off and running. Update files and watch the hot reload magic happen before your eyes!

Happy Gatsby-ing!

I really like React because of its flexibility - I can pre-render to static files, I can render on-demand on the server, or I can render on-demand on the client. And Gatsby makes it very easy to unlock that potential.

Thinking about jumping in? Take a look at my Practical Gatsby.js post, a bunch of tips to get you to production-ready!

A little bit more:

Kyle Mathews recently gave a talk on Gatsby: http://www.staticwebtech.com/presentations/developing-with-react-gatsbyjs/

I won't share your email with anyone. See previous emails.

It's me!
Hi, I'm Scott. I've written both server and client code in many languages for many employers and clients. I've also got a bit of an unusual perspective, since I've spent time in roles outside the pure 'software developer.'


Practical Gatsby.js 2016 Apr 21

So you want to use React.js to build your site, and you want to deploy just static files? Gatsby.js is a great choice! But it’s dangerous to go alone - take these hard-won tips! Read more »


Feeling the Bern 2016 Apr 14

This election really has me excited. Bernie Sanders is bringing a new energy into politics, and I’ve never been this engaged before. You could definitely say that I’m “Feeling the Bern.” Read more »