In my last article in this series, I discussed optimizing and preparing your site to serve as the content management system and REST API for a single page web app (SPA) that does not run inside of WordPress. I have packaged those optimizations into a WordPress plugin, called Josie-API, which you can install from WordPress.org. I have also put the complete code that I’ll be walking you through in this article and the next one in a GitHub project called Josie, so if you want to start by forking it, or want to read all the code together, go there.
In case you were wondering, I’ve named the project after one of my dogs, a 3-year-old Pointer named Josie that my wife and I rescued from the shelter earlier this year.
If you go to GitHub you can see the setup that I’m detailing working live, where it’s serving posts from my own website. One of the goals of this project is to emulate WordPress pretty permalinks perfectly, so that I can use this as a replacement for my current site’s front-end.
Moving forward I intend to use this or K. Adam White’s ExpressPress as the starting point for all of my development projects. For many reasons, I am personally very excited about the possibility of using WordPress only for content management, and using this or something similar as a front-end solution.
Why Node?
The first reason I am excited about a Node-powered front-end for my sites is simply because it’s faster. WordPress site managers and developers spend so much time and energy optimizing their sites. Without any caching, or even proper JavaScript or CSS minification, my pingdom page load times are 190-500ms when testing from the US, and just under a second when testing from Europe.
The second reason is that I’m able to use a simple JavaScript templating language, Handlebars. It’s so much simpler than working with WordPress templates in a WordPress theme. PHP just isn’t a great templating language.
Another reason is that, while the example site looks pretty bland thanks to the use of a totally stock Foundation front-end, any designer/front-end developer hired to work on it will not need to know anything about WordPress. That’s going to really open up the range of designers and front-end developers I can call on to work on a site.
Most importantly though, since the web server being used is Node, moving between the browser and a mobile app is incredibly simple, and there are a lot of solutions. The easiest path would be to use Cordova (AKA PhoneGap) to take advantage of mobile device interactions and also to build a native app. The internet is full of solutions for Node.js-powered mobile apps. Using this approach opens you up to that.
In this tutorial, I will be trying to be as general as possible. I’m sticking to using JQuery AJAX to make the requests. Using the client-js for the API, as done in the ExpressPress project, might make a lot more sense for some people, but it requires an understanding of both Backbone and Underscores, which require more advanced and specialized skills.
While my code is totally usable, I encourage you to view it more as a proof of concept. As you read these tutorials and review the code, I hope you start seeing how to do the same thing using your prefered JavaScript Framework or even in another language altogether.
Goals
In this tutorial, the goal will be to create an app for a basic blog site. Like WordPress itself, mastering that leads to so much more. Using the REST API’s support for custom post types and post meta, or using Pods and the Pods JSON API add-on, you can turn this into a complete web app pretty easily. As I said this is a good starting point, use it as a jumping off point for your own needs.
This is a huge topic, and I have intentionally avoided some of the important steps in creating a more efficient and manageable app, as I don’t want to cover dependency management, client-side caching, etc.
I intend to build all those things into this eventually because I want use this for my own projects. That is why in my example code repo I have added a tag so you can see the code as it existed when this article was published and also see how it’s evolved over time.
Setting up your node server
As I said before, one of the goals for this app is that when viewed in the browser, it should use the same URL structure as WordPress pretty permalinks, allowing it to act as a drop-in replacement for an existing WordPress site. In order to be a true single page web app, and reap the performance and UX benefits of a SPA, this needs to be accomplished without page loads.
The solution I came up with was to write a little code to use push states to update the URL shown in the browser, after clicking a link. Also, the app’s router is written to read the incoming URLs and call the right function to generate the view based on the URL that the browser is showing.
The catch here is that push state URLs aren‘t “real” urls. If you were to run the code from this tutorial without the node server, it would work — except when you refresh any page besides the index you’d get a 404. The Node server is very simple. All it does is use Express as “middleware” to route all requests — except for JavaScript, CSS, and images— to index.html.
You will need to install node on your computer. You can do this via one of the installers that you can download here, or via your OS’ package manager.
Once you have node installed you will need to install Express as a node module inside of the directory for this project. Simply change to that directory in your terminal and then use the Node Package Manager (NPM) to install it by typing:
Now that express is installed, we can use it to write our simple server. Node provides a series of “modules” that can be combined to create simple to complex web apps. Each module is a JavaScript object. Our server will use several modules, and all but one is included in Node. The other has to be added using the Node Package Manager (NPM)
To use a module we call it using node’s require() function, and store the result in a variable, which is now a JavaScript object. So, to begin, we use require() twice to create an object of express, and another of “path,” which is included in node. Create a file called “server.js” and start with this:
We can now create our server, which is actually another object, called “server.” We will be constructed out of the methods of these two classes. We start by adding the function express() to it, like this:
We will need to create two special routings to ensure that our JavaScript, CSS and images are not caught by our third, “catch-all” routing. They look like this:
Our catch-all router looks like this:
Now all requests will be routed into the public folder, and if it’s for any url without a file extension at the end, our index.html file will be served. The only thing left to do is set up the port for the server and tell Node to listen on that port. That looks like this:
Feel free to change the value of the port variable to whatever port you want to serve your app on. Also, note that this, or any other use of console.log() in this file, will not show up in the browser’s console. Rather it will show in the terminal after we run the file.
Here is the whole server file:
Pretty simple, eh? In order to start the server in the terminal type “node server.”
You should see the message “Server listening on port 1001″ in the terminal. If you do, add a directory called public, and in it add a file called index.html. Just add some placeholder text to that file for now. Then go to http://localhost:10001/ in your browser where you should see that placeholder text. If you’re running this on a remote server, replace that server’s IP address or URL for localhost.
Congratulations, you just created a Node and Express-powered web server! For a more fully-featured intro to writing a Node server, with Express, I recommend this article.
Making node server persistent
One thing that you should be aware of, which frankly caught me by surprise, is that by default Node.js servers aren’t persistent. I’m used to working with Apache and nginx, which keep running as long as the servers on and nothing goes wrong. Node.js, on the other hand, will shut down once you close the terminal window you opened it up in.
This creates an obvious issue for using this to serve a web app. One way of dealing with this on the live site is to use the Node package Forever, which keeps Node running indefinitely. On your live site, simply install Forever using npm, and then use it to start the app, like this:
For a more detailed look at this issue, I recommend, this article.
What server to use
Since this app doesn’t have its own database, it’s very easy to develop locally. That is if you’ve set your cross origin domain access headers correctly, like I showed in my last article. It also makes deployments very easy, just git clone the site’s repository to your live server and everything will be updated.
What server to use for the Node-powered front-end is an interesting question. I chose to use a second server, as I wanted to make sure that my experiments didn’t impact my current site at all. I asked K. Adam White, the author of ExpressPress, about the site that ExpressPress is based on and he said they too used a separate server, because “having it co-located with node seemed overly complicated in an age of cheap AWS virtual servers.”
He also pointed out that having two separate servers makes it easier to maintain both.
While I wonder if running both sites on the same physical server might have performance benefits, I agree with White about the benefits of isolating them.
For my demo I used Digital Ocean’s $5 droplet, and there one click Node.js image. It had everything I needed except for git. To deploy my app, I installed git, cloned the app into a new directory, and then started the server with Forever. On my Ubuntu-based server it was this easy:
Laying out the page
Now that we have the server, we can start building the app itself. Like the description “single page web app” says: it works entirely from one HTML file. Also, the end-user will never leave that page. To begin, we need to create that HTML file.
The file, besides loading our CSS and JavaScript will create a basic scaffolding for our site, full of empty containers. This will allow us to load content into the various containers we create. In my example code, this is the scaffolding:
This gives us two areas to populate with content, wrapped up in Foundation’s off-canvas component to create a slide-in and slide-out menu. Inside of the slide out menu we can put a menu or other content.
Foundation is set
That’s it for part two. So far we’ve covered optimizing a WordPress site for powering a SPA running in a separate server. I’ve also detailed enough information about Node so you should be able to use it to create a simple server for the app, using the page scaffolding that we’ve laid out.
Next week, I will be covering the JavaScript to populate the page we laid out with data from a WordPress site and handle peralinks. In the meantime, I challenge you to see what you can come up with to make the right calls via jQuery AJAX or using another language to fill out the app. Or you can read ahead on GitHub, or just wait until next week when I will walk you through it step by step.
Josh Pollock started learning WordPress development when he was supposed to be working on his masters thesis, which ended up being about open source solutions for sustainable design and was presented in a WordPress site. You can learn more about him at JoshPress.net or follow him on twitter @Josh412
The post Setting Up a Node Server for a WordPress REST API-Powered Single Page Web App appeared first on Torque.