In Which We Select Gatsby As Our SSG

I.

Because I needed to provide a path for clients on WordPress to take advantage of the enormous performance boosts of jamstack deployments, I waded into the SSG world last year. Somebody said I should have a look at Gatsby. Sure, I thought. How hard could that be? It’s written in JavaScript. I know JavaScript.

Here’s a great idea, I thought. Put together a full-blown WordPress publication site, start publishing articles about Gatsby and related things (thought I wasn’t one hundred percent sure what the related things were at that point), then, midflight, rebuild the airplane, chucking out WordPress and migrating to a Gatsby site.

People are going to love this, I thought.

And maybe they will, in the end. But if so, my fear is that it will be because it was kind of a car wreck that from which they couldn’t avert their eyes. Still: forward.

 

II.

This raises the question of which jamstack platform. Actually, this is a more complex question because jamstack as a term has pulled in lots of things that aren’t, strictly speaking, jamstack (which is one of the minor problems with the term jamstack). Jamstack is JavaScript and APIs, but what about frameworks that don’t use JavaScript, but are nevertheless producing sites where the content management (and other components) are decoupled, where the default mode for doing things is pre-generating pages, and so on? Hugo, for instance, which is built on the Go language. Or Pelican (Python) or Jekyll (Ruby).

But even boiled down to the simplest version of the question and assuming JavaScript, there are several options, top among them probably Gatsby, Nextjs, Eleventy, and Gridsome. Because of their early lead in market share and my desire that PeakZebra be relevant to the widest readership possible (and taking into consideration the market share of the various jamstack options, I went into the question already pretty well narrowed down to Gatsby and Next.js.

Gatsby is the first SSG framework I played around with (well, at least since hand-coding perfectly static HTML in the early days, including actually (gasp) before JavaScript turned up) and it’s still the one I have the most familiarity with, so, to cut to the chase, I decided to migrate the site to Gatsby.

I will almost certainly build adjunct sites that run on other platforms, just so I have a first-hand look at all of the major ones. But priority one is to get to Gatsby. There are lots of things to like about Gatsby, as readers of this site probably already know.

But one thing that’s attractive at present is the very clean way in which Gatsby can use WordPress as its headless Content Management System (CMS).

 

 

III.

 

A  relevant confession. I’ve been pretty good at JavaScript in the past. Indeed, I taught a one-day course in JavaScript for a short-lived training arm of Ziff-Davis, a publishing company that put out a lot of tech-related magazines but that, astonishingly enough, dated back to 1927, when they formed to publish Aviation Magazine. Anyway, I’ve taught JavaScript, but that was years ago and, returning to it in 2020, I found that it was a totally different animal.

Same thing with Cascading Style Sheets, by the way. There was a Ziff-Davis magazine for a while called ZD Internet, in which I wrote an early overview of CSS in—brace yourself—1997. In the ensuing twenty-odd years, it’s become a horse of another color.

So I’m thinking: I still deeply enjoy programming. This will be good for me. I’ll get back the old swagger.

JAMSTACK, PUNCTUATED

There’s been some discussion about how to write “Jamstack” of late. The argument for “dropping the acronym” is given in a blog post by Brian Rinaldi, developer advocate at StepZen.

IV.

One aspect that’s clear about JavaScript’s having growing up is the advent of very fancy libraries that handle things like user interface. In particular, React.

React puts UI stuff in a browser window. Early in my process of getting my footing in React, it appears to me that it is akin to object oriented programming in C++, in that it has what I would called classes and these are extended by your JavaScript code. In React these are components.

I have a theory when it comes to development that most of the languages that the web world has gotten excited about over the past twenty-odd years looks remarkably similar to the C programming language. Since I cut my teeth on C and coded professionally in it for several years, this is good. PHP looks like C. Java basically is memory-safe C. JavaScript looks like C. All is well in my world.

(It’s not that simple. I ran across the transcript of a speech Paul Graham gave to Python coders in which he imagines what sort of programmer there will be in a hundred years that we understand enough that we might actually use it some extent even now. It’s quite imaginative and I kind of get the impression that Graham doesn’t think that hundred-year language is going to look much like C.)

Because I’m feeling this foolhardy sense of confidence, I decide to cut to the chase and do some online Gatsby courses. The one by Andrew Mead I particularly enjoy.

V.
On the wordpress side of things…

The way Gatsby looks at WordPress is just how it would look at any other GraphQL endpoint, so most of the trick with connecting WP to Gatsby is installing a couple of plugins on the WordPress site. Specifically, you need WP Gatsby and WP GraphQL. You just click the Add New option for plugins, search for those two names, select them to install them, then click the activate button.

As if by miracle, almost no configuration is needed. There is some stuff that you might, at some point, want to fool around with in the WP GraphQL settings, but the main thing you have to do is tell it exactly what the pathname is for GraphQL requests. It defaults to “graphql” and I can’t really think of any reason why that would need to be changed. The simplicity of it is, of course, because your WordPress installation is already set up as, basically, a blog, with a bunch of posts, plus whatever non-post pages you’ve created.

At this point, you can click on the “Graphical IDE” option in the left sidebar of the admin console and up pops GraphiQL.

VI.
And Way Over Yonder in the Minor Key…

It’s kind of magic. Not only can you query for post content, but you can query things like which plugins are installed, or which themes.

At this point, if you make a GraphQL query from within a Gatsby application, you’ll get back posts just the way you’d get them if you used GraphQL to get your posts from markdown files. Very little has to change in order to change your markdown-file-driven Gatsby site over to one that pulls posts from your WordPress site.

This is probably obvious, but in case it’s not: life goes on as normal on the WordPress site. Until you explicitly cut over to the Gatsby front end, the WordPress site is still serving guests. Furthermore, you xxcan still jump into WordPress and make new posts (which is exactly what’s going on with this post).

Indeed, if you’ve got an editorial workflow running on WordPress, it’s still running. And it will still be running, just like you set it up, even when the Gatsby app is what’s serving the pages up to visitors.

And one more thing that’s probably obvious but let’s just say it: nothing about the look and feel of your WordPress site has been incorporated into your Gatsby app at this point. It gets the titles, the slugs, the content. But whatever theme you’re using to make your WordPress site snazzy lives only on WordPress. In other words, there’s still the non-trivial task of making the Gatsby site a wonder of design.

So…

This is where things stand at the moment. GraphQL is running on the WordPress site and, here on my local development machine, there’s an extremely bare-bones starter version of a Gatsby site that incorporates the plugins needed to prepare and send off GraphQL queries. When I run the GraphiQL tool from the Gatsby side of things, there are the posts, the pages, the whole thing. Now, to build up a Gatsby version that has at least some of the bells and whistles of the WordPress version.

The Minor Key?

You know how sometimes you want to do something that you know everyone will immediately recognize as wonderfully witty and literate? This would be one of those moments, if it worked. By my strong suspicion is that no one recognizes that this is the title of a song. Also, the song has nothing to do with this. The subtitle really and truly should have just been “And Over in Gatsby…”

Some Resources

This is the first part of a series, tracking progress on the WordPress to Gatsby migration as it happens. There will be more on the Peak Zebra Project in a week or two, depending on how bloody things get.