In this article, I’ll introduce you to VuePress, show you how to create a simple blog, and create a custom layout component.
VuePress currently powers my personal site and the WordExpress doucmentation site.
One of the most difficult things to overcome at the time was server-side rendering with GraphQL. WordPress sites require search engine optimization, and you can’t begin to do SEO without server-side rendering. A lot has changed in two years, and server-side-rendering with GraphQL is now much easier thanks to Apollo.
In the past month, I’ve revisited WordExpress and I’ve come up with a solution using Vue instead of React. This is totally doable using React (in fact a big piece of the puzzle is the WordExpressSchema which is front-end agnostic) but I’ve been using Vue a lot and they have great documentation on server-side rendering, so I decided to give it a go.
I’ve called this new solution VuePress because I’m very clever with words.
The VuePress Architecture
On the back-end, VuePress consists of a node server (using express) that has a GraphQL endpoint. The GraphQL endpoint uses GraphQLExpress from Apollo, which accepts a schema. This is where WordExpressSchema comes in. You can (and should!) read the documentation on the schema. In short, the schema has queries which are resolved by connecting to a WordPress database and getting data directly from it.
On the front-end, VuePress consists of Vue components. Some of these components contain GraphQL queries. When the server gets a request, it determines which components to render, prefetches the required data from GraphQL, pipes that data through a template, and finally renders the HTML.
Making A Blog
The code in the VuePress repo contains pretty much every thing you need to get started. First, clone the repo and follow the instructions in the readme to get started.
A note about custom fields: I personally use the advanced-custom-fields plugin for WordPress, and I use the pro version. You absolutely don’t need to use this plugin, but it makes life much easier, and all the VuePress documentation assumes you are using it.
After following the directions, you can start the development server.
$ npm run dev
You should get something like this:
Lets change the layout of the homepage to include a page header.
Now it should look a little nicer:
Creating A Post List
First, lets create a page that will show all of our posts.
Notice the value for the Layout Component is PostList, which generates some extra custom fields (this is why ACF is nice!). The PostType drop down will tell the
PostList component which post type in WordPress to render. Right now, we only have posts which is the default. VuePress also allows you to render different Post Item Components for each post list. Imagine you had two pages — a list of Articles and a list of Photographs. The list items in each page would probably be designed differently (articles would have text, photographs would have images), so you’d probably want to use a different component to render that item. You could create a whole new Layout Component with a different list, but that is more work.
Now, lets add the new Posts page to our primary-navigation menu.
Save the menu and refresh your application browser. You should see that the posts page is now in the header menu. That page looks like this:
Voila, we have a very simple blog in just a few steps.
Creating a Custom Layout Component
Lets say we want to create a page that has a sidebar that has its own menu of external links. So far, we haven’t had to touch any application code, but that’s about to change. First, we need to make some updates to our custom fields.
In the WordPress back-end, go to Custom Fields -> FieldGroups -> PageFields. Select page fields and add a new value to the LayoutComponent field.
Save the changes by clicking the Update button on that far right. Now, lets create a new page field called SidebarMenu that will let use render a custom menu by name. We only want this field to show up on pages that have the PageWithSidebar layout. Click the AddField button.
And further below, we want to add some conditional logic on when to display this field.
Save the changes.
Now, lets create a new menu for the sidebar. My menu will be a collection of links to Vue resources that I like. Yours can be whatever! Here’s what my menu looks like:
Now lets create a new page that will use the sidebar and the custom menu. You can name the page whatever you want — I’ve named it Resources.
Lastly, you’ll need to remember to add the new page to your primary-navigation menu.
Great! That’s all we need to do in the WordPress back-end. Now, we’ll need to create the custom layout file.
The layout components are located in
/src/components/page/layouts . In that directory, you’ll see the existing layout components. Create a new file called
PageWithSidebar.vue . Its going to look like this:
There are several things to note. First, notice the custom
menu-container component. This component contains a GraphQL query. It accepts a prop called
menuName and uses that to query GraphQL and get the items in the menu. But first, we have to get the name of the menu from the custom field of the page we are currently on. For that, we have to do some filtering of the page’s post meta.
This is a good time to mention that VuePress comes equipped with GraphiQL — an in-browser IDE for exploring GraphQL. You can go to
localhost:3000/graphiql and see it. Click here and it will open up GraphiQL with the page query for a page with a name “resources”, which looks like this.
meta_key for sidebarmenu and the
meta_value is resources-menu. Going back to the PageWithSidebar component, you can see that the
getSidebarMenuName is simply filtering the post meta for the sidebarmenu key and getting its
Now, lets look at what a menu query looks like. Click here for that link.
Now, menus are arguably one of the craziest things in WordPress because of how they are saved in the database. Each menu item has a
navitem that is either a link to another post, or a custom link with its own post meta. In the case of this sidebar menu, all the links are custom. Luckily for you, though, I’ve created a
MenuLink component that will determine if the link is internal or external, so you just need to pass the navitem to it.
Here’s the final result of the
While VuePress is still in heavy development (I haven’t even written any tests for it which makes me a bad person), I think its a step in the right direction. It feels good to be able to write Vue components instead of using PHP templates. Its nice to have scoped CSS or CSS modules built in. Its nice to finally have server-side rendering.
Over the course of the next couple of weeks I plan on really tightening up some documentation as well as developing a comprehensive testing suite. If you’d like to contribute, please hit me up on twitter or send me an email. Happy developing!