Developer Showcase Spotlight: Gatsby Bricks for LEGO builders

My main job is being a web developer, and I built Drupal sites for many years before switching mainly to Contentful and other headless CMSes. As the company where I worked got into more and more headless builds, it occurred to me that I should try out some of the newer CMSes that seemed specially suited for this role.

I arrived at Contentful because it seemed to have a high amount of adoption compared to other headless CMSes, and its UI had great support for nested, referenced-based content structures. In the next few years, I would go on to try some other headless CMSes. However, I continue to choose Contentful for new projects because I think that in most cases, having to manage source code for your CMS is a liability rather than an advantage. If you use Contentful, your whole content management workflow will always be covered by Contentful’s testing suite, so that you can worry about other things.

If you are wanting to learn more about Contentful, or any CMS, it helps to have some kind of collection that you want to showcase. I happen to have a ridiculous amount of LEGO, so when, a couple years ago, I decided I wanted to learn about a CMS that wasn’t Drupal, I signed up for a Contentful instance and started adding pictures and descriptions of my LEGO builds as content. It has been a lot of fun!

Content Model

Gatsby Bricks uses Contentful to store all of its content, which includes 95 percent of the words you see on any given page, and all of the images. Gatsby Bricks has a few “first-class” content types:

• Build – A LEGO that someone built

• Builder – Someone who built a LEGO

• Page – A landing page with a URL

• Blog Post – A blog post

These content types get their own URL when the site is built.

It also has about two dozen more supporting content types, which vary from representations of different bins on the storage guide, to things like individual headings, images, text chunks and “cards” that appear on various landing pages.

The picture below shows how these supporting component entry types stack to form the top of the homepage:

Deployment infrastructure

Gatsby Bricks began with the Contentful/Gatsby Blog Starter. I was impressed the first time I clicked through and was able to deploy a static site to Netlify that I could customize. This stood in stark contrast to what I would have had to do in order to spin up something like Drupal, which I would say has passed beyond the pale of being an option for hobbyists to use.

I have much love for the Drupal project and the Drupal community, but I think it has become an enterprise-only option owing to how much effort it takes to orchestrate CI/CD with Composer in play, whereas platforms like Netlify and Gatsby Cloud have solved this problem neatly for the Javascript universe.

Anyway, Gatsby Bricks uses Netlify to host the site and do CI/CD things like executing the static build, and it very rarely runs into problems.

Static Page Generation

As I mentioned, I used Gatsby to statically build the site. I took advantage of Gatsby’s incremental builds to keep build times small. When I upgraded to Gatsby 4 and turned on the incremental build setting, it reduced build times from about six minutes to around 1:30 on average.

Static generation works well with a headless CMS like Contentful because it solves one of the bigger challenges that headless CMSes pose, namely that your content is always a network hop away and could be slow to retrieve. Gatsby and other static site builders put all of this work in the background where it won’t affect site visitors.

Contentful is good about not melting down when it is fielding requests to build site content from Gatsby. This can actually be a problem for monolithic CMSes. They just are not tuned for responding to large bursts of cache-misses, unless you pay for a lot of computing resources to back them up.

Environments aliases

For most of its life, I did not use Contentful’s multi-environment capacities, but recently I did use an environment alias to do what Contentful refers to as “risk-free releases and instant rollbacks” for a larger change to the content model. 

Environment aliases in Contentful can help you adopt a blue/green deployment pattern, which is helpful these days when the operation of your site or application as a whole depends on a variety of distributed services functioning smoothly, both before and after teams deploy new code.

One thing that helped me was following the expand first, contract second rule. Roughly, this means don’t make changes that remove parts of the content model that your code depends on until you have deployed new code that no longer depends on the old model. The classic example is when you want to delete or rename a field.

Using environment aliases and following expand/contract best practices for the content model, I was able to deploy a large update to the code and content model without having any downtime.

Frontend stack

