ustwo: An Open Source Example of a React-Powered WordPress Site

If you’re looking for a real-world example of the WordPress REST API with code that you can dig into, the new ustwo.com website is open source on GitHub. ustwo is a digital product agency most well known for their work on the award-winning Monument Valley app. They partnered with Human Made, a WordPress development agency, to build the backend of the site.

The ustwo.com frontend is a React.js single-page application that serves WordPress content via the WP REST API using custom endpoints. In a post called “Open Sourcing Our Website,” ustwo developer Daniel Demmel explains why the company put the site’s frontend up on GitHub.

“Ultimately, we’ve built something that feels novel and polished enough to share publicly,” he said. “We want it to be of real use to others – after all, it’s all very well reading on a blog about how nice it is using React or Docker, with some Hello World examples, but having a chance to look under the bonnet of a production website is an entirely different thing.”

The team at ustwo decided to get innovative with a “headless WordPress” setup earlier this year, before the WP REST API was officially merged.

“The way we used WordPress as a headless setup accessible only through the API for a high profile production website was a bit of a technological bet – with WP-API landing in WordPress core six months after we decided to go for it – so sharing our experience and codebase should give execution ideas and confidence to anyone else considering this setup,” Demmel said.

Advantages of Headless WordPress

If you’re wondering why an agency might go to all the trouble of creating their website as a single-page application, you need only check out ustwo.com to see the difference. The beautiful transitions and speediness of the UI put the site head and shoulders above similar portfolio sites.

“We chose to build the site as a single-page application in order to have full control over all of its aspects – including transitions between pages – and to make navigation super fast by not having to reload the browser,” Demmel said. “We chose React.js as a main JavaScript technology to do this, since it has built-in support to render pages on the server side too (called isomorphic rendering).

“Our content management system behind this is a WordPress instance which doesn’t actually render the pages itself, but instead serves content up via the API through a mixture of standard and customised JSON REST endpoints, making the vast majority of the content editable,” he said.

Coincidentally, WordPress.com’s Calypso project runs on a similar stack. “So if you like what they’ve done to make the editor experience awesome, you’ll like what we’ve done to make the visitor experience great,” Demmel said.

ustwo opted to make their work open source just like Automattic did with Calypso, recognizing the importance of sharing in helping the whole ecosystem move forward.

“For us, there’s so much more value to be gained from building on each other’s work and knowledge than trying to hold on to a short-term technological advantage,” Demmel said.

The REST API is Changing How Teams Work Together

In a case study published on Human Made’s website, the team reviewed how working on the ustwo.com project has changed the way they work.

Working with the WordPress REST API brought a separation of concerns that meant approaching project management in a new way. Our developers were focused solely on WordPress as a data entry and delivery application. We were just one part of a wider team that included a designer, a front end React developer, a front end CSS developer, a Node.js developer, a project manager, and the stakeholder. This allowed each part of the team to be completely focused on their component, working independently while feeding back to the rest of the team.

Human Made attributes this tidy separation of concerns to the new workflow that naturally comes out of using a REST API. Back and frontend developers are no longer stepping on each other’s toes:

The technology itself facilitated this change in project management: all that the front end developers need to make the site live is to change the URL where the data is. When developers are working locally in their development environments they can work with the content from the live site; it also streamlines the process of moving from staging to production. We found that the API hasn’t just changed WordPress but changed how people work together, creating a new workflow and pushing where WordPress is going.

For more details on the ustwo.com architecture, check out Human Made’s case study as well as ustwo’s post reviewing the process. Solid open source examples like this one are always helpful when learning to build with new technologies. All the code for the website is GPL-licensed and available on GitHub for anyone to use or repurpose.

Does anyone remember the days when desktop applications where loading so slow each one had to have some animation while it is loading to proves that it is actually loading? Guess it is time to get that on the web.

The whole idea is stupid for a web site. Why to do two requests to the server (initial HTML and query for content) instead of one? And it seems like they did not (can not?) utilized the browser based caching as you get the animation when going back, something that should have been immediate.

And in order to make it workable they had to use node.js in addition to wordpress on the server, so instead of maintaining one server platform they need to maintain two.

This whole thing is nice if you are doing a web app like gmail but truly pointless when the inner navigation is minimal as it happens for most sites (I read this article and I am not going to read anything else on the tavern right now so what advantage do I get from all the JS code being loaded in the browser if I am not going to use any part of it)

