How to create headless apps & awesome things with Gutenberg

Gutenberg WordPress Editor REST API

Gutenberg WordPress Editor REST API

Gutenberg, or the new WordPress editor is coming soon. Everyone is prospecting it will come later this year, 2018. There are many reasons to be excited.

Gutenberg introduces a New JavaScript Framework

While WordPress has always relied somewhat on Backbone as a JavaScript framework for certain parts of the admin (mainly the media uploader), Backbone is an old framework that not many adopt for new projects any longer. With Gutenberg and this new editor, WordPress is getting React which is a state of the art, new-age JavaScript framework that many larger companies are using to build our their web and even native apps.

This is great, WordPress is moving forward, however this is just to build out the actual editor. So building the new blocks is great, you get to use the latest in technology like React, webpack, etc to build out your blocks and thus creating a customized UI within the new editor to meet the needs for your team that uses WordPress.

A New Way to Write Content

For users, bloggers, editorial teams, etc. Gutenberg is a new way to think about how to write content. Instead of a wall of text, content will be built using “blocks”. Like Legos, each block will be unique whether it is a different type of block, or just different data. I’m writing this blog post pre-Gutenberg, or using the current “classic” editor that we are all familiar with and love. So while I’m using the 1 big area to write and put in headings, each paragraph or heading would be a “block”.

This isn’t a “What is Gutenberg” article, so if you want to get more familiar with what Gutenberg is, there are many great resources to learn including the Gutenberg handbook.

The Data

In order to keep everything backwards compatible so upgrading to the WordPress version that has Gutenberg as the new editor won’t break 30% of the Internet, any time a block is saved it creates HTML markup of the output and stores that in as “the content”. If you are a developer or know some of the code for WordPress templating you know that the_content(); is a function you have to run to get the output of the big WYSIWYG box. There are ways to manipulate that with plugins like PODS, or you can remove it and add a plugin like Advanced Custom Fields to make the data for that post very custom, however out of the box WordPress will need the_content(); to show what is written in the editor.

Here is an example post I created and the output that gets stored into the database:
In the screenshot you’ll see that each block starts with a HTML comment like <wp:paragraph> signifying that a new paragraph block is starting. This is great for the output and makes it so themes don’t really need to do much to be compatible with Gutenberg.

However for me, that left a lot to be desired. When I saw Gutenberg the first time, all I could think about was how lovely it would be to have a nice array of data for each block. So I could take the paragraph content for that paragraph block and do what I wish with it in my theme, or even a headless application. However by default, the REST API doesn’t give you that kind of data, as when the post is saved (via REST API) the data has already been serialized to look like the above data.

A standalone plugin

After speaking with quite a few people at WordCamp San Diego 2018, I knew I was not the only one to feel “weird” about the way data is stored and the potential there is if the data was stored as a unique array, so I wanted to see how hard it would be to implement that.

So I built the Gutenberg Object Plugin – which basically hooks in to the save event, and then takes each block’s data, filters it as needed, then stores it in a unique table. As part of the plugin I also created custom endpoints just for Gutenberg data as well as an addition to the normal POST response. Now you can get a custom editor_blocks array as part of your normal REST API response.

Why A Custom Table?

I’m not 100% sold on this approach, but I do want to eventually do some performance testing. Once I have just the raw data of the post content, do I really need anything else? If I can make a performant call to the DB that doesn’t also make other calls like post_meta calls, etc. could that load the page or return the results faster? Testing still needs to be done to confirm any of this, and to find any other possible improvements with a custom table.

The other choice was to create a new field in the wp_posts table. I kind of wish that had been the case OTB and Gutenberg just did that for those who can refactor and not care about backwards compatibility. However modifying a table that a site already uses is a lot more sketchy IMO, and I’ve seen plugins that do it and it is scary when you have LOTS of posts.

What can be built?

If you are familiar with building anything Headless with WordPress, you’ll know that this means a lot. You can now create a very customized UI based on the block data, vs. having to parse through a string of HTML comments.

In most cases, this is not necessary as a theme or plugin will just use the_content() and what it spits out to show the content of the post or page. However adding this level of data availability means that if you share your data across to another platform or app, it can digest it how it pleases vs. as a string.


There are many ways to use the data, even if it isn’t a headless app. I’m going to work on some examples and create some followup posts in the next few weeks, but for now here is a NON-headless way to look at how an array of data can help you create way more modular code for your theme:


  1. Wow this is great! We’ve been using typerocket internally as the page builder in our headless wp/next.js setup and am using a similar method of passing block data to the wp rest api. We’ve recently been looking at dropping typerocket in favor of Gutenburg in time for the core rollout and this plugin is a HUGE help. Thanks!

Comments are closed.