The future is amazing… if you have time. The dev community is all aquiver about some new technologies at the moment. We’ve been using one of them, Netlify to host pattern libraries, static HTML sites, and prototypes for a few months.
However we hadn’t really had a chance to use Craft—our preferred CMS, in headless mode. To add to our shame, we haven’t had cause to build anything using Gatsby JS, although the team have used React on various projects. Recently a client requested we use Gatsby JS for a project and we were excited to get stuck in.
Buzzword Bingo Explanation
A headless CMS is just like a regular CMS except that rather than serving templates and HTML, it behaves more like an API. It allows you to structure your content and expose it to any appropriate technology. Content editors get to use the Control Panel to add pages and content as normal, but rather than having a single end-point (e.g. a website) a headless CMS can send content to the web, to apps, to third party services, or to some weird technology that we haven’t even thought of.
Our preferred CMS, Craft, has a couple of ways of exposing its content in a headless way. One way is to use the Element API. This exposes the content as a JSON REST API where you create the endpoints and hitting a specific URL will return content in a JSON format. That’s cool and all, but traditional REST APIs have some problems.
Depending on how they are constructed, REST APIs often result in you needing to make several API calls to get the information you need. For example, you might need to hit one endpoint for a list of users, then another for a each user’s online status. This can be a bit of a headache, especially when using an asynchronous language like Javascript.
However, Craft has another plugin: CraftQL. This adds a GraphQL server to Craft.
GraphQL
GraphQL is a query language developed by Facebook. Rather than have the data solely dictated by the server, it allows the client to decide what it needs and query it all together. In our previous example, we could get a list of users and the details of their status’ in one go. This is both clever and powerful. It takes a lot of burden off of backend development. There is no (or much less) need to think about all the different content and ways people might want to access that content before publishing the API.
So now we have a platform for our client to add and edit their content. Now for the website...
Gatsby JS
Gatsby JS is a tool for building websites. It allows you to build a static site from a collection of React Javascript components. But it’s more than a static site generator. Gatsby wraps a bunch of awesome modern development technologies together without the need for you to configure anything.
Say wha?? I’ll break that down a little
- Gatsby will compile all of your React components, styles, and data into a static site. This means no database queries and no templates to compile at each request. The server just needs to serve HTML files from a folder. That is not only fast but its inherently secure as there is no database for someone to get to.
- Gatsby will automatically code split your Javascript and inline your styles to make each page as small as possible and deliver it in as few requests as possible. On the web, smaller and less requests means faster.
- A Progressive Web App is basically a website which is built in such a way as to be available offline (after its been loaded once).
Gatsby lets you play with a whole bunch of cool web tech without you needing to spend ages configuring everything. Wanna Webpack? Gatsby does it all for you without needing to write a Webpack config. Can I use SCSS/LESS/Post CSS/CSS Modules? Gatsby has you covered with a bunch of easy to add and configure plugins. Progressive Enhancement? No problemo, Gatsby serves all the pages as static HTML so you get to build with React but without worrying about the downsides of a single-page app.
It's a kinda magic…
This is not only cool, it’s almost like magic. You simply install the Gatsby CLI from NPM and it will do all your scaffolding for you. You can even setup your own starter kit so that you can have your project structure, plugins, and config all setup and ready to go.
It takes a bit of getting your head around some of the concepts of GraphQL and how to generate pages from a feed (e.g. your blog). You’ll also need JS knowledge and some grasp of React (but only the basics). The tutorials on the Gatsby JS site are pretty easy to follow and with some JS know how, you can fit the examples to your particular use case. I recommend having a go with a few of those to get comfortable before building anything in anger.
Gatsby also allows you to bring your own data and is built to use GraphQL. By using GraphQL, you also get the ability to combine a number of data endpoints into one consistent API. Theoretically, as well as linking to Craft CMS for our content, we could also bring in products from a Shopify store via their GraphQL Storefront API.
Hacker note: There are a bunch of services which offer GraphQL APIs. Mashups are back!
Netlify
Netlify is a service which hosts your static websites for you. But it's more than that. You can configure your site to be deployed directly from your Git repo whenever you push a change to a branch (continuous integration). Better still, Netlify can run the build for you, so no need to push up all your compiled CSS and JS code, just give it the source code and boom! This can be something like a Grunt or Gulp build or, guess what... a Gatsby site!
I strongly encourage you to have a go with Netlify as it's one of the easiest hosting/deployment experiences I’ve ever seen. It’s very slick, very simple and for basic needs, completely free.
Plugging it together
So after installing the CraftQL plugin in Craft and setting up what content should be exposed to the API, you then get an API key and URL which you add to your Gatsby config. I used the Gatsby Source GraphQL plugin which will allow you to take any GraphQL source and start building queries. You can then test your connection is working using the built in GraphQL playground, which is both in Craft and generated for you by Gatsby.
Once you’ve done that, you can begin to add some components and start querying some data. Gatsby V2 introduces a concept called Static Queries. These mean you can query data directly in a component so a Post Collection component can request all Posts and their entry dates and a snippet of content. This helps keep your components nice and reusable. It also means you don’t have the headache of passing props down a stack of nested components from a top level page component.
Then it's just a case of tinkering until you get what you want. Depending on the complexity of what you want to do, this could be a bit challenging. Some things I couldn’t work out I just tried something and it worked. That might mean Gatsby is very intuitive, or that I’m very lucky. Let me know!
If you build it, they will come
A few days later and you’ll have a super slick site, which you can deploy to Netlify by committing your code updates to Git. This is seamless and generally very quick. However there is one small problem. When your content editor edits some text in the CMS, you need a way of kicking off a build on Netlify, as Gatsby needs to re-grab all the data from Craft.
I’m sure you could build a Craft Plugin for this so that every time content was updated, you could hit a URL on Netlify to trigger a build. For our project though, we used a Craft plugin called Nethooks (available in the Plugin Store). This lets you configure build hooks for your setup. You need to manually go to settings and click a button to kick it off though.
EDIT: This Webhooks Plugin for Craft (by the Craft CMS org on Github) would probably be the best choice for future projects. It wasn't a thing when we were developing this though.
What’s the catch?
Hmmm. This will depend on your particular use case…
Not really “Serverless”
If you want to run Craft as the data provider for your Gatsby site, you’ll need to run that on a server. This isn’t a big issue for us as we are more than happy to spin up a Digital Ocean droplet and have a bunch of automation scripts for doing just that. There are other platforms that offer CMS as a serverless service, such as Contentful, if you want to remove the server entirely.
React Only
Gatsby does a lot of cool stuff, not least all the code splitting and optimisations. However, the catch is that this is React only. I like React, especially at the level you need to use it for a Gatsby site. However, I also like the look of Vue, and am interested in how Marko develops. There’s no option to use Gatsby with those technologies though.
Not for beginners
Although Gatsby is like magic, and it’s let me play with tech I usually wouldn’t have time/be bothered to get setup and running, it’s not all very beginner friendly. I’m pretty good at this stuff and it took me a little while to get things working for our specific setup. The community are pretty awesome though. For example, I initially tried using a Gatsby source plugin specifically for Craft CMS which was really tricky to use. The maintainer seemingly was not responding to issues. However a few tweets to some folks I heard on a podcast and boom—switched the plugin out and it worked like a charm.
Netlify
Not related to this project, but I have had some dealings with Netlify support which were… terse. I’ve also seen a couple of examples online of people feeling the same. They are usually helpful, and I guess you get what you pay for. However, their tiers go from Free to $45 a month which is probably a bit much for our use case. I’d be happy to pay a $10 a month for our simple setup (and my own personal setup) to get some better support. I also worry that if-the-service-is-free-then-you’re-the-product. However, for the most part, I think Netlify is a brilliant service and we will use it again.
Closed Box
Although all of Gatsby is open source, I’m not sure even if I had the time or inclination to understand it, I would know how to change its behaviour. It makes a lot of decisions for you about what’s best and how it does stuff. I personally love the idea of a benign dictator for development things. It means I can get on with writing code and not worry about tinkering with configurations and such. I know others who will probably wince at the thought of ceding that much control though.
Conclusion
To be perfectly honest, when I heard about Gatsby, I couldn’t understand the benefit of it. *Old man voice*: Why would you want to write your whole website in Javascript? However on closer inspection and understanding what it does, I’m completely sold on it.
We’ve been holding off updating our development workflow for a long time. This isn’t out of some sort of luddite spite. We have a very settled flow which is quick to set up, easy to tweak, and gets us up and running with new projects in seconds. The idea of porting it all over to Webpack didn’t see worth the hassle, as I couldn’t see the benefit of Webpack for the type of websites we usually build (i.e. not Javascript apps).
Gatsby has potentially changed all of that. Combined with a new set of CMS and hosting technologies, the overheads for using this new workflow are lower than ever. I’m sure we will use this setup again for future projects.
Further reading/listening
I recommend any Craft CMS nerds, interested in learning a bit more about Gatsby, check out this episode of the DevMode podcast. I also recommend trying the tutorials on the Gatsby website.
Got any questions or thoughts? Hit us up on Twitter.
Want to talk to us about building your new digital project with some awesome new technologies? Let’s talk.