There is only one request as the React templates are rendered server side – just try loading with JS turned off in the browser! The reason there’s a loading animation is because no matter how much you optimise JS, if you have a few libraries (React is even on the leaner side), the browser will need some time to execute it.

And browser cache is indeed used, the presence of the animation is a design choice, or rather not having got around to create specific animations for already loaded pages.

Also keep in mind that a portfolio site for a design studio is a particular use case where a level of emotional impact (or “wow”) is more important than most efficiently delivering content.

My understanding from the blog post was that it is done only for mobile so maybe I misunderstood here, but that prerendered html could have been loaded directly from wordpress. what is the added value of the middleman?

Not having an immediate rendering on back/forward browser navigation is just bad UX. The underlying technical reason is not very important.

Sure I fully agree that the design and hype (look we do all the buzzwords even in our site) can be important for such an agency but for 95% (being nice here) of wordpress sites it adds no value. Having to have a node.js is a non starter in the first place for all shared hosting (this includes managed hosting like wp-engine).

Question: Why do you need the REST API at all as you could have just written a node.js script that reads directly from the DB (you still write with wordpress admin, but don’t do anything else with wordpress). Again, why the middleman?

Question: Why do you need the REST API at all as you could have just written a node.js script that reads directly from the DB (you still write with wordpress admin, but don’t do anything else with wordpress). Again, why the middleman?

Thanks for asking this. As a non-developer myself, I really don’t get it.

All you have said is that someone needs to write a JS implementation of WP APIs. Maybe this is not something you and me can do by ourself but wordpress.com people sure can do.

There is a relatively big performance hit for intra server communication, therefor you want to minimize it as much as possible. No point in having node.js -> WP -> MySQL if you can just do node.js -> MySQL. You don’t care about such performance stuff only if you have extra money to pay for more hardware.

I personally don’t care “they” write something from scratch or not. I doubt most users do. What I want to know is what is the advantage to me, as a WordPress user or admin, in having something built this way. Or, to put this another way, what is so wonderful about this that I ought to ask a developer to do this for me?

At the moment, all I’m seeing is what could have been done before without the REST API. And yet no-one was apparently doing it. That doesn’t make it sound like something that’s worthwhile.

And, like Rick, I tested this site without JS activated, and found it loaded much faster and provided a much more pleasurable experience.

One possible use case would be to provide a front end that is not obviously WordPress powered (so less of a target for hacking attempts), can be secured more fully (place the WordPress backend content generator portion in a more locked down section), doesn’t need to hit PHP and a DB to generate a page (less server resource intensive, also well written javascript is amazingly fast now days), the content can be placed into layouts that can move far away from the standard WordPress theme template approaches (layouts that don’t have to think in terms of header, main, sidebar and footer), and javascript can allow for more fluid user interactions with data (ajax and instant UX changes).

Yes. I think people are getting confused with use case here. The theme is an example of what you can do, but the real benefit comes in when you use multiple API’s from external services. For example, I can build a react based app built on React and then hook into API’s from Etsy, and WordPress, and create, manipulate, and/or retrieve just the data I need, building a custom application to my taste that has my own Etsy store, and my blog presented precisely the way I want it to display and behave. Learning javascript application development and design is different, but it’s also the best method for many use cases today. If all you want is a simple blog, then you obviously don’t need the above.

Google as probably the biggest provider of REST APIs has rate limiting on almost all of them which means that in practice you need to authenticate, which means in turn that your authentication credentials have to be available in the JS code, which means bye bye security.

I never heard of a mashup done on the browser side, but I will be glad to see a real life example to that. All mashups that I know of happen at server side.

Hiding that a site is wordpress is the most stupidest practice the community engages in and got nothing to do with real life security.

If you are willing to lock down the admin then what security gain do you get? why do you think that node.js and react are more secure than wordpress theme code? why do you think the extra json code you will have to write will be more secure than the theme code you can write?

As for being somehow free to use more JS, no one prevented you to write JS/Ajax based themes before and people have done that. Nothing new here.

OriginalEXE didn’t go into details, but just to put things into perspective, our Node.js code tiny, a couple hundred lines altogether (probably smaller than most WP plugins) and all it does is to prerender content for the various URL routes. It doesn’t even know about the WP API or templates as that’s actually already React code. So it’s really just an extension of the browser side code, which it can run as both are JS runtimes.

