Fellow developers, who have used Headless WordPress with GatsbyJS on one of your latest projects what were the major challenges you encountered and how did you go about solving it?

In this post, I will try to share my experience working on a recent project with this stack.

Gutenberg Editor

The Gutenberg editor is a new editor developed by the WordPress team which was released in version 5 of WordPress. You can get a feel of this editor by trying it out on this website setup by Tom J Nowell and the official Gutenberg project here. I realized that this is exactly what I need for my users' needs

Rendering generated content on Gatsby

The very basic way to render content coming from WordPress is this way

return (<div
   dangerouslySetInnerHTML={{
      __html: data.WordPressPage.content
   }}
/>)

How will you be able to render an image gallery which opens a modal when you click on one of the images if the markup generated by WordPress is something like this?

<div class="gallery">
  <img src="https://placekitten.com/200/300" />
  <img src="https://placekitten.com/g/200/300" />
</div>

I have used html-react-parser and transformed this HTML string into a component.

Check the code below. Note that the custom Gallery component I implemented here doesn't have that modal I talked about earlier. But since its already a React component, we can do just about anything.

Style of preview should match rendered Gatsby content

Here we should at least sync the styles of the preview with the rendered content.

Either we repurpose an existing block or create our own custom blocks so that it will look exactly the same on the editor and the site. FYI, blocks are written in React.

I created overrides of the block styles at the theme level and made sure the same is shown on Gatsby. If we don't do this then the editor is not a WYSIWYG anymore.

The major challenge here is, the user can install some new blocks then we have to write support code and make sure it doesn't break the others.

ACF on Gutenberg Editor Page

At first, you'll think that your Advanced Custom Fields are broken if you have placed fields below the title. With Gutenberg activated, ACF will only show if you place it below the content.

I haven't tried placing it on the sidebar but I am guessing it should work too.

Publishing Content

I have chosen Netlify to host the content generated by Gatsby. It's fast and reliable.

Instant Feeback

I understand users need a way to validate what they have just published instantly.

I have explored this plugin to solve this issue. During save, this will call a build hook on Netlify to trigger the deployment.

Make sure you have something set for both Production and Staging, else the plugin will not work.

It will still take some time to reflect changes on the actual site.

Gatsby Cache

There are some instances where I have to clear the cache just to see the changes that I have done.

I am not sure, what is causing this. It doesn't happen too often though. There is already an open issue at Gatsby.

I could explore server-side rendering using Next.js but I really like the Gatsby workflow.

Global Settings

There are some things I wanted for the user to be able to configure like the following: footer text, company address, email, etc.

I haven't tried to look into solutions yet. I am interested in how you guys will approach this.

Forms

I used the form submission API provided by Netlify. It was not a straightforward journey.

I had everything correctly setup by following this documentation yet I was not receiving any submissions.

You should put this in mind. Do not try to test the form with your usual testing instincts. Netlify will automatically block form submissions if it looks like spam without you even knowing. You should test it like filling out a real form not the garbled test strings from muscle memory.

I wish there was a way on Netlify forms to at least see how many messages were blocked or even disable the filtering on development mode.

My users wanted to have the messages straight to their emails so I integrated with Zapier.

Pages on Gatsby

I am creating pages in Gatsby using the gatsby-node.js but there are specific pages I want to explicitly create because they have specific styling and stuff.

For these pages, I query the WordPress API via the page id. These page ids I also exclude on the auto-creation at gatsby-node.js. This is done to make sure that the page will work even though the title or slug is changed.

However, if a slug is changed, there will be no route to handle it on Gatsby. Maybe, I am trying to create a non-issue here but this is worth mentioning.

Conclusion

If you are a frontend developer who hasn't really done any react or WordPress development in the past. This is something I think you should at least try.

This workflow is really something that I would like to 'perfect' it allows us to create anything out of a WordPress API.

I hope these challenges would help you decide if this is something for you. I do expect to get some feedback from the community as well about the challenges you encountered with this stack and how you solved or plan to solve it.