WordExpress Project Experiments with Bringing GraphQL to WordPress

In 2012, when Facebook started re-architecting its HTML5-driven mobile applications to be native iOS or Android apps, the company invented GraphQL. This new open source query language is being heralded as a direct replacement for REST. GraphQL provides a more efficient way of supporting the volume of interaction that takes place across Facebook’s apps every day, but it is database agnostic and built to be used beyond Facebook.

Although GraphQL is still relatively new, big companies like Intuit, Coursera, Pinterest, and Shopify are using it in production. Last month GitHub announced GraphQL support for its GitHub API to answer some of the drawbacks of its REST architecture.

GraphQL offers a new way of structuring communication from the client to the server that makes fetching data more efficient. In his article GraphQL in the age of REST APIs, Petr Bela summarizes the difference between the two types of architecture:

GraphQL’s power comes from a simple idea — instead of defining the structure of responses on the server, the flexibility is given to the client. Each request specifies what fields and relationships it wants to get back, and GraphQL will construct a response tailored for this particular request. The benefit: only one round-trip is needed to fetch all the complex data that might otherwise span multiple REST endpoints, and at the same time only return the data that are actually needed and nothing more.

Last month Facebook announced that GraphQL is exiting the “technical preview” stage and is now production ready. It has been implemented in many different programming languages and has already been adopted by companies that wanted a more efficient way of accessing data.

WordExpress Brings GraphQL to WordPress

Ramsay Lanier, a JavaScript front-end developer who works at nclud in Washington, D.C., has created a GraphQL-powered WordPress implementation called WordExpress. Lanier is not a fan of PHP and doesn’t like working with the loop or templates, all the things that have historically comprised the bulk of WordPress front-end development. He created WordExpress as a Node.js application with the goal of replacing PHP with JavaScript for the presentational side of WordPress. It uses Express on the backend and React components on the frontend. GraphQL sits between the two to retrieve data from the WordPress database.

“When I originally started out with the idea for WordExpress, I wanted to use the REST API, but I found the existing endpoints were not what I wanted,” Lanier said. “I would end up having to write a bunch of custom endpoints and chaining calls together. So I thought I’d give GraphQL a try.”

He found that GraphQL is more efficient than REST, because it reduces round trips to the server, allowing developers to focus on what data the client really needs. Lanier highlighted the benefits as they pertain to WordPress sites:

With GraphQL, the client determines the exact data it needs via a GraphQL query. The GraphQL query has a custom resolving function that determines how that data is retrieved. In that function, you can even hit multiple databases. For example, with WordPress you have a MySQL database, but you might also have a Mongo database for an application that stores other data that doesn’t need to be relational. In the GraphQL resolving function, you can make calls to retrieve data from both databases and send it back to the client in one server round trip.

WordExpress, in its current form, is a good starting place for building JavaScript-powered applications that use WordPress for administration. Lanier said this development setup allows him to create components of web pages and applications much more easily than with PHP templates.

“With React, each component contains not just the markup to display stuff, but the styling for that component, the data the it requires to work, and any interaction logic as well – all in one or two files,” he said.

WordExpress’ Current Challenges: Plugin Compatibility and Server-Side Rendering

Despite all the exciting benefits of more efficient queries and the possibility of a JavaScript-powered frontend, the WordExpress project has a number of serious challenges that would make it troublesome to use in production beyond a simple blog installation. It is not compatible with the vast majority of WordPress plugins, as most are written in PHP.

“Essentially, I’ve replaced the entire front end, which means any plugins that affect the front end won’t do anything,” Lanier said. “However, you can certainly leverage existing plugins that affect the admin side of things (like Advanced Custom Fields or the AWS S3 plugin). Anything that manipulates how WordPress data is stored in MySQL is still usable – you just need to modify your GraphQL schema and queries to work with them.”

The other major challenge is getting server-side rendering to work, which is required for handling things like SEO and meta tags. Apollostack, which WordExpress uses to fetch the data and deliver it to the React components, has only recently added early support for auto server-side rendering.

“I’ve switched from using Facebook’s Relay to ApolloStack,” Lanier said. “Both are pretty new technologies and I’m not sure if either has really figured out how to handle Server Side rendering very well. I haven’t looked into it in a few months, and things have been moving pretty quickly with ApolloStack, so they might have figured it out by now.”

For now, WordExpress is just a proof-of-concept and Lanier said he doesn’t have plans to try to support existing plugins. Given that WordExpress cannot currently leverage themes and plugins, some of the best parts of the WordPress ecosystem, Lanier said developers who use this stack are probably more interested in preserving the power of the admin side of WordPress.

“I love the WordPress admin,” he said. “It’s very powerful and easy to use to manage content. WordExpress would be a starting point for any JavaScript developer that wants to build WordPress applications using just JavaScript.”

Lanier’s goal with WordExpress is to turn it into an npm package that can be reused in a variety of different React projects. He has already published two WordExpress npm packages that work together: wordexpress-schema (handles the GraphQL schema and connection settings) and wordexpress-components (currently houses the first two components, WordExpressPage and WordExpressMenu). Since the project is built on Node.js, developers can make use of any npm package they want, a consolation for limited plugin compatibility.

GraphQL and the WP REST API

Many of those who are predicting that GraphQL will become a direct replacement for REST are also of the opinion that the two can co-exist. In fact, Facebook has recently written a guide for wrapping a REST API in GraphQL.

“It’s likely that if GraphQL proves to be effective, it will co-exist with REST APIs,” said Petr Bela. “Some APIs will use REST, some will use GraphQL. Some might support both.” He predicts that it would take the industry years, perhaps even a decade, to completely switch from REST to GraphQL.

Lanier’s WordExpress, which recently passed 1,000 stars on GitHub, is currently the only open source project that is publicly exploring a GraphQL-powered implementation of WordPress. A cursory search on GitHub reveals that many others are experimenting with similar setups. Fortunately, GraphQL doesn’t require any changes to WordPress core to enable sites to use the API for querying the database.

Lanier said he appreciates the work of those who are trying to get the WP REST API merged into core and doesn’t see GraphQL implementations as a threat to that.

“I think the work they are doing with the REST API is good stuff,” he said. “They definitely needed to take that step. REST has been around for a long time – GraphQL is still pretty new, so it makes sense to go the REST route. Also, a lot more people know how to use it. The nice thing about GraphQL is that you can use it to wrap a REST API, so they can both co-exist.”

The possibility of WordExpress going beyond a simple proof-of-concept depends on feedback from the community. Lanier said developers are demonstrating interest in WordExpress by forking it and asking questions.

“People are using it and playing with and (hopefully) making it their own,” he said. “I think the interest is there. To make it really feasible, though, you need a whole team of developers making it a top notch option.”

Lanier recently took a new job where he’s using React 100% and hasn’t had the opportunity to use WordPress for a little while but said he’s open to exploring collaboration to make WordExpress production ready.

“If people were really interested and wanted to get together to grow it into a feasible solution, I would 100% be involved in that,” he said.

Developers who want want to test it out and start developing with WordExpress will need a basic understanding of how React works. Lanier has written detailed documentation of how the GraphQL implementation is set up and how to extend GraphQL queries and database models. The WordExpress.io site is a live demo of the code, which you can find on GitHub.