Whereas if you were to go directly to the database you’d need to understand the structure of WP and also as far as I know any plugin can alter the database, so deal with unknown and practically infinite variations if some content is extended by and created with a plugin. And it will be guaranteed to break as soon as the database structure is changed. The point of having an API is that it’s an interface which is agreed on, won’t change without a notice and is optimised to efficiently retrieve the data, coded by people who intimately know WP.

So yes, while theoretically you could save some resources with Node.js directly going to the database and using optimised queries, actually doing it unpractical to the point that it’s almost impossible. But don’t forget that any non-trivial WP installation will have some cache, ours for example stores API responses in Memcached which is orders of magnitude faster than anything trying to read the database.

You say many things with which I can agree or disagree to some extent but you end with “and we cache responses in memcache” which nullifies your arguments. When you read from memcache you bypass all the filters and action plugins are using on the WP side and therefor end with a very similar situation as getting the values directly from the DB (and hmmmm, the DB structure of wordpress that relates to serving post content is actually very easy to understand, I refuse to believe that you don’t understand it)

@mark you are making some assumptions which aren’t necessarily true for all WP setups: you don’t have to have filter and action plugins installed, neither do you need to cache things in Memcached for any longer than even a couple of minutes to greatly reduce DB load.

Working directly with the DB is not a matter of understanding, it just doesn’t make sense unless you’re specifically interested in WP innards.
APIs were invented for a reason and there are many other strategies to optimise server resource usage. Our main caching layer isn’t even Memcached, but a CDN, so 90+% of visitor requests won’t even reach the WP backend at all, people will either get prerendered HTML or stored JSON API responses from the CDN edge which is geographically the closest to them.
It’s cheap, fast and efficient.

All these still doesn’t mean that I’m trying to convince you that this is the right approach for you and everyone using WP, but try to keep an open mind and see the possibilities instead of trying to find faults! This isn’t something which is going to replace WP themes or be a mainstream thing, but I think it opens up a completely new frontier for WP being able to serve more application like websites and applications proper (even native ones where you can’t argue that an iPhone app should connect directly to the DB). And I couldn’t be happier to see an open source CMS with a great community gaining this possibility!

DAIN

@daaain

Please note that I regularly don’t work on Wednesdays, so I won’t be able to reply or attend a meeting / call on these days. Sorry about the inconvenience this might cause to you, but my young family really appreciates this time.

@daniel, just wanted to apologize if it sounds like I am grilling you over your software design decisions. Obviously Client and budget have much more important factor in the end result than being “best”.

I think that my bias against the REST API in the way it is being developed and hyped is obvious and I actually thank you for taking the time in explaining the setting as now I can point to specific issues I have instead of theorizing about how actual implementations will look like and what will be their weakest points.

For me it is double obvious right now that promotional site like that one should not be done in wordpress if usage of react is a requirement as the resulting software architecture is too complex to be maintained by one developer and it is a total maintenance hell for the non technologically oriented site admin. Using ghost in this kind of setting sounds like a much more natural decision from software development POV.

I just wanted to shift the focus a little bit as I think the critical questions aren’t really that much related to database (or even backend) performance, but more so how and when WP API would be useful. Maybe there’s a bit too much hype around it, it’s definitely not going to replace classic WP templates, but makes WP a more flexible platform by opening up app integrations with it (be it a single-page application on the web or even native apps).

In our case the choice was made because we wanted to create a special visitor experience with a single-page application while having an advanced admin / editing interface with a rich set of plugins to do things like automatically taking care of creating / converting responsive images, etc.

This is not something which can be done in Ghost, and maybe there are other, simpler CMS systems which can deliver content via an API, but we were already using WP with a 100+ posts and wanted to use a proven open source system with a healthy ecosystem.

Maintenance is not something which our editors will do, one way or an other it’ll be up for developers. But they should definitely be able to create content easily without having to worry about manually processing images or writing much raw HTML.

That’s true for every single website, the initial load is of course going to be faster without JS. But not having any interactions without a page reload is only going to work for very simple sites, for most cases you do need it.

In our case you might not like the animations and prefer the instant load, but again don’t forget that the use case here to “wow” visitors not to just serve content up.

> Why to do two requests to the server (initial HTML and query for content) instead of one?

