Wuxt logo

Nuxt/WordPress development environment - Wuxt

Wuxt combines WordPress, the worlds biggest CMS with nuxt.js, the most awesome front-end application framework yet.

Quick start
Introduction
Architecture
Getting started
Generate and Deploy
WordPress Rest API endpoints
- Extensions to the API endpoints
Scripts
- Working with the containers
  - WP-CLI and yarn
- Scaffolding
Links
Credits

Quick start

git clone https://github.com/northosts/wuxt.git
cd wuxt
docker-compose up -d

http://localhost:3080/install.php - Install WordPress
http://localhost:3080/wp-admin/options-permalink.php - Set permalinks to Post name
http://localhost:3080/wp-admin/themes.php - Activate wuxt-theme
http://localhost:3000 - Done

Introduction

The goal of Wuxt is to provide a ready to use development environment, which makes the full power of WordPress easily available to your front-end app. Included in Wuxt are:

Fully dockerized WordPress and nuxt.js container configuration, docker-compose up -d sets up everything needed in one command and you can start working
Extended Rest API to give the front-end easy access to meta-fields, featured media menus or the front-page configuration.
The newest nuxt.js version, extended with a WordPress $wp object, to connect to the extended WordPress Rest API.

All together the Wuxt features get you started with your front-end with just one command, you just need to work with the intuitive WordPress admin interface and can skip all back-end coding. But if you know your way around WordPress you are able to easily extend the back-end as well.

The WUXT architecture

WUXT environment

Getting started

First clone this repository to a directory you want, then change to that directory and simply start your containers (you need to have a running Docker installation of course):

docker-compose up -d

That starts the following containers:

MySql (mysql.wuxt) Database for your WordPress installation. The data-folder of the database-container is mirrored to the _db-folder of your host system, to keep the data persistent.
WordPress (wp.wuxt) on a Apache server with the newest PHP version and the Wuxt Rest API extension theme, ACF and other good-to-have plugins pre-installed. The wp-content directory of the WordPress directory is mirrored to the wp-content directory on your host.
nuxt.js (front.wuxt) started in development mode with file-monitoring and browser-sync and extended by a complete WordPress Rest API wrapper and a starter application, mimicing base functions of a WordPress theme.

Your containers are available at

front-end: http://localhost:3000
back-end: http://localhost:3080, http://localhost:3080/wp-admin
database: docker exec -ti mysql.wuxt bash

Starting with custom container configuration

wuxt allows you to change the above setup to run multiple projects at the same time or to adjust to your own environment. To change ports and container names, add an .env file in the same directory of your docker-compose.yml file. You can adjust the following values:

WUXT_PORT_FRONTEND=3000
WUXT_PORT_BACKEND=3080
WUXT_PORT_DIST=8080
WUXT_MYSQL_CONTAINER=mysql.wuxt
WUXT_WP_CONTAINER=wp.wuxt
WUXT_NUXT_CONTAINER=front.wuxt

After you created the file, run

docker-compose down
docker-compose up -d

There is even a script that does everything to you :

npm run env

You will be asked for projectname, front-end-port, back-end-port and dist-port. The script creates an .env file like the folllowing and stops the old containers:

WUXT_PORT_FRONTEND=4000
WUXT_PORT_BACKEND=4080
WUXT_PORT_DIST=9080
WUXT_MYSQL_CONTAINER=mysql.projectname
WUXT_WP_CONTAINER=wp.projectname
WUXT_NUXT_CONTAINER=front.projectname

After running the script start the new containers

docker-compose up -d

Setup WordPress

In short:

Install WordPress (http://localhost:3080/install.php)
Set permalinks to Post name (http://localhost:3080/wp-admin/options-permalink.php)
Activate wuxt-theme (http://localhost:3080/wp-admin/themes.php)

Do a common WordPress installation at http://localhost:3080/install.php, then login to wp-admin and select the wuxt theme to activate all the API extensions. Additionally you might want to activate the ACF plugin to make your meta-value work easier. Last but not least you have to set the permalink structure to "Post Name" in the WordPress settings.

To check if everything is running, visit http://localhost:3080 and verify that the wuxt info screen is showing.

Then check that the Rest API at http://localhost:3080/wp-json is returning a JSON-object you are good to go.

Setup nuxt.js

Nuxt should have been started automatically inside the docker container. The command we use for running the nuxt.js server is yarn dev. Check if the front-end is running by opening http://localhost:3000. You should be greeted by the Wuxt intro-screen.

Check if BrowserSync is running, by doing a minor change to the front-page. The change should directly be visible on the front-page without manually reloading the page.

Generate and Deploy

To make a complete deploy of WUXT, you have to get at least one server and solve a lot of configuration stuff to get WordPress, MySql and nuxt.js running (we are working on a manual for some of the big cloud services).

However, there is an easier solution, at least without on-site user generated content, like WordPress-comments (disqus would be ok, though). We have tweaked the nuxt.js generate-command, so that you can generate a fully static site with all your content, posts and pages inside the dist directory of nuxt. Then it's only a matter of getting the static html-site uploaded to a webspace of your choice.

Generating a fully static site

First be sure your containers are running

docker-compose up -d

Then go to the wuxt root-directory and run generate with yarn

yarn generate

Despite generating your static site, this commands runs some docker-compose action, so while generating, your WUXT site will be down and started again after.

After the generation there will be started a small local web-server, which deploys the static site on

http://localhost:8080

To get the files you go to the dist directory inside your wuxt/nuxt directory:

wuxt/nuxt/dist

To shut down the local web-server you have to run the following command insie the wuxt directory:

docker-compose -f dist.yml down

How it works

The generate-command simply scrapes all available urls you added to your nuxt.js and WordPress installation, saves the html-output and caches the JSON-requests to the WordPress Rest API.

To know which urls are available, the generate command asks the WordPress Rest API for a list of existing endpoints and all links used in the WordPress menus. You can view that list with the following endpoint:

GET: /wp-json/wuxt/v1/generate

Since nuxt.js doesn't fully support 100% static sites yet, we have to get help of the static plugin used on nuxt.org, which is jsut taking care of the payload caching. Read more here and here.

WordPress Rest API endpoints

The WordPress Rest API gives you access to a wide range of native endpoints. Find the docs at: https://developer.wordpress.org/rest-api/reference/. To easily access the endpoints from nuxt.js you can use the $wp extension, which integrates the node-wpapi library. You can find the full documentation here.

Extensions to the API endpoints

To make wuxt even more easy to use, there are a bunch of endpoint extensions to the WordPress Rest API.

Front-page

$wp.frontPage()
$wp.frontPage().embed()

GET: /wp-json/wuxt/v1/front-page
GET: /wp-json/wuxt/v1/front-page?_embed

You can use the WordPress front-page settings to build your front-ends first page. If you setup the front-page in WordPress as static page, the endpoint will return the corresponing page object.

If there is no front-page configured, the query automatically returns the result of the default posts query

GET /wp-json/wp/v2/posts

Note that the _embed parameter works for the front-page query, which gives you access to featured media (post-thumbnails), author information and more.

Menus

$wp.menu()
$wp.menu().locati

Wuxt

Install / Use

README