At our January meetup, Clem Omotosho kicked off the first of three hands-on workshops exploring “headless” — or more precisely, decoupled — WordPress. Last night, the February meetup dug a little deeper, and in March, we’ll wrap up.
If you want to follow along and build your own decoupled WordPress app in a local environment, start with Clem’s five-step tutorial, which features a Marvel-themed set of trading cards as the content pulled from WordPress into a Svelte+TypeScript front end.
Wait — What even is “Headless WordPress?”
Let’s back up, because “headless” is one of those terms that sounds weirder than it is.
Traditionally, WordPress handles everything in one place: it stores your content, manages users and data, and renders the HTML pages your visitors see. That all-in-one approach is called a monolithic architecture. WordPress has been this way since day one — your theme is the “head,” generating the full visual front end or presentation layer.
That said, WordPress has no single unified “Theme API” — it has many plethoras of APIs. As a result, there’s never been just one way to build a theme. WordPress is a very front-end agnostic animal, so it is easy to take its head off, and it won’t care!
Headless means exactly that: you cut the head off. The WordPress back end keeps doing what it does best: CRUD (Create, Read, Update, Delete) functions. Headless WP still stores and manages content with its database, the REST API, and other interfaces — but it stops generating the front end. No theme rendering happens in production. Instead, a separate tooling system (in Clem’s workshops, a “meta-framework” called SvelteKit) builds everything the visitor sees in runtime JavaScript. So the front end is rendered on the server side and interacts with WordPress via API to push and pull what it needs from/to the WordPress database.
(SvelteKit uses Vite as its build tool and local development server. It can be deployed to various JavaScript runtime environments — such as Node.js, Deno, or edge platforms — through adapters.)
This separation is what “decoupled” describes more precisely: the content back end and the presentation front end are now independent, fully server-side systems (two separate stacks) that communicate through WordPress APIs, either REST or GraphQL. In Clem’s workshops, we’re using the WordPress implementation of GraphQL: WP GraphQL.
All these technologies I’ve mentioned so far are, like WordPress, free and open source software. 😀
Why go “headless?”
Decoupling opens up some real flexibility:
- Front-end freedom. Have as many different front-ends as you like, or none at all. Your content can flow to a website, a mobile app, a kiosk, a voice assistant — whatever. The WordPress back end doesn’t care what consumes it. This is basic for omnichannel marketing and e-commerce.
- Independent scaling. Got a traffic spike on the front end? Scale it without touching the back end. Need to swap your JS framework someday? Your content layer stays put.
- Specialized integrations. Plugging in dedicated services for search, e-commerce, or AI becomes cleaner when you’re already thinking in APIs and microservices rather than monolithic plugins.
- Modern developer experience. JavaScript frameworks like React, Next.js, Nuxt, and SvelteKit have rich ecosystems and tooling that WordPress themes simply can’t match.
There’s also a related concept worth knowing: API-first (or “native headless”) platforms that were born without a head. They’re pure content repositories with no theme engine at all. WordPress going headless is a choice; for those platforms, it’s intrinsic to their architecture.
It should go without saying that API strategy now means AI strategy. In the near future, AI tools that can talk to a database may be all the front-end some data stores may need, and their purely internal, back-end capabilities will become extremely valuable for management and insight.
Think about it: OpenClaw + WordPress: what actually happens 🦞🔥
Reasons to Keep Your Head: The Drawbacks of Being Decoupled
Of course, there are also technical and real-world business reasons why a decoupled architecture or decapitated WordPress can be a bad idea. Headless has been almost stereotypically a trend for younger front-end developers who want to work on the latest and greatest JS-based design frameworks. The voice of age, experience, and business owners (including agencies and their clients) offers the following cautions, as you’ve heard me do at the meetup!
- Impaired Content Creator Experience. It can be a bad tradeoff if you get slower, more friction-heavy publishing workflows that frustrate creators, designers, and marketing teams. The headless approach often solves problems that do not exist, driven by developer preference rather than core business or operational needs.
- Heightened Development and Maintenance Burdens. Now you’re maintaining two (or more) codebases for the back-end and the front-end apps. Front-end routing, authentication, form handling, comments, search — it all has to be rebuilt from scratch. Testing fragmentation across decoupled layers is real, frustrating, and expensive. The deployment pipeline complexity increases significantly.
- Degraded Performance. The “headless is faster” claim often doesn’t hold up — a well-cached WordPress site with a good host can outperform a poorly optimized JS front end hitting an API. Added network latency from API round-trips, especially with multiple REST or GraphQL calls per page load, can make things sloooow. Time to First Byte can actually increase if you’re doing server-side rendering (SSR) that fetches from a remote API. Don’t forget cold start penalties on serverless/edge deployments.
- SEO and Functionality Gaps. SEO requires careful handling, so SSR or static generation becomes mandatory, not optional. Native WordPress features like RSS, sitemaps, redirects, and search need to be re-implemented or proxied — and then maintained. (There are many other examples.) Accessibility can regress if the front-end team isn’t prioritizing it.
- The Complexity Tax. That’s what these (and other) drawbacks all add up to — a tax for the complexity of a less centralized system that inevitably drives up overhead and the total cost of ownership and maintenance.
Overall, a lot more work and costs with a decoupled, decentralized, highly customized system.
- Bottom Line and Organizational Costs. A decoupled system requires specialized JavaScript developers in addition to another team of experts handling the back end, whether that is WordPress or something else. Hosting costs often go up since you’re running infrastructure for both the CMS and the front-end app.
“There’s a hot new JS framework every five minutes, but six months from now, will your SvelteKit/Next.js/Nuxt front end age as gracefully as traditional, tried and true, sustainable “legacy” codebases?”</oldmanrant>✊🏻👴🏻
These are critical tradeoffs worth thinking through. Leave your thoughts in the comments here, and bring them to the next meetup!
Where We Are in the Workshop Series
Here’s the roadmap for Clem’s three-part series:
- Session 1 (January — done!) Introduction to headless architecture + setting up SvelteKit in your local (integrated) development environment (IDE).
We dug deeply into the fast-evolving and free Studio app from Automattic, which has its own unique implementation of SQLite, WP-CLI, and an AI assistant. If you missed January’s session, follow Clem’s tutorial to set up your local development environment and be ready to connect the pieces next time. - Session 2 (February — done!) Connecting SvelteKit to WordPress via the API so your front-end can actually pull and display content.
We debugged some Windows and macOS issues to get up and running, and then explored Clem’s code while using various LLM tools baked into our IDEs, like VS Code and two new forks of it, Antigravity and Codex. You’ll notice there is a “Rating” field mentioned in the front-end code and GraphQL requests, but no such metadata exists in the content. That led me to create a more interactive version of the cards that writes their rating to the postmeta. Looking closely at how authentication and database writes work with GraphQL helped me debug another project.
Session 3 (coming soon): Continuing to build out the full headless application. Do it your way! Please share your work and discoveries in the comments here and at the March meetup.
YEG WP Meetup meets monthly in Edmonton. Join us →
Leave a Reply