Local WordPress Development
Testing in production is never a good idea, especially with a team of developers who've never used WordPress before. In order to avoid testing new custom blocks on the production WordPress site while still in development, we use wp-env to launch a local WordPress instance (in Docker) with the required plugins and styling such that we can test custom blocks and ACF features locally.
This tooling feature is tracked in https://github.com/Code-4-Community/nefac/issues/66 and was originally implemented by Troy.
- Docker Desktop
- A recent NodeJS installation
- NPM
- Basic familiarity with Faust.js and related technologies (see https://github.com/Code-4-Community/nefac/wiki/WordPress-Concepts)
Aside from Docker, you should already have most of these prerequisites installed from working on the website.
If you haven't already, clone this repository, and cd into its root directory.
Install wp-env globally. Official documentation about this step can be found here.
npm i -g @wordpress/env
Enter the wp-env directory in the repo, and start the WordPress environment. It may take some time to boot up.
Tip
If you just installed Docker, you will most likely need to restart your computer before being able to proceed. Also make sure that Docker Desktop is running (even if just in the background). Haven't installed it yet? Scroll back up to Prerequisites!
cd wp-env
wp-env start
Eventually, the bootup should complete and you should be greeted with a success message showing what's running on which ports, like this:
WordPress development site started at http://localhost:8888
WordPress test site started at http://localhost:8889
MySQL is listening on port 60223
MySQL for automated testing is listening on port 60272
√ Done! (in 153s 730ms)
We aren't using the automated testing features, so you can ignore those. Continue to the next section.
Note
Remember to shut down wp-env when you're done!
Open the login page of your WordPress instance: http://localhost:8888/wp-admin
The default credentials are:
- Username:
admin - Password:
password
From the admin dashboard, you can change settings, add/edit plugins, add/edit site content, and do anything else you'd like to do. Changes you make within this WordPress instance will not be tracked in git.
In this section, we will see how the local WordPress environment we have set up can be used for locally testing custom Faust.js blocks.
cd into the nefac-website directory of our repo. Follow the usual setup instructions from https://github.com/Code-4-Community/nefac/blob/main/README.md. Afterwards, all your dependencies should be installed.
.env file in this directory to use the local environment's URL and credentials instead of the corresponding production values. You can copy these from right here (they're not sensitive since they only work locally):
# Your WordPress site URL
NEXT_PUBLIC_WORDPRESS_URL=http://localhost:8888
# Plugin secret found in WordPress Settings->Faust
FAUST_SECRET_KEY=38a76cc8-4d12-4489-985a-cd25f1b3cfabRun Faust.js' blockset utility. You should see a success message when this operation is finished.
npx faust blockset
Return to the wp-admin dashboard in your browser. In the left-hand sidebar, click "Add Page" under the "Pages" menu:
Now, attempt to insert your custom block on the page using the block editor GUI. You can add new blocks by typing "/" in the text editor field.
After clicking the Publish or Save button, you should be able to open the live page in a new tab and see the rendered version of the block.
Does it work? It should! If not, reach out to the TL for support.
To shut down the local WordPress containers, cd back to wp-env and run:
wp-env stop
If you want to delete the containers entirely, perhaps to free up storage or to reset the state of your local environment (which is otherwise persistent), run:
wp-env destroy
This command will ask for your confirmation; if your goal is to locally delete the containers, you can safely enter 'y'.
There is more official documentation about this process here and here.
TODO