Jack Anderson

Building the Blog

• 5 minute read

Why Blog?

I’m a big believer in documenting knowledge and learning in public. So much of my personal interests and discussions happen in places like Slack (if they’re written down at all), it makes sense to have a place put to words some of the things I’m thinking about.

I recently started working remotely full-time (not just for the duration of COVID-19), and wanted to find a way to start building a distributed community, as I can’t just pop into meetups to chat with people now.

Why this stack?

I had two crucial criteria for how I wanted to build this blog:

1. I need to own my blog.

If I want to migrate from Gatsby someday, or if I want to extract my content, it should be set up behind a domain I own, and stored in a format I can extract easily.

This rules out places like Medium, dev.to, hackernoon, and their ilk. I have other gripes with their strategies and content too, but this criteria is enough to rule them out.

2. I need the tooling and development to get out of the way.

A technically impressive but contentless blog is a bit useless. I know myself, and I know I’d go down a dozen React rabbit holes before actually putting pen to paper to post.

This knocks out bespoke solutions from the competition, as well as interesting projects in tech stacks that would take some ramping up for me.

There are also a few secondary goals:

  1. Static rendering is interesting and I haven’t had much opportunity to touch it yet.
  2. I want to spend some time really getting to know the System UI Theme Specification used by styled-system, theme-ui, rebass and a few others.
  3. Check out the state of tools to see if there’s anything I can bring back to work as a useful addition to our projects.

Ultimately, I’ve heard near-constant praise of Gatsby and Netlify used together. Gatsby is built with familiar tools and promises a great developer experience, and Netlify is supposed to make it silly-easy to deploy. The two seem worth at least a day or two of fiddling, and given Gatsby renders markdown, migration would be easy if I wanted to try something else.

Observations on Gatsby

Gatsby is a static site generator. It boasts of an impressive array of plugins and integrations, and offers a pretty slick development experience. There’s more to it, too, but I’ll let the Gatsby team do their own sales.

I worked with gatsby-starter-blog as a template and modified from there. Some of the more substantial changes I made:

  • Adopting TypeScript (which has good, but not perfect, support in Gatsby)
  • Adding in GraphQL Codegen to type all of the query responses. (Gatsby conveniently provides gatsby-plugin-graphql-codegen which mostly runs out of the box)
  • Ditching typography.js, the built-in styling library, and replacing it with theme-ui.
  • Migrating to MDX instead of markdown to take advantage of theme-ui‘s features.
  • A whole pile of debugging that came out of these changes. (More on that later)

Some highlights:

  • It really is very easy to get up and running with. If I weren’t so insistent on ripping out half the tooling and replacing it with my own, I could be running a blog and writing content in under an hour.
  • The documentation is also generally good. Their site is easy to navigate and discover.
  • Having plugins working right out of the box was an enormous boost, too.

The pain points:

The ‘traditional’ (for lack of a better term) approach to GraphQL schemas is to hand-write them, either to match an existing data model or in advance of writing your models.

Gatsby (and a few notable others) follows a different pattern, where the GraphQL type definitions are auto-derived from the underlying data. In this case, that’s a mix of MDX and JSON. During early stages of a project like this, that’s very unstable. Dropping a field from gatsby-config.js will blow up your queries as the schema has been changed from under them.

This has an irritating side effect. Bridging GraphQL, a typed domain specific language, and TypeScript, a typed superset of JavaScript is both an an enormously frustrating problem and a huge opportunity. Because of Gatsby’s gql schema is autogenerated, there is little control over what types are generated. Gatsby, types virtually all fields as nullable on the schema. Handling query responses safely in code requires a dizzying array of short-circuits, safe navigation operators, and nullish coalescing. There are efforts to improve this, but it’ll probably take some time.

Another substantial pain point was getting theme-ui to apply its styles to rendered MDX content. This is a feature it promises, and it’s documented as fairly trivial. Ultimately this had to do with a dependency mismatch, resolved by switching to yarn and using a resolutions field as such:

  "resolutions": {
    "@mdx-js/react": "1.6.16"
  },

Finally, this issue didn’t bite me, but Gatsby does strike me as a truly enormous amount of tooling to adopt, and while the sites are lightweight, the process is heavy. After this exercise it still feels like the right choice for a blog, but I don’t think I could recommend it if my work wanted to rebuild our landing page, for example.

Observations on Netlify

Netlify was shockingly easy to set up a simple site. I just pointed it at my repo and away it went. They currently claim to be setting up an SSL certificate for my domain, too, which is quite nice.

That said, I’m not convinced that this is what I would recommend for a more enterprise-y use case. It’s great when I don’t want to think about it, but deploying React apps isn’t exactly an unsolved problem. Netlify also seems to have put a big bet on Gatsby and optimized for that case. I have no idea how it would handle a different use case.

Back to posts