Spinning Up a WordPress Local Environment with 10up WP-Scaffold and @wordpress/env

While researching starter themes for WordPress Block-based Themes, I came across the 10up wp-scaffold. I decided to try spinning up an environment using the @wordpress/env tool (which I have not done before). Even though 10up provided instructions for installation, I still ran into some issues due to not being familiar with how wp-env works. Below are the steps I took to get this successfully up and running.

Resources

• 10up wp-scaffold repo
• Guides for using wp-env:
  • Get started with wp-env
  • @wordpress/env documentation

Prerequisites/Set up

1. Make sure these are installed on your machine:
   1. Node & npm
   2. Docker
   3. Git
2. A Github account, with your machine’s ssh key added to your account.
   • How to add your ssh key to your github account..
3. Once Docker is running, install the wp-env package globally
   1. Using terminal, run:
      • npm -g i @wordpress/env

Steps for spinning up the 10up wp-scaffold

Clone the 10up Scaffold into your project

1. Create a project folder on your machine and add a wp-content folder inside
2. Using terminal, cd into /wp-content
3. Within /wp-content, run:
   • npx 10up-toolkit project init
     Note: I ran into some issues with my node and npm versions, I ended up switching Node to version 20 and npm to version 10.
4. Answer the following prompts:
   1. Create a project name: {what ever you want}
   2. Project template: Standard WP
   3. CI type: None
5. Within /wp-content run:
   • composer install
   • npm install

Set up a .wp-env file for your project

Within /wp-content add a .wp-env.json file with configurations set up (see example)

• update “themes” path to the path of your theme:

{
  "core": null,
  "phpVersion": null,
  "mysqlPort": null,
  "plugins": [],
  "themes": ["./themes/<your-theme>"],
  "config": {
    "WP_DEBUG": true,
    "WP_DEBUG_DISPLAY": true,
    "WP_DISABLE_FATAL_ERROR_HANDLER": true,
    "SCRIPT_DEBUG": true
  },
  "env": {
    "development": {
      "themes": ["./themes/<your-theme>"]
    },
    "tests": {
      "config": {
        "WP_DEBUG": true,
        "WP_DEBUG_DISPLAY": true,
        "WP_DISABLE_FATAL_ERROR_HANDLER": true,
        "SCRIPT_DEBUG": true
      }
    }
  }
}

Install composer within your theme

1. cd into themes/yourtheme-theme 
2. In the theme folder /yourtheme-theme, run:
   • composer install

Start the Wp Env

1. Cd back to /wp-content, run:
   • wp-env start
2. Once the Docker environment is set up, login to the WordPress admin and activate your theme:
   1. Login: http://localhost:8888/wp-admin
   2. Un: admin
   3. Pw: password

To edit the theme files:

1. Inside /wp-content open package.json and edit the “watch:theme” and make sure the path is set to your theme.
2. Run npm run watch:theme

Troubleshooting

My biggest advice is to read the 10up-toolkit documentation for further ways to modify environment and troubleshoot issues. Below are some issues I ran into:

Tips

• Turn off Prettier vscode extension for this project.
  • add a .prettierignore file with “**”
• modify .eslintrc to relax linting

{
    "extends": ["@10up/eslint-config/wordpress"],
    "rules": {
        "no-unused-vars": "warn",
        "react/self-closing-comp": "off",
        "prettier/prettier": "off"
      }
}

• Read the HMR and Fast Refresh section for fixing any issues there
  • I couldn’t get this to work on my environment.
  • If HMR is reloading page over and over again try updating the refresh webpack plugin: `npm install @pmmmwh/react-refresh-webpack-plugin@0.5.11 react-refresh@0.11.0 –save-dev`
• Style Linting issues: read documentation about @10up/stylelint-config
  • Note: in the css folder you can add .scss files but you need to set up the additional configurations to get it to work