RFC: Headless WP Issues & Struggles

[moonmeister]

We want to create a living list of WP things that are difficult to use in a Headless architecture. These will fall into roughly 3 categories.

• Things that WP makes hard because it's not designed to be headless or whatever
• Things that are just complicated to integrate but aren't particularly an issue with WP
• Community issues that aren't technical in nature

I'm sorry to the public who don't have access to some internal things. Feel free to comment on what you find hard in Headless WP. We'll put the final list here for all to see.

Community Issues

• Content: WP Developers don't know where to turn for HWP docs and support.

WP Issues

• Absolute URLs: WP Often embeds Absolute URLs in content that doesn't correctly point to a headless front-end
• Content Previews: WP Post Previews are broken cause WP is no longer in control of the front-end (ACF specifically is extra impossible)
• RSS Feeds: WP native RSS feeds are unusable by default in the front end (adding /rss for every route doesn't just work).
• Application Access: some APIs could/should be authenticated but are often left public due to lack of auth methods
• Short Codes: Don't process in API responses
• Opinionated Routing: Unlike most headless CMSes WP has opinions on how routing should work via Permalinks. Keeping this in sync with the JS front-end can be cumbersome. For example, creating a new post type using JS routing would require adding a new route to your front-end app. Relying on WP for routing means that a new Post Type can use an existing template.
• Content Styling: Blocks especially provide a lot of power to layout content, but getting the styles/JS into the front-end app proves difficult. (this could be an integration issue too but gonna put it here too as it bridges between the categories)

Integration Issues

• Menus: must be enabled by a theme and locations configured
• Lack of front-end control
  • SEO: SEO plugins don't embed the goods cause they can't control the frontend and sitemaps are on the backend
  • Forms: lack of clarity and easy plug-n-play forms
  • Comments: they're hard implement
  • Redirects: plugins SEO/standalone redirects can't redirect
  • WP Head/Footer: These concepts don't exist in headless
• Private Content: WP auth system lets plugins control content to specific users based on payment/membership/etc
• Media in Content: Media embedded in content often needs custom parsing to optimize with modern frameworks like NextImage. Is media slow-serving because it is not on specialty CDNs?
• Muli WP Sites: Whether Multisite or not managing a JS client working across multiple rest/graphql APIs can be difficult
• Caching: Due to the potentially multiple layers of caching (WP, GraphQL, Next.js/etc., network, browser), folks often find caching confusing, unclear, and incorrect. (RFC: Headless WP Issues & Struggles #8 (comment))
• Meta Queries: Users often reach for meta queries to do advanced when they shouldn't. RFC: Headless WP Issues & Struggles #8 (comment)

Working Docs

• David Notes
• Colin Notes
• Iona Notes
• Current Faust Features

[moonmeister]

Caching is an issue that comes up a lot too. It gets complicated. Though this isn't necessarily a WP issue as we tried to focus on here.

[moonmeister]

I was reminded of FacetWP today (David works on this) and how I regularly see folks leveraging meta queries/data to filter Custom Posts in headless. It's always a bad idea. Depending on the use case facets or WP Taxonomies are often better systems.

These are specific problems, but they generally relate to WP DB performance. ACF performance is also related: .
https://www.advancedcustomfields.com/resources/local-json/
https://www.acf-extended.com/features/modules/performance-mode
https://www.advancedcustomfields.com/resources/improving-acf-performance/
https://hookturn.io/downloads/acf-custom-database-tables/

[moonmeister]

This topic is addressed by some of the pain points above, but I wanted to reframe or frame it from the specific to the general.

I've often seen more security-conscious folks wanting to "lockdown" APIs or limit their publicness. WP Engine does some work here around rate-limiting IPs outside of our own node hosting to prevent DOS. This is still more that needs to be enabled on the OSS side. These users don't want/need full authentication only ways to limit abuse. Having public/private keys that permit their front ends to have access to things like introspection and persisted queries would go a long way.

Similarly, more documentation on how and when to lock down various aspects of the GraphQL API could benefit advanced and enterprise users.