💥 Starward

Full-stack Wordpress boilerplate web app built using ReactJS and WP REST API v2, built on the awesome reactGo framework 🎉

Features:

Sites using Starward

Wordpress Dependencies

Requires a Wordpress setup using the following plugins:

Strongly recommended plugins

Optional supported plugins

Getting started

⛔️ 📛 🚫 IMPORTANT run yarn build or npm run build at the start of each project

Running Server

yarn && yarn dev / npm install && npm run dev

Configuration

Client App Config

Rename /app/config/app-template.js to /app/config/app.js

SITE_NAME fallback site name if ACF options page is unavailable
POSTS_PER_PAGE number of posts to be shown on blog, category and author listing pages, default 10
HOME_SLUG WP slug for front page, default homepage
BLOG_SLUG WP slug for posts page, default blog
CATEGORY_SLUG desired root slug for category pages, default category
AUTHOR_SLUG desired root slug for author pages, default author
ROOT_API GraphQL root URL (does not require changing from default)

Server Config (contains secrets, don't include inside client/front end code)

Rename /server/config/app-template.js to /server/config/app.js

WP_URL root URL of Wordpress installation
WP_API root of WP API (does not require changing from default)
WP_AUTH Basic auth details for API/developer user, used for submissions of Gravity Forms - Don't expose to front end
REDIS_PREFIX Prefix for redis keys to avoid key clashes during development (required in production unless you disable redis via ENV variables)

Redis Setup (optional)

Redis runs by default in production, this can be changed in /env.js
Redis can be ran whilst in development by running npm run dev:redis or yarn dev:redis
Redis cache can be cleared by hitting ${baseURL}/api/flushredis in your browser

Install Redis (optional):

brew install redis

(you can also manually install, but if you don't have brew it's rather useful!)

Open a new terminal and run

redis-server /usr/local/etc/redis.conf

make sure to keep this terminal open as it's not running as a daemon. To see more ways of launching redis, check this blog post out.

Quick and dirty ACF Pro Setup

Two ready to import JSON field groups are located here /wp/ACF:

page_flexible_content.json - Component based (/app/components/ACF/layout) field group using the native ACF PRO flexible content field
settings_option_page.json - Generic setting fields designed for a custom option page within Wordpress and accessible from the GraphQL endpoint /api/settings

Styling

Component and container level based styles exist in /app/components/*/*.scss & app/containers/*/*.scss and are imported at the top of each JSX file (beneath absolute and relative module/component imports):

// Header.jsx
import React from 'react';
import { Logo } from './Logo';
import './Header.scss';

Global SASS partials (variables, typography, grid settings etc) are contained within /app/sass/ and are split between two folders:

/base

For storing Sass mixins, variables and functions across the project.

/global

For styles and classes used throughout the project, such as our CSS reset, typography rules, etc. Imported in App container (/app/containers/App.jsx) - file imports need be relative to here.

GraphQL

All data from WP-API is consumed in GraphQL with the help of Graph.ql (https://github.com/matthewmueller/graph.ql), which returns a smaller, more succinct response using Express. The purpose is to reduce the amount of JSON contained within the initial state that gets supplied to the document by the server when running universally.

The GraphQL schemas and queries are located within /graphQL

The GraphQL API endpoints are defined within server/init/api.js

Out of the box the following API requests can be made to the API server localhost:3000/api and can be extended by adding additional GraphQL schema within /graphQL:

Get site settings from ACF PRO options page

Pulls data from a custom option page containing the following ACF fields /wp/ACF/settings_option_page.json

GET: api/settings

Get a page

GET: api/page?slug=*

Get a post

GET: api/post?slug=*

Get collection of posts

GET: api/posts?page=*

Get a category and list of posts

GET: api/category?slug=*&page=*

Get an author and list of posts

GET: api/author?name=*&page=*

Get results from a search request

GET: api/search?term=SEARCH_TERM&type=posts&page=1&perPage=10

Get a Gravity Form

GET: api/gravityforms?id=*

Please note submitting the Gravity Form is handled by a direct API post request to the WP GF API v2 service inside an action, please view app/actions/gravityforms.js

Debugging 🐛

Have you installed and activated all plugins listed above including Search By Path
Have you checked the API endpoints listed above in your browser including GET: api/settings && GET: api/page?slug=*.
Have you checked the API endpoints listed above in Postman, does it flag any encoding errors within data from a WYSIWYG inside WordPress? Sometimes illegal characters can be pasted into WordPress that drive the API crazy. We try and santise this here using this Regex but this does not cover edge cases. Using the clear formatting option within the WordPress WYSIWYG editor usually fixes this issue.
Is WordPress running and returning data from it's API. You can find the WordPress API endpoints here
Is Redis enabled? If so try flushing the cache by hitting the API endpoint GET: api/flushredis
Something else? Let us know or add your solution here

samlogan/starward