Gatsby For Great Good

I have been a blogger for most of my adult life (a dubious honour) and have, over a decade, used a variety of blogging platforms. My first blog, hosted on BlogSpot and please don’t go looking for it, centred around my personal explorations of atheism. When I started blogging about software development in 2011, I had the foresight to start a new blog, this time using a self-hosted Wordpress installation.

Wordpress worked well for a few years, until my installation got hacked and started advertising knock-off handbags. Since I was focused on learning iOS development at the time, I migrated to Squarespace. This let me outsource the design, hosting, and security aspects of my blog which let me focus on what I cared about most: my writing.

Several years (and a few jobs later), I had developed an eye for design and some HTML+CSS+Ruby skills. The tradeoffs that Squarespace made – specifically, the constraints it dictated on design – were no longer suiting my needs as a writer. Or even as a software developer. I felt stifled. So in 2014, I rebuilt my site in Middleman, a static site generator. This struck the perfect balance of giving me the freedom to design my own site however I wanted with the security of hosting it on an S3 bucket, where it couldn’t be hacked (as long as my AWS credentials weren’t compromised).

That was five years ago, and since then, I’ve continued developed new skills. I’ve applied those skills, building client-side search for my blog (and on Artsy’s blog). I learned enough Bootstrap and jQuery to build a Portfolio, a home for my conference talks, and even some interactive blog posts. I even did some SEO, loading “critical” styling inline, in the HTML header. But I would never have called myself my a “web developer.”

Until recently. My work at Artsy has pushed me to learn React Native and, subsequently, React itself. I helped build a brand-new ecommerce web app at Artsy using React, TypeScript, styled-components, GraphQL, and other cutting-edge technologies. After this experience, returning to my blog’s codebase felt… icky. I had built a mountain of hacks, and I wasn’t proud of it anymore.

Enter Gatsby, another static site generator, built on top of React. I could use all the tools that I was familiar with from my work at Artsy, but still keep a static site, striking that perfect balance I still wanted.

I tried, a few years ago, to migrate to Gatsby. I wrote a script to migrate my blog posts into Gatsby’s folder structure and tried it out. Unfortunately, Gatsby’s v1 development server refused to start; Gatsby collapsed under the weight of all of my posts. Another dubious honour.

So I gave up. Gatsby v2 came out then next year and so I tried, for a second time, to migrate my posts. But my heart just wasn’t in it. Maybe it was the overwhelming depression that I was struggling through at the time. It just seemed like a lot of work for not a lot of benefit.

Over the past few months, I’ve been working on a five-year career retrospective: a sequel to my initial five-years-of-iOS post. In writing this new retrospective, I was reusing the code from the first one, and again it felt… icky. Around the same time, a coworker had shared react-timeline on Artsy’s Slack; it looked way better than the timeline that I had built with jQuery in 2014. I wanted to use it. This was the kick in the pants that I needed (post-recovery) to try a third time.

This time, I didn’t start with migrating the posts because migrating hundreds of posts from three different content systems is hard, and I am lazy. Instead, I started with the site design. I took a Gatsby starter project that used TypeScript and styled-components, and worked on migrating it to my existing design (no need to re-invent the wheel). Not only was this fun, but it helped me get emotionally invested in the new codebase. Every commit made the Gatsby site look and feel like the site that I was already emotionally attached to.

It took three weekends and 140 commits, but I finally did it. Here’s the very brief breakdown of my process:

  • Set my Netlify build command to rake build || yarn build so that I could have in-progress deploy previews without breaking my existing continuous delivery.
  • Move the old site into an ./old directory so I could reference the existing implementation and, eventually, move the posts and images into the new file structure.
  • Migrate the design. Holy moly this was fun, but took a while.
  • Build out static pages (my portfolio, speaking page, etc).
  • Create React components to replace my custom Middleman plugins. (No more regular expressions! Ugh!)
  • Rebuild the RSS feed, sitemap, opengraph tags, that kinda stuff.
  • Write a basic migration script to move the posts and their images into Gatsby’s structure, reformatting their contents and yaml frontmatter, and translating Middleman plugin invocations to React components.
  • Migrate the blog posts in batches, moving the files from ./old to keep the git history as continuous as possible. I visited every blog post in the browser to make sure it rendered correctly, and to improve the migration script for the next batch.
  • Compare the old and new sitemaps and create any necessary URL redirects.

The code is definitely not perfect. The design still needs to be tightened. But “done is the enemy of perfect”, so I shipped the migration last weekend.

All the heavy-lifting that I had to build myself in Middleman was so easy to do in Gatsby. Search is just a plugin. Critical CSS gets inlined for me automatically. My posts are written in MDX, so I can mix in React components. No more Bootstrap or jQuery, so I only have the styling that I actually use.

Et cetera. And so on. Gatsby is just so… nice!

So that’s it! Finally, my personal site is congruent with tools that I actually use day-to-day. I feel really comfortable working in my site’s codebase and I’m excited to build more interactive posts using custom React components to tell compelling stories. Gatsby and React have opened up a whole new world for my writing, and I’m so excited to see what comes next.

Over the years, I had gotten really used to using Ruby as my go-to scripting language; moving to TypeScript has been another learning curve. And I’m still climbing that curve. And you know what else? Gatsby is… it’s kinda hard. Gatsby strikes a good balance between the “magic” of Ruby/Rails and staying the heck out of my way, but any tool this sophisticated will necessarily include a good measure of inherent complexity.

I continue to learn.

In the course of this work, I had to look at a decade’s worth of my writing, which was kind of a trip. It was fun, but a bit emotionally exhausting. And it made me realize just how out-of-date my portfolio is: I made it in 2014, and I’ve grown a lot since then. It feels almost… quaint to look at now. It doesn’t reflect who I am anymore. After I clean up the Gatsby code and publish my five-year retrospective in December, my next step is to rethink my Portfolio from the ground-up.

I’d like to give thanks to a few folks who helped make this happen, even if they didn’t know they were helping.

  • Orta Therox helped with getting my Gatsby internals modularized so that I could write them in TypeScript.
  • Harshil Shah for tweeting through the process building his own site in Gatsby.
  • Majid Hajian for the fantastic starter that I used.
  • Honestly, all of my coworkers at Artsy. I learn so much from everyone there, every day. I wouldn’t be the developer I am today without you all.

So. What did I ultimately learn? A lesson that I seem to be re-learning every six months or so: I should never pigeon-hole myself. That goes for you, too. If you’re a software developer, you can build anything. I believe in you, and maybe finally, I can believe in myself. Take care.

Please submit typo corrections on GitHub