There are a lot of static site generators these days. Jekyll seemed to be the most popular back when I was in college, but other systems have since popped up: Hugo is a big one, and Pelican also has a somewhat mature ecosystem. Each generator is always tightly coupled to a particular language: Jekyll uses Ruby, Hugo uses Go, Pelican uses Python.

I've wanted to switch from Jekyll for a while now, mostly because I was never fluent in Ruby and that made writing plugins a huge challenge. I recently saw on HackerNews that Gatsby released v2.0.0, and I'd never heard of it. Turns out it uses GraphQL and React (two things I use pretty heavily at work) and makes it super easy to get started. I was able to follow the tutorial and get a site up and running in a matter of minutes.

The cool thing about Gatsby is that the entire Webpack pipeline is included out of the box, so you get nice things like hot-module-reloading while developing, and everything gets minified for the production build.

Flow Typing

My team at work uses Flow for static typing JavaScript applications, and I've gotten used to all the benefits that provides: catching errors before they go to production, jump to definition, and remembering what bits of code do what. We also use Relay for GraphQL Javascript apps, which has a compiler that generates Flow types as a part of parsing GraphQL queries.

However, turns out that Gatsby is missing this particular feature, and that means all GraphQL queries are untyped by default. Not good!

Luckily, Apollo's CLI allows you to generate Flow definitions from any set of Javascript files, regardless if you're using their ecosystem or not. I chained a couple of commands in my package.json:

rm -f src/codegen/graphql/* && \
    apollo schema:download --endpoint http://localhost:8000/___graphql gatsby-schema.json && \
    apollo codegen:generate --tagName graphql  --target flow --useFlowExactObjects --useFlowReadOnlyTypes --queries './src/**/*.js' --schema ./gatsby-schema.json --outputFlat src/codegen/graphql

This queries the local GraphiQL instance, dumps the schema to a file, and uses that schema to generate Flow types for all JavaScript files in my src directory. I can then import those types from the components that need them:

import type { PostQuery } from '../codegen/graphql/PostQuery';

type Props = {|
  data: PostQuery,
|};

export default class Post extends React.PureComponent<Props> {
  ...
}

I've never actually been excited about a static page generator until now, and I've found it super easy to get things up and running.