DE{CODE}: Headless 101 for WordPress Developers
Headless development can be more powerful and even more fun than traditional WordPress development. However, with so many new choices in this emerging stack, what’s the best way to get started?
This workshop will walk builders through installing and optimizing a WordPress project for headless, all the way to templating your first page in a decoupled frontend.
Session Slides
Full Text Transcript
GRACE ERIXON: Welcome to Headless 101 for WordPress Developers. My name is Grace Erixon, and I am an associate developer advocate here at WP Engine. Joining me is Steve from Haus. Today, we are going to give you a quick introduction to what headless WordPress is, and how you can get started using it.
So in order to understand what a headless WordPress website architecture is, it’s important to make sure that we’re all on the same page about what a traditional WordPress architecture looks like. Traditionally, a CMS such as WordPress would handle both the front end and the back end of a website.
In a traditional architecture, the publisher creates and manages content such as blog posts and pages inside of WordPress. The developer writes code to control how the site looks and functions using PHP and WordPress’s theme API. Then WordPress generates the HTML page that is sent to the visitor.
In this coupled CMS architecture, WordPress provides the content management capabilities to publishers. And it also is responsible for serving HTML pages to website visitors. A headless CMS uses a decoupled architecture where the front end and the back end are managed separately. In a headless architecture, the publisher still creates and manages content in WordPress, the same as in a traditional WordPress architecture.
The developer writes code to control how the site looks and functions in JavaScript as well as using WPGraphQL or the REST API to pull data out of WordPress. A framework such as Faust.js, Next.js, Nuxt.js or SvelteKit is often used to power this frontend application. Then the front end JavaScript application generates and serves the HTML pages that are sent to the website visitor.
Unlike in a traditional architecture, WordPress is no longer responsible for generating HTML pages. So the interaction to exchange content between the WordPress back end and the front end JavaScript application happens through the API layer. The two options for the API layer are the WordPress REST API or WPGraphQL.
The REST API comes bundled with WordPress. However, the data access pattern that it requires can be slow because REST requires each resource to have its own end point. For example, it would require multiple round trips to reconstruct a fully modeled post. If you wanted to get a post’s content, author, and category, it would require three separate API calls.
In contrast, WPGraphQL allows us to ask for a post’s content, author, and category all in one request. Because of this, WPGraphQL is our preferred API layer. WPGraphQL is a free plugin that provides an extendable GraphQL schema and API for your WordPress site. WPGraphQL is faster than the REST API because it gets the exact data that is asked for, and results in fewer functions executing through query optimization, less data downloading, more efficient data loading, and multiple resources being included in a single request.
A headless architecture gives developers the freedom to choose from any front end technology stack with JavaScript frameworks being the most popular. Some of the most popular front end JavaScript frameworks include React, Vue.js, and Svelte. New frameworks are being released all the time, so this list is nowhere near comprehensive.
Many of these JavaScript frameworks are used in conjunction with meta frameworks that add solutions for things like routing, server-side rendering, and more. React is used in conjunction with Next.js, Vue.js is used in conjunction with Nuxt.js, and Svelte is used in conjunction with SvelteKit. Gatsby is another popular meta framework.
WP Engine has developed Faust.js, a JavaScript framework built on top of React and Next.js. Faust was created specifically to support headless WordPress web applications. It supports authentication and post previews out of the box, provides convenient built-in React hooks for accessing WordPress data, and more.
So we’ve talked about what a headless WordPress architecture means and the kinds of technology you would use. But let’s touch quickly on why you would even choose headless. WordPress itself is a heavy CMS, and it uses PHP, which is not a fast language. Headless WordPress uses foster languages through JavaScript and loads only the necessary files through API calls. It’s much more lightweight, so your site will load faster.
Headless WordPress also minimizes the risk to your content since your data lives separate from your front end delivery. It’s less exposed to web attacks. And the main benefit is that headless WordPress architecture allows publishers to continue to benefit from the great publishing experience that WordPress provides while also allowing developers and website visitors to take advantage of the technical capabilities that modern JavaScript applications bring to the table.
Now, let’s dig into the code of a real headless site. I have pre-recorded a walkthrough of the new Atlas Blueprints headless WordPress site. The new Blueprints feature in Atlas provides a really easy way to get a complete headless WordPress site up and running. They come with starter code, plugins, content models, and page structure to get your app off the ground faster.
So let’s create a new Blueprint site so we can dive into the code. From inside of WP Engine’s dashboard, we’ll go to Atlas. Click Create App. Select Start with Blueprint. And then we’re going to select which blueprint we want to use. I’m going to choose the portfolio blueprint.
Then you’ll connect your WP Engine account to your GitHub account, and clone that blueprint into a new repository. This will take a couple of seconds to build. Finally, you’ll just select the name of the repository you just created, the region that you’re located closest to, and then you click Create App.
Now, if you click on the Atlas URL, we can check out what our headless WordPress site looks like. We’re specifically interested in the Posts page. As you can see, the site is pulling in all of the most recent posts into this Our Blog page. And each post also has its own individual view page. But where is all this data coming from?
If we go back to the WP Engine dashboard, we’ll see a button for WP Admin. There’s the back end for our headless WordPress site. If I click on Posts, you’ll see the same list as the web app was pulling in. Now, we can open up the GitHub repository that our Blueprint was cloned into. And let’s clone that repo down to our local environment.
Then I’m going to open this repo in Visual Studio Code, my favorite code editor. Drilling into the project directory, the file for the blog page can be found at SRC, pages, posts, Index.js. This project is built using React, Next.js, Faust.js, and WPGraphQL. If you aren’t familiar with React or even JavaScript, then this could look confusing at first.
In the first section, the file is just importing things that it needs from internal and external sources. The second section that defines the post nodes prepass fields is where every piece of data that we need is listed. Running this through prepass ensures that the data is there when we need it and no cascading requests occur.
Then we have the page function. At first, it’s just collecting the data that we need into a few different variables, namely, the general settings and a paginated list of posts. The tags inside of the return statement is the code that will be visually rendered on the web page. First, we have the component for the header. Then, inside of this main component, we have an entry header component, and that is what displays the big title that says Latest Posts at the top of the page.
Finally, we get to the post component, which accepts the paginated list of posts as a parameter. Let’s look at what the post component does with this information. Here it is looping through each post contained in the list of posts that it received. For each post, it displays the card-like view on the latest post’s page. This first consists of a featured image component wrapped in a link to the individual blog post’s page, a heading of the post’s title, and a post info component consisting of the date and author of the post.
Back to the Index.js file that displays all of the posts, we finish this out by displaying the Load More component at the bottom of the page to retrieve more posts if requested and a footer. The last function, getStaticProps, is a Next.js static site generation function that tells it to pre-render this page at build time using the props returned by the function. And that’s it.
Thanks to Blueprints for handling the Headless setup for us. It was straightforward to break down what goes into the post page to get data from the WordPress backend using WPGraphQL and to display the posts using React components. Thanks for tuning in. You can find me on Twitter @graceerixon.
Check out developers.wpengine.com for more content around Headless WordPress. We have a tutorial on how to build your first Headless WordPress site from scratch using Faust.js, and we’re working on a Headless 101 series of content right now. You can get all of the tools that Atlas offers if you sign up for a free Sandbox account. Now I’ll pass it off to Steve to talk more about why Haus chose Headless WordPress for their leoburnett.com project.
STEVE SCAVO: Thanks, Grace. Hi, I’m Steve Scavo, CTO at Haus. We are a creative technology studio and agency out of Los Angeles, California. This talk is appropriately titled Headless 101 for WordPress Developers. And coming clean, I’m not a WordPress developer by trade, but I think that’s part of the beauty of a headless architecture.
So we could have easily have called this Headless 101 for non-WordPress developers that need to leverage WordPress. That might have been just as apt title. That’s what’s beautiful about headless. It’s a win a win-win from all sides, as you’ll see.
So why headless? There are so many high level reasons that we could speak of, but I think that kind of talking about real production examples and real world examples of when it shines is really helpful. And I’d like to showcase a project that we did for Leo Burnett using headless under a headless architecture. For context, Leo Burnett is a storied advertising agency out of Chicago, but they have many offices worldwide and globally. So they have a lot of content, a lot of work.
The old site was operating on a single WordPress theme. It was really fragmented, sort of slow, didn’t perform well. It was difficult to update, and it didn’t quite exhibit the sort of cachet and the branding that Leo Burnett wanted to convey. So that’s what we went to work with from a design perspective. And we chose headless to really modernize their stack.
We just wanted it to feel alive and fresh and have that sort of capability that we need to have to really put together a wonderful user experience and UI. We wanted to increase their publishing power. We wanted to increase the cadence by which they can publish content. We wanted to reestablish the brand identity and have a UI and an interaction, the feel to the website that really kind of exuded Leo Burnett and all these little touches and sort of editorial and typographic and interaction points that they wanted to convey.
And we wanted to prepare the code base and the website for the future. We didn’t just want the site to be relevant for the next 12 months. We want it to be relevant for the next decade, perhaps. And I think that this headless architecture, this headless stack really sort of does that.
So one of the initial problems with headless is that there’s always a lot of decisions around hosting and deployment and infrastructure, and it’s always been a huge pain point. So these stack decisions have always been left up to the developer. And you hunt around and you ideate around, OK, what third party, maybe CI/CD application do you need to use? Are we going to host this on AWS? How do we do that? What services? And then you kind of implement these sort of potentially– these ad hoc solutions around that flow.
Well, Atlas and WordPress Engine Atlas platform really solves this. This is where it comes into play. We chose to go with Atlas for all those reasons, and they have this managed service infrastructure. They standardize the CI/CD pipeline. You don’t really have to think about it.
There’s data migrations between the environments that are essentially down to a one click flow. That’s always historically been a big problem with moving from QA to staging to production. Essentially WordPress Engine and the Atlas platform has brought that down to a single click.
And then there’s just this fatigue around microservices and DevOps. There’s just a heavy cognitive load of how much you have to think about and support and be aware of that as a developer and keep it up and running. These are all things that the Atlas platform really takes out of your hand and solves in a beneficial way.
So let’s talk about some of the dynamics that I think headless really promotes and it really emphasizes. The first pillar here– there’s three of them. The first pillar is developer experience. It allows us to choose the right tool for the job. And when I say us, I mean developers.
It allows us to choose a stack that we want to write code in. And that’s, for us, that’s at Haus, that’s Next.js and React. Next.js is just a wonderful framework around some really nice conventions for routing and performance and application architecture. And we also wanted to implement a design system, and not just a visual design system but a codified design system. This is something that keeps our application consistent, tested, beautiful.
The interactions are consistent. It allows us to build new pages and features into that ecosystem going forward as well, and keep that and maintain that consistency. It also allows us to write declarative expressive code and React endorses that as a library. But we also believe in that style of writing as a team. It allows us to choose that stack for us on the front end, whereas maybe a traditional theme-based WordPress site, we don’t really have that same luxury.
We also need a lot of creative headroom. You can see when you visit leoburnett.com, there’s beautiful page transitions. There are– we’re not bound to the traditional WordPress stack on how things should be rendered. WordPress isn’t in charge of rendering the frontend anymore.
Our headroom is just virtually limitless. We can choose our animation libraries. We can choose the way that our components interact with each other. It’s a huge benefit on the DX side.
The admin experience is elevated, and I think that we’ve optimized that because we never moved away from their old familiarity. There’s no backend cutover. We went from WordPress to WordPress. We didn’t have to export data and sort of write scripts to move into another proprietary system. So familiarity is huge. We wanted to maintain that sort of flow for the current admins of leoburnett.com.
Adoption and documentation– if you spend five minutes on the web, you have probably touched a WordPress back end, and that simply can’t be overstated. Leo Burnett also has a lot of very specific content points and custom fields. WordPress offers that and gives you that power, but we were able to implement Advanced Custom Fields plugin, which is a really nice convention around adjusting the admin UI to make it really friendly and usable. So that was a win on the admin experience.
Now, of course the third pillar is user experience. It’s what really matters. Users, I think much like how we believe web applications at Haus should feel like native applications, there should be no drop-off. I think users really appreciate that as well.
They are seamless. They’re responsive. They just feel good. And I think we wanted Leo Burnett and all of our applications to feel that way. Being able to choose the stack we want on the front end allows us to do that.
Native apps are inherently decoupled from their back end content infrastructures, and so are our web apps. And this is what Atlas promotes. This is what headless architecture in general promotes. It also promotes performance. We can universally render our UI. That means the initial load is on the server side. And after that, the client takes over.
There’s a lot of benefits here. One is that it makes search engines happy. They’re server side content. It’s fast. It also allows us to virtually instantaneously pre-render the next page and make those requests based upon what’s in the viewport a single time.
For Leo Burnett, in terms of the content API that we chose to consume, we set up a GraphQL endpoint. That means that there are leaner payloads coming back. We’re explicitly defining exactly the content that we need. There’s less hydration after that server side render into the client side render.
That’s less code coming over the wire, less response, faster response times. It’s definitely a win, and I would suggest that if you’re going to move into an Atlas workflow or a headless workflow, that you take a hard look at using the GraphQL API versus maybe something like a REST API.
And from a user’s perspective, they’re seeing fresh, timely content. This is a publishing flow that is optimized for previewing content. It’s optimized for quick content fetches on the staging and previews side and then promoting that into production. The admins at Leo Burnett are extremely happy with how easy it is to update content, and that makes users happy.
What’s the outcome? This is just kind of to roll it all up. It’s inspired developers, productive admins, and happy users. This is the triad and the hope that I think all web dev teams really strive for.
When developers are inspired, they’re using an optimized set of tools. It just feels good. They’re happy. They write better code.
Admins know that they’re producing content into a beautiful ecosystem. It’s fast. It ships quickly. And users are seeing that updated content, and they’re experiencing a modern, beautiful, well-functioning, optimized front end.
I think to wrap it up– just a few final thoughts that I would love for you to keep in mind. I think that the brief, per se, always has missing language. I think that too often we talk only about, hey, build me a beautiful website. Build me an amazing website. I want it to look and feel– and we’ve run all these reviews with clients.
And everyone gets excited, and then V1 comes, and it’s launched. And then the people that need to take over that website are like, you handed me a mess. How do I take care of this? Is this some ad hoc flow that you conceived of?
You don’t want to build a beautiful website and hand over a burden. We take a lot of pride here at Haus to not do that. And I think what’s wonderful about Atlas and Atlas as a platform is that it solves that.
It gives you the confidence that you’re shipping an ecosystem and a web publishing system that actually makes sense from an infrastructure standpoint and a code deployment standpoint. It gives documented proof to the IT team and the engineering team or the marketing team that you know what you’re doing and that they’re in good hands now with this new website that you built for them.
Because remember, we’re not just building a website. We’re establishing a content publishing system, and that’s critical to understand and to acknowledge from day one. And again, this is where Atlas comes into play.
So I hope that little tidbit kind of helps you strategically conceive of your headless stack going forward. If that’s the direction that you want to take, I highly encourage you take a look at Atlas. I hope you enjoyed the session, and thank you very much.