Actually, it’s all pre-rendered server-side, which is the point of having Node on the backend. You can verify this yourself by looking at the requests made from your browser; there’s only one API request, which is for “takeovers” (full-page promos which take over the whole page for when they’ve just launched something new).

It doesn’t require two requests, the only reason the takeover isn’t baked in is because we only want to show it for people with JS anyway.

The whole site more or less works with JS disabled, just give it a go!

And going back to the original comment, browser cache is indeed used, the presence of the animation is a design choice, or rather not having got around to create specific animations for already loaded pages.

Also keep in mind that a portfolio site for a design studio is a particular use case where a level of emotional impact (or “wow”) is more important than most efficiently delivering content.

But the site is anything but fast (or at least, it wasn’t for me). Loading the initial first page of the site took about 6 seconds and every page there within the site had an animated loading icon thingy for a second or so before anything appeared. The visual rendering speed of properly optimized WP sites (on quality hosting) are much less… if the RESP API is supposed to make sites faster, I wouldn’t say this is a very good example. Just saying.

@Brin the speed of PHP has very little impact on the peformance of wordpress. The biggest bottle neck with wordpress relates to DB access, and only after you solve it there is some point looking into other optimizations.

I’m not sure if that comparison makes sense, you’d use these different approaches to solve different problems.

Creating a single-page application is almost surely going to be more effort, but then you have more control over the experience as you’re not at the mercy of browsers having to reload pages for example. Or if you need to create a more complex, offline-first web app powered by a WP CMS backend.

But I definitely don’t think people should just completely drop traditional PHP based themes, they are still going be a perfectly good solution to most needs.

Look at this development (as in having WP API) as a new tool in the toolbox you can reach to in case you had projects where you were stretching the limits of what you can do with themes. But getting a new tool doesn’t mean you need to bin all the previous ones…

I just wonder what it’s performance would be without all the caching layers, because you know, even a crappy non-optimized way-too-many-db-requests theme/website can be served extremely fast if: “We have everything served up from a CDN, and by that we mean that ustwo.com is pointed at the CDN URL on a DNS level!”

I’m in no position to judge as I’m only now learning JS, but hearing the community shout that the JS approach is native-level fast, super-uber-hyper-easy, and quite a lot of other nonsense really, well, that by itself is a reason of why I would love to see a comparison like the one I mentioned.

I’m all in for the tools that get the job done, and kudos for doing it the way you did.
However, as far as the end user is concerned, it’s just a fast website. In the eyes of a [front|end] webdev who won’t look at the page source / dev tools, it’s something doable with a plain old theme, some ajax and loads of caching.

That being said, I’m not dismissing the “new” tools. All I’m saying is that it could have been made in a different, or more “traditional” way, and makes it look that it was done like it’s done just for the novelty of it.

I think the “wow” factor you were trying to achieve is for the webdev community, not your actual customers, and indeed you have achieved it, so, bravo!

Somewhat unrelated but also related, Facebook (built using React) completely stops working without javascript. It won’t even let you use it if you disable javascript. Is this the future of the web if javascript is the future of WordPress?

I’d love to see a post about best practices for fallbacks when javascript is disabled – as Facebook is clearly not a good example of how to do it :/

The ustwo site actually is. You can write React code to run on the server and thus pre-render the pages. As you can see if looking at their site with JS off, you lose the custom fonts, you lose animations and a few other things but the site looks nice and works fine.

The cool thing is that it’s not too hard to create proper URL routes to work both on Node / Express and in React / Flux, so for example on the Join Us page the studio location tab switch is actually changing the URL as you toggle and gets prerendered with the right state too: https://ustwo.com/join-us/london

So with the server side one we’re just stubbing out objects / properties we’re referencing to prevent JS errors in Node.

It might look a bit tedious to have all these adaptor files, but they get compiled in Browserify to separate targets (using Aliasify) as we want to avoid server side code being delivered to the client side.

Agree. We use Javascript when we need to provide better user experience and better performance of the website (if we do it right). One size doesn’t fit all. We can choose traditional way to build WordPress website or a new way with Javascript. It’s just another option, another opportunity.

Using the WordPress API to fetch the data for a theme doesn’t make sense as the WP API is self consuming (the end points live on the same server that the theme is served from) and you can save yourself the round trip request from the browser to the server and then back down to the browser again.