Craft CMS and JAMstack

September 26, 2019 7 min read

guillotine illustration detail

Guillotine illustration detail courtesy of Bibliothèque nationale de France.

JAMstack is the Beatles.

At Dot All we clutched our hearts, outstretched our hands, and jumped around screaming and crying as JAMstack filled the air.1

You probably heard about that already, and if not you might want to start with an excellent summary by Matt Gray or Ben Croker.

I'd like to clarify how headless Craft, serverless architecture, GraphQL and JAMstack relate and how they could play a part in however you build web projects.

Before that, Marion made a point on the devMode podcast that's worth repeating: Craft is not forcing you to change anything. If you build sites happily and productively with Twig, you can keep right on doing that and enjoy the exciting stuff that's coming in Craft 4. This headless, JAMstack-centric business is opt-in only and not something that requires you to change the way you work.

My Interest in JAMstack

I've been building modestly-sized, headful Craft sites for years, and I'd like to build sites statically without any compromise for content authors. My clients shouldn't have to suddenly do without Live Preview or lose control over exactly when they publish updates. My technical interest comes down to hosting and building with components. I'd like to...

  • stop provisioning, maintaining and supporting servers
  • dramatically reduce hosting costs while improving performance, uptime, and security
  • deploy static sites built with Vue, React, or Svelte (using projects like Gridsome, Gatsby or Sapper)
  • take advantage of component-centric tools like Storybook and Figma to design and document work with greater clarity

I haven't made that my new normal yet, but as of Craft 3.3 the major pieces are all there to be assembled. I'm pretty sure that's what we're all excited about.

But let's sort out what these things mean. They seem to have arrived all at once, and it's easy to confuse the pieces and how they fit together.

Headless != JAMstack != GraphQL

Andrew's talk compared the LAMP stack we know to the JAMstack we want to. It's not an alien wonder, but a rearrangement of concepts and responsibilities we already know pretty well. Cool new things that have their own tradeoffs.

The LAMP/LEMP initialisms acronyms stand for software you inherently run on a server, while JAMstack's JavaScript, APIs and Markup don't require a server at all.

For this reason, one of the benefits of the JAMstack is how well-suited it is for serverless architecture. The term “serverless” is part lie because there are still servers, but mostly great because you don't have to manage them. Usually you point a slick SaaS offering to a repository, give it some minimal configuration, and it takes care of the rest.

We'll get to Gatsby and Gridsome in a moment, but it's important to know that they still require a server even though they build sites you can host on a CDN. Gatsby and Gridsome require a server at build time, which is before the site gets deployed. This is probably similar to how you're prepping CSS or JavaScript for deployment right now, except the site's pages are all built too. Craft obviously runs on a server, but it was born building pages on the fly at request time. Various forms of caching can make that as fast as a static site, but that's the key difference between Craft and static site generators: both need web servers to generate pages, but one builds before deploy and the other builds live, upon request.

The last Craft 3 install you touched can run headless right now without any changes to its server. In the not-too-distant future, you'll also be able to use headless Craft without needing to install anything on a server—that's Craft Cloud.

Headless Craft just means Craft without Twig.2 Craft reduces its role to content manager, with a UI for authors to manage content and APIs (ElementAPI and GraphQL) for developers to extract that content and decide how and where it's presented. Those developers aren't limited to using Twig to build a frontend, but anything at all that can interact with those APIs. This plays perfectly, and at just the right time, into serverless static sites.

Static sites aren't new, but hosts like Netlify and Zeit offer platforms that make them easy to work with. Building those sites can be fun with projects like Gatsby and Gridsome.

There are two reasons Gatsby and Gridsome get so much attention:

  1. They'll take whatever content you've got. This can mean local markdown files, MySQL or Postgres, a GraphQL API, and more. It can also be any combination of sources. No matter how much there was or where it came from, it'll then be accessible in one uniform GraphQL collection.3
  2. They neatly package frontends using the things we know we should be. Performance and best practices are baked in: preconfigured webpack (!), server side rendering, critical CSS and prefetching to name a few. Plugins make trivial work of adding Tailwind or offline browsing and loads of other fancies. If you've ever tried to wire up just a few of these things yourself, you'll appreciate how they all just work right out of the box.

It's reasonable to assume, based on Gatsby and Gridsome's popularity, that humanity has not been loving the tooling complexity required for a performant, well-rounded modern frontend. Each project takes data from a variety of sources, lets us work with Vue or React and whatever we want for styling, and offers preconfigured and easily-customizable tooling to generate a great static frontend.

Live Preview

Live Preview was a real challenge for static sites until Pixel & Tonic released preview targets with tokens. This says, “sure, let whoever you want into that preview pane, just have them give us this little token so we know it's safe to share your content.” It still takes some extra planning and effort to support Live Preview outside of Craft's comfortable Twig templates, but the preview tokens make it a lot simpler.

Read/Write

If you've contemplated a static Craft site, it probably took you ten seconds to wonder how content gets back into to Craft via Guest Entries, form posts, etc.

The GraphQL API doesn't yet support mutations, which is GraphQL-speak for writing stuff that's currently just read-only. But those are coming. You can still use the Element API, see how plugin developers might support headless interaction, or just send data to third-party services.

The bigger shift to prepare for right now, however, is adding more logic to your presentation layer. If you've ever submitted a contact form via AJAX, you already know exactly what this means: have axios or jQuery post the data, look at the response, and decide how to reflect that on the page. This is the exact same shift you'd make for building a member section or store, though you'll probably need to store persistent data in sessions or local storage. Once you make the shift in how you think of “dynamic” interaction, it'll probably make Vue or React seem more powerful and lead to a more manageable set of problems to solve.

What Now?

One nice thing about JAMstack's patchwork is that its pieces can easily be broken into bite-sized nuggets.

Francesca's talk offered a pragmatic way forward for those of us that are new to a lot of these things: don't feel pressured to build a whole project with Gatsby if that's overly daunting. Instead, sprinkle a little Vue or React into a project as progressive enhancement.

Or whip up a serverless microservice by using a Lambda function to handle your image transforms or send email notifications when forms are submitted.

You might discover a surprise love for Lambda functions and like AWS again, become weirdly passionate about web components, or maybe get comfortable with enough different parts that building a headless Craft site seems more inevitable than daunting.

Whatever you do, make stuff and have fun!


  1. Symbolically.

  2. There are Twig JavaScript parsers, so technically you could write a static frontend with barebones Twig templates. But who wants to live like that?

  3. If, like me, you've mixed up Craft's GraphQL endpoint and Gridsome/Gatsby's GraphQL endpoint, remember that Craft is one source of content and Gridsome/Gatsby are designed to collect multiple sources of content and make them available in one (remarkably similar) GraphQL API.

***