kxws888/wordexpress

WordPress using Node, React, GraphQL, and Apollo

WordPress Express

This project aims to replace PHP with Javascript in WordPress development by using Node.js and Express to consume data from a WordPress database using GraphQL. It uses Apollo to fetch the data and deliver it into React components. This repo is the codebase for wordexpress.io, where I will write articles and documentation explaining how it works.

The core of this project revolves around setting up a connection to a WordPress database using Sequelize, defining models from that connection, and then querying those models using GraphQL. It's delivered through an npm package called WordExpress Schema. Read the documentation for implementation details and information on how to extend it.

I've also started creating a set of WordExpress Components that contain GraphQL qeuries based on the WordExpress Schema package. Refer to that repo for documentation.

Regarding building, this project using Webpack, and requires Node V 5.0.0. You might be able to get away with 4.0, but really just tighten up and use 5.0.

Docs on Medium

Part 1 - Introduction

Part 2 - The Setup

Part 3 - The Schema

Getting Started

Add the WordExpress Companion Plugin

You'll need to install the WordExpress Companion Plugin into your WordPress plugins directory. Currently, the plugin simply adds a custom field to all WordPress pages that lets you set a React component as a page layout. See the layouts section below for details.

Install NPM modules and running Locally

Just run npm install and then npm run startdev, which will start a Webpack Dev Server. It should automatically open a browser window pointed at localhost:3000.

Building For Production

Run npm run build, which creates a dist folder in the root directory that contains production-ready code to be deployed to a node server. You can run npm start which will start the express server using code in the dist folder. There is an npm run deploy script that will call a deploy.sh shell script located in the /scripts folder. Mine is not included in this repo, since it contains production server information, and it's specific to my setup.

Defining Your Application Settings

You'll notice a settings folder, which contains JSON files for development. This is where you can define settings for uploads, WP database connection, and some other things. Change accordingly. For production, create a prod.json file in the same format as dev.json.

Upload Settings

This project uses Amazon AWS with an S3 bucket. If you are hosting your media files on the same server as your WP installation, set amazonS3 to false and set the uploads directory accordingly. If you are using S3, set don't include 'wp-content/uploads' to the end of the setting - it will be added for you.

Database Settings

This should be pretty self-explanatory: simply enter in the name of your database, username and password, and host. Make sure these are inside of "private", or else they'll be available on the client (WHICH IS BAD).

Using React Components as Layouts

As mentioned above, make sure you have first installed the WordExpress Companion Plugin into your WordPress plugins directory. The plugin will add a custom WordPress meta box to all your WordPress pages. There is a text input field in the meta box called Page Layout Component. The value you put in there should match one of the objects in the Layouts object in the layouts directory. The Layouts object stores some basic parameters that the WordpressPage component will read. It looks like this:

import PostList from '../posts/PostList.js';
import DefaultLayout from './DefaultLayout.js';
import FrontPageLayout from './FrontPageLayout.js';

const Layouts = {
  'Default': {
    Component: DefaultLayout
  },
  'FrontPage': {
    Component: FrontPageLayout
  },
  'PostList': {
    Component: PostList,
    postType: 'post',
    limit: 10,
    skip: 0
  }
};

export default Layouts;

In the above example, I have a WordPress page called 'articles'. On this page, I want it to use a PostList component and show posts of the 'post' type, with a limit of 10 posts per page. In the Page Layout Component field on the Articles page in the WordPress admin backend, I enter "PostList" and publish the page.

Playing With GraphiQL

GraphiQL is the in-browser IDE for testing GraphQL queries. For experimentation purposes, I've kept the GraphiQL IDE publically available so you can play around with querying the WordExpress database. Check it out here.

Roadmap

This project started out as just an experiment, but it seems like a lot of other developers have this pain point while developing in WordPress, so I've started building out a road map of features. I'll try to prioritize them.

1. Make Server Side Rendering work. It's weird using Relay, and Facebook doesn't have official support for it, though it seems like it might be coming soon. We need SSR to handle SEO, meta tags, and all that.

2. Need to make layouts work better. Currently, you create a custom field in wordpress for each page called 'react_layout" and just type the name of a React component that will server as the pages "layout." It could be better. Ideally, I'd write a companion WordPress plugin that comes complete with some standard custom fields that work directly with this project. The companion plugin exists!

3. Work on developing more complex queries. The WordExpressDatabase object is currently expandable, meaning after importing the default from wordexpress-schema you can add Sequel models and queries to it before passing it into WordExpressGraphQLSchema. However, WordExpressGraphQLSchema is not expandable. This should be a thing.

4. Figuring out how to get WordPress shortcodes to work. I'd only expect that built in WordPress shortcodes would work (i.e [caption], but they don't currently. It would require parsing the post_content field and then recognizing short codes and then probably building a unique React component for each shortcode. Currently only a few shortcodes work. I've got Caption working, as well as the ability to embed Github Gists.