Since the site uses Gatsby, the frontend is React. I am a big fan of React. My favorite thing in React is useState — it is just very powerful and simple.

I built Gatsby Bricks before the hooks era of React, so since then, I have had to rewrite most components. I actually enjoy refactoring code when I’m not on the clock.

The site doesn’t have too many complex parts, but I will showcase a few things that are kind of fun.

1. Latest builds component

This component is how visitors discover, filter, and page through the builds. It’s the only piece of the site that isn’t built statically, because there are too many permutations of filters and pages to do so. So, it calls the Contentful Content Delivery API directly from the browser. That’s why it loads a bit later than the other parts of the page. It is on my to-do list to make the initial set of items render statically, so that most page loads don’t need to hit Contentful.

The latest builds component appears on the homepage and the builds page, in a larger format. It uses React contexts to share logic and state between a set of control and display components, such as the pager, the buttons, the filters and the results grid.

2. Storage guide

This part of the site is a guide for those who seek to sort their LEGO. It turns out that creating a good LEGO sorting and storage system is as time consuming and expensive as collecting and building, and there were no particularly good guides on the internet for how to sort and store LEGO effectively “at scale.”

Now is a good time to mention that Gatsby Bricks uses the Material UI design system for React. The storage page uses tabs, buttons, “paper” surfaces, etc. Going back to the build listing, that uses MUI form elements like toggle switches and fancy select boxes.

Selecting Material UI for a project like this is a tradeoff. On one hand, it gives you a lot of nice looking “stuff.” At the time of starting this, I had not been doing CSS on a regular basis, so it was nice to find that working with MUI has you using Javascript almost exclusively.

On the other hand, MUI has its own ways that you have to learn, and some quirks when it runs on Gatsby. I also remember having to rewrite most of the theme when I decided to upgrade to MUI v5 from v3.

One cool thing is that all of the content on the storage guide page is structured and modeled in Contentful. I have content types such as:

• Piecetype Segment – e.g. “Angle bricks”

• Piecetype Segment Type – e.g. “Utility”

• Storage Type – a product that I use to sort things

With Contentful, you can model entry types like this pretty quickly. I do it right in the UI. I know that on larger sites where versioning of the content model is more important, it is a good practice to use the Contentful Content Management API for content modeling.

3. Search

I built a search utility so that my visitors can find a build by title. It uses Elastic Lunr. The advantage of this is that search is very fast. Unfortunately, this is the case because Lunr adds an entire search index to the response when the page is served, which makes initial page load slower. So, it’s a tradeoff. I think for the size of Gatsby Bricks today, it makes sense.

4. Landing pages

Besides builds, all sites pages are what I sometimes call “composed content stacks.” The homepage, or this page about Y-wings are good examples. Both are “Page” entries, and have a field called “Components” that I load up with references to the components that actually hold the content, as shown below:

This lets me control exactly what goes on a page, without having to add chunks of HTML to the CMS. The catch is that for any component I want to have available, I need to write a React component to handle the display. Luckily, I enjoy doing this.

Conclusion

From a technical perspective, I think the biggest factor that made this project fun and successful was how well Gatsby and Contentful work together.

The gatsby-source-contentful plugin is great at making all of your Contentful entries available in the Gatsby graph, Contentful serves content reliably at build time, and the Contentful Image API gives you images at the right size without much fuss.

Building a website to document a collection can be a fun way to learn about a new CMS and its surrounding tech ecosystem. You might even find yourself learning a bit about photography, or building a lightbox to use as a backdrop.

This project has brought me quite a bit of joy as well, as it provides a record of many wonderful hours spent building with my family, cranking out spaceships, houses, animals, and scale models of my basement.

I hope you’ve enjoyed the tour!

We want to see what you’ve built! Share your most creative use of Contentful to the Developer Showcase — maybe it’s a website, developer tooling, or something else. Your project might inspire other developers to think outside the box and grow their skills. Let's celebrate awesome builds and create a welcoming, inspiring community. Submit an entry.