An Almost Static Stack

Charlie Gleason
Feb 3, 2017 · 6 min read

Or how create-react-app, with a couple of modern tools, can make building static sites (with benefits) a breeze.

Update, 11 December 2017: The response to this setup has been super cool. My sincere thanks to those who have helped people get set up in the responses, and to those who have reached out with advice and high fives.

I have updated the dependencies in the repo to the latest versions, along with the guide, and tested that everything is still working as expected. Some of the output in your terminal might look slightly different than the screengrabs, but do not fear—you’re all good! Also, stereobooster has put together an amazing overview of possible performance optimisations for the final product which is well worth a read.

And again, thanks for reading.

Note to self: write more notes to self

I’m a big fan of create-react-app. It hugely simplifies starting a new React-based project, and it serves pretty well for any ES6 / ES2015 setup regardless of whether you use React. I originally built Sandpit with it, purely because I could get straight to coding, writing tests, and deploying to a static site host like Surge or Now.

create-react-app’s best feature is its simplicity, but that that simplicity comes at a cost. As your application grows in complexity, you either have to yarn eject and take the entire set up into your own hands, or live with the limitations.

But hey, neither of those options are necessarily bad. But if you’d rather stick within create-react-app, there are a few tools you can use to take advantage of the incredible ease of use and speed of development that comes with create-react-app, without any terrifyingly massive webpack.config.js files keeping you up at night.

So, what are they?

Kind of goes without saying, really.

Declarative routing for React, with a fancy new v4 that resolves a lot of the confusion around using the library.

Manages the document head, including title, description and meta tags.

A zero-configuration pre-renderer for React apps.

All the cool kids are into it, and it allows you use SCSS-like code in create-react-app (which, out of the box, supports vanilla CSS)—styling for the component age.

Okay, so, why?

When you build your site, react-snapshot fires up a server, visits each relative link, and saves a copy of the rendered page in the build folder. When you deploy it to Surge the app is “hydrated” with the JavaScript hooks, and you can spend the remainder of your afternoon sipping a crisp white wine spritzer (or apple juice and soda, depending on your personal preference).

So, let’s go.

The create-react-app installation process, now with added emojis!

Setting it up

npm install -g create-react-app

Then you can make a new app, which will take a while, so maybe make yourself a coffee? It’ll take the edge off that daytime wine you had.

create-react-app app-name

When the installation completes, jump into the directory and install some fancy dependencies.

cd app-name && yarn add react-router-dom react-helmet react-snapshot styled-components

Also, you 100% do not need to use yarn if you don’t want to. npm is also great, but yarn is super fast, and let’s face it we’re all still reeling from that whole create-react-app installation waiting game. Plus it has emojis!

react-snapshot requires a couple of quick changes to the default create-react-app setup.

First off, change your package.json build option.

"build": "react-scripts build && react-snapshot"

And then patch up the default src/index.js.

import React from 'react';
import { render } from 'react-snapshot';
import App from './App';
import './index.css';
<App />,

And voila. If you run yarn build, you’ll see some sweet snapshot magic.

$ react-scripts build && react-snapshot
Creating an optimized production build...
Compiled successfully.
🕷 Starting crawling http://localhost:2999
✏️ Saving / as /index.html
🕸 Finished crawling.

✨ Done in 11.06s.

As you can see, react-snapshot is taking the app and outputting a static index.html.

It might not look like much, but it’s so great.

Still, it doesn’t do much about the key areas that a search engine is looking at—the title and metadata in the head. That’s where react-helmet comes in. It is a component that helps you manage the document head, meaning while someone navigates your app, your metadata stays in sync.

Here we’re populating the title with “You Are Doing Great”, which is true, using the Helmet component. It displays in your browser tab, and all is well with the world.

Unfortunately, when viewing the source, the <title> is still React App.


That’s where react-snapshot comes in. By using react-snapshot in conjunction with react-helmet, you can pre-populate both the head of each route, and the body, on server and client side. It is literally win-win. So let’s build it.

yarn build🕷   Starting crawling http://localhost:2999
✏️ Saving / as /index.html
🕸 Finished crawling.

And when we look at the generated index.html?

<title>You Are Doing Great</title>

Omg, see? Even the server gets it.

For routes that aren’t snapshotted (I don’t think that’s a word, honestly), react-snapshot provides a fallback, 200.html, which behaves exactly like the non-snapshotted (still not a word) index.html. Hosts like Surge serve it automatically if no other snapshot is found, meaning react-router can grab the URL and route it appropriately. It’s automagical.

I’ve pulled together a repo that shows all this in action, called You Are Doing Great, or YADG. You can see the live version in action here.

The repo is on Github, too:

It’s set up with all the features I’ve mentioned, including routing, snapshotting, metadata management, almost hot-reloading, and using styled-components.

Also, if you’re looking for an example in the wild, I built my site on, essentially, the same stack.

If you have any questions leave a comment or say hi via Twitter. Alternatively, enjoy a GIF of an owl being petted.

Owls are so great.


Tutorials and thoughts on front end development

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store