Headless WP experiment I: Low-code dashboard approach

While thinking about good backend solutions for Astro, SvelteKit or Eleventy, I discovered that the new Gutenberg editor brought some interesting fresh opportunities. My current goal is to achieve a static frontend site, while providing a simple dashboard for content creators/clients in the backend (in a small dev team / freelancer setup).

The last months I spent researching robust and professional WordPress development workflows. In my mind, that always meant git, composer, deploy pipelines, continous integration etc. See e.g. bedrock.

Today I thought about a different approach: Handling everything in the WordPress dashboard. That means no git, no ftp/ssh, no CI/CD, no VScode. (The "real coding" with git only happens in the frontend repository with Astro, SvelteKit or 11ty, see end of the post.)

The main question in my head was: Why try to force WordPress into git when the whole technical approach and philosophy resists it?

So let's try this, just by clicking around in the dashboard ;-)

WPGraphQL

This would be my starting point, but you could also use the built-in REST API.

https://www.wpgraphql.com/
https://www.youtube.com/c/WPGraphQL

Custom Post Types UI

https://wordpress.org/plugins/custom-post-type-ui/

This is so standard that I would be interested in knowing why the WordPress team hasn't integrated this into core yet. It lets you add custom sections in your dashboard, e.g. if you want to store different restaurant locations:

The plugin officially supports WPGraphQL, so there is a checkbox ready to check:

Advanced Custom Fields (Pro $)

This is pretty well known as well, it lets you add custom data fields. The ACF plugin is fully compatible with Gutenberg editor, although the devs weren't happy with their new field area:

By default, our beloved metaboxes are pushed all the way to the bottom of the screen in an awkward attempt to retain compatibility. This placement feels very much like an afterthought from the Gutenberg developers and creates a disjointed editing experience for those of us (1+ million awesome ACF users) who extend the edit screens with extra fields.
https://www.advancedcustomfields.com/blog/the-state-of-acf-in-a-gutenberg-world/

The custom fields can be added to certain post types - e.g. our custom post type "restaurant locations":

Their (unfortunate) appearance in Gutenberg at the bottom:

Custom Fields created with ACF can be used in WPGraphQL, which let's you write nice frontend components with them. See https://www.wpgraphql.com/acf/ or this talk by WPGraphQL creator Jason Bahl:

Btw: Other approaches than Advanced Custom Fields

Advanced Custom Fields has 2+ million installs and is quite prominent. It was acquired last year by Delicious Brains. You should keep in mind that some important features are only available in pro (https://www.advancedcustomfields.com/pro/).

Of course, there are some other options as well:

https://wordpress.org/plugins/atlas-content-modeler/ (new)
https://de.wordpress.org/plugins/pods/
https://metabox.io/
https://carbonfields.net/
etc. etc. etc.

But you need to check if they are compatible with WPGraphQL (or the REST API of WordPress), see https://www.wpgraphql.com/extensions.

Restricting Gutenberg blocks via Code Snippets:

https://de.wordpress.org/plugins/code-snippets/

I personally always thought of inserting PHP via dashboard as bad practice, but WordPress ships the plugin files and theme files dashboard editor since the early days (The professional way of doing this would be in your child theme or plugin). So let's take advantage of it.

The main challenge in Headless WordPress in my opinion are the multiple Gutenberg blocks. If we want to keep it simple in the beginning, it is necessary to only start with a few blocks for editors. I found out about the allowed_block_types-hook on https://wp-content.co/restrict-gutenberg-blocks/:

function wpcc_allowed_block_types() {
    return array(
        'core/paragraph'
    );
}
add_filter( 'allowed_block_types', 'wpcc_allowed_block_types' );

This can be added via Code Snippets:

With this editors can only add the block paragraph:

Clicking "Browse All" also only reveals the paragraph block:

I need to find out where I can find a complete list of the block IDs though, adding the image block would be nice as well ;-) ;-)

Add custom blocks: Genesis Custom Blocks

https://www.studiopress.com/genesis-custom-blocks/

Genesis Custom Blocks lets you add blocks for editors/customers via Dashboard. I guess this can be really handy:

I haven't tested it yet, but they should just normally work with WPGraphQL if you just retrieve the rendered HTML.

To enable these custom blocks in Gutenberg (if you have restricted them with the method above), you need to add them to the allowed-hook as well. I opened a forum question about how the IDs are generated for these custom blocks (https://wordpress.org/support/topic/can-i-use-allowed_block_types_hook-with-this-plugin-restrict-blocks/)

btw: ACF has launched a similar feature as well, but coding is needed for it. https://www.advancedcustomfields.com/resources/blocks/

Backend permissions

One of the challenges I face with WordPress is good permission management. Editors should only see what they really need. With the restriction of Gutenberg blocks available we took the first step, there are also some permission plugins:

Headless Mode

This plugin locks down your normal website frontend for visitors and redirects them to the static frontend site if they visit your backend by accident.

What to do next?

We got our band together. Basically. One of the biggest advantages in my mind is the revision history system in WordPress and the nice dashboard experience.
I do have some questions left like multilanguage, SEO, Forms and other special cases. The missing direct preview in WordPress is also a topic worth researching, maybe it's possible to disable this completely (or there are ways to use your frontend site for previews).

But we could start now connecting a frontend framework like Astro via GraphQL - without using ftp/ssh once while setting this up. ;-)

To get into headless Wordpress and Astro, Buddy published a nice crash course recently:

And there is also a recent talk about SvelteKit:

I haven't watched one for Eleventy, but there are tutorials:

https://davedavies.dev/post/how-to-use-11ty-with-headless-wordpress/

Disclaimer up front: One of the hard parts is rendering the Gutenberg output in the frontend static site generator. They are different strategies with WPGraphQL, but the most simple one is retrieving and converting the HTML. You need to replace the internal links for example:

The good news: Gutenbergs standard styles can be added via npm (https://www.npmjs.com/package/@wordpress/base-styles).

Another strategy is receiving blocks via WPGraphQL and render them individually via wp-graphql-gutenberg, see e.g. https://www.youtube.com/watch?v=4Ybro_joKMk. Jason Bahl talked about this briefly at WPeDecode conference.https://developers.wpengine.com/ provides good information for headless Wordpress as well.

To be continued ...

Blog