Getting to Grips With Gatsby

This blog has lived through several different incarnations. It original began life as a wordpress blog, hosted... somewhere. I can no longer remember - but I do remember using cPanel. At some point I got into Markdown, and Ghost had just been released, so I added some digital ocean into the mix and began hosting it on a VPS. I got tired of managing that, and went with Hugo and Netlify a couple of years ago before I became aware of the whole 'serverless' thing. As of now, the site running on AWS Amplify, built with Gatsby.js.

But before we get to that, allow me to produce a little more exposition...

A little while ago, I began experimenting with a small server side rendering project. I had stumbled up a library called VexFlow which is a javascript library that produces music notation as SVG. I did a small trial where I would call an AWS lambda function, and it would return the SVG directly from the server. I did this to see I could generate these SVG's server side without needing to perform the generation on the client side. I decided not to pursue this further for the time being.

I figured out that the above might be useful for automatically generating music that could be used for sight-reading excercises - but may not nessecarily be useful if I was designing something for content that was unlikely to change - eg; programmed excercises, etudes, etc that are designed to be practiced over and over again. In all honesty, it would probably be faster the for the client to generate this content than take the round-trip penality involved in called a lambda function.

That was roughly the time I had a second epiphany - surely a static site generator could preconstruct the SVG? This began my search to look for a javascript based SSG that could perform this task.

At this point, I decided to take stock of what exactly I wanted in order to achieve this. Listing them out, these were my requirements

• A static site generator that was based on a component oriented approach eg; vue or react. The idea was that this would enable me to extract the notation svg functionality into it's own component - this was my number 1 requirement, and I'll detail how went up doing this in another post.

If that is not clear I wanted to take something like this;

# Music Excercise one

some preamble about the excercises

<music-notation>
options scale=1
tabstave
notation=true tablature=false
notes :q C-D-E-F-G-A-B/4-C/5
text :q,.0,C,D,E,F,G,A,B,C
text ++,.2,3,0,2,3,0,2,0,1
</music-notation>

Which would produce:

• Would do pre-rendering of the different 'pages'. The idea here was that I wanted something that would have an extremely fast load initial loads
• Each page could be routed to directly; eg I wanted it to SEO friendly, despite being based on a Single Page Application framework, which typically are difficult for search engine's to crawl.
• Ideally had support for components in markdown. I wanted the ability to author my content in markdown and mix react components within to produce the content in-line. I didn't want to reference images directly, but author them directly in the content.

From this I was able to identify a few different options - these were Gatsby, Nextjs, annd React-Static on the react side of things. On the vue side I identified Vuepress and Nuxtjs.

Being somewhat familiar with react, my first attempt was with react-static. It seemed less 'big', and I felt that might make it easier to work with. However, the lack of 'batteries included', particularly with regards to markdown/mdx support made me abandon it. The struggles I was having were directly addressed in vuepresses' documentation, so I decided my second attempt would be with Vuepress.

I managed to get up and running with Vuepress without much effort. Not long after I was able to achieve my goal; create a small component in which vextab could be embedded, which would then be transcluded during the build process to output an SVG. It was also quite snappy; load times from links were quite fast. Where everything kind of came off the rails was in customization. Vuepress really only has the one theme available, and requires a fair amount of editing to customize. As someone completely unfamiliar with vue, I was unwilling to invest the time to build upon this. Because of this, I decided to pass on looking into Nuxt - which by all accounts would have taken more time to get started with than Vuepress as well as requiring me to spend time learning Vue.

That left me with Gatsby and Next. It was around this time that I identified mdx, and determined this was more or less inline with what I was trying to achieve. There were a small number of existing Gatsby projects that had been using mdx, and there seemed to be a couple of plugins designed on integrating it with gatsby. Together with the amount of documentation and project momentum, I skipped evaluating Next and went with Gatsby, though I may take a deeper look into Next at some point in the future.

I won't go into major detail about each single step I did to convert the blog over to gatsby. I started with the tutorial that was available in Gatsby's documentation and slowly edited it until I was happy with it. Instead, I'll detail some of the things I like about Gatsby.

A Mature Ecosystem of plugins

There's a plugin for just about everything, and they are fairly well organized based on what they doing i.e. fetching data vs transforming it. This made it fairly easy to find the features I needed for generating the site. Also cool - this separation of concerns makes a stark distinction between fetching data and rendering it. It seems like a small thing, but it made it very clear where data was coming from - it wasn't too hard when debugging to find the source of the data.

This does make configuring Gatsby feel like configuring Webpack. I'll let the reader decide whether they like that or not.

Idiot proof PWA support

Automatic code-splitting support

hosting

• AWS amplify console announcement

• Setting up with AWS amplify

• Resolving Routing Issues

• Productionizing