Clone this repository locally and cd
to the client
folder and type npm install
.
The React app relies on an .env
file to configure itself to its environment, and this repo ships with an example that you can copy and rename. To do so, make sure you're still in the /client
directory, and then duplicate / rename .env.example
by running cp .env.example .env
. The example .env
file comes preloaded with the URL to the default Docker installation of Wordpress.
First, make sure you have Docker installed locally. Once you do, cd
to /api
to duplicate and rename docker-compose.yml.example
by running cp docker-compose.yml.example docker-compose.yml
. Now we need to edit api/docker-compose.yml
to link your local filesystem with Docker's Wordpress files. To do so, open up our newly duplicated docker-compose.yml
and change the following to match your local install directory.
NOTE: You only need to change the path located before the colon. In this case, replace ~/www/react-wp-rest
with your install directory.
volumes:
- ~/www/react-wp-rest/api:/var/www/html
You may want to also swap all ex_
prefixes for your project's abbreviation to avoid using the same container across multiple projects.
Feel free to make any other changes you'd like to the default user and database configurations but there's no real need locally. Just don't use defaults in production.
Next, fire up Docker if it isn't already. Once this is done, ensure you're still in the api
directory and and type docker-compose up -d
. You can now reach your WP instance via http://localhost:8080
.
After you're up and running, we need to navigate to http://localhost:8080/wp-admin
and perform the following steps to Wordpress:
- Activate the REST API theme
- Activate plugins ACF PRO and ACF to REST API
- Import boilerplate ACF custom fields by navigating to
Custom Fields -> Tools
, and uploadingapi/acf/acf-meta.data.json
. This will add meta fields to each Page and Post by default, avoiding the need for Yoast SEO or similar plugins. Extend and add to other post types as you need - Add a new page called
Home
, set it to use theHome
page template, and then set it as your front page in theSettings -> Reading -> Your homepage displays
section - Change Permalinks to the 'Custom Structure' option and enter
/post/%postname%/
- Update your Site Address within
Settings -> General
to your SSR app (default: http://localhost:1337)
Note: It's important that the Site Address update is performed last in the order above.
The server-side rendering configuraton in place serves the /client/build
folder on port 1337
. The /build
folder contains the results of create-react-app
's npm run build
command - so before attempting to test SSR, make sure you first run npm run build
. After that, run npm run serve
while still in the /client
directory to fire up the server.
At this point, you can get to work. For a development workflow, we've included create-react-app
so we can rely on all the goodness that comes with it. cd
into /client
and run npm start
to get to work.
This repo comes preconfigured to support Sass.
We use Redux both on the server and the client to cache the site content provided by Wordpress in memory. This is a very simple approach but it works quite well in practice. The first time a client requests a server rendered copy of a page, Node serves the contents of the build
folder, without waiting for the asynchronous calls to the WP REST API. But, this first call populates the in-memory Redux store - therefore any consecutive requests by clients to the same server rendered page will automatically pull from the Redux store - and will automatically populate the data from WP.
Repo relies on Wordpress page templates to assign ACF custom fields to pages as needed. For example, a Homepage will generally require different custom fields than a typical About page. By creating empty templates in the /api/wp-content/themes/rest-api
folder, we can assign them to pages we create within Wordpress. We then can write ACF logic to apply custom field groups to pages that use specific page templates, and then we can mirror the same template structure on the client side, but built with React components.
To build this repo, we've relied heavily on a few very helpful Medium posts from Andrei Duca:
https://medium.com/bucharestjs/upgrading-a-create-react-app-project-to-a-ssr-code-splitting-setup-9da57df2040a https://medium.com/bucharestjs/adding-state-management-with-redux-in-a-cra-srr-project-9798d74dbb3b
Inspiration from Postlight's Next.JS + Wordpress setup: