«Blog
•
Theme Development
•
Tutorial

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

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.
  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 CSS and JS 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

Tips:

The Linting rules are very strict out of the box, if you want to prevent the build from failing when linting issues arise and autofix fixable rules then add a webpack.config.js file to the root

import StyleLintPlugin from 'stylelint-webpack-plugin';

module.exports = {
  plugins: [
    new StyleLintPlugin({
      configFile: ".stylelintrc", // use ".stylelintrc.js" or "stylelint.config.js" if that's what you have
      files: "themes/amalt-theme/assets/css/**/*.scss", // adjust this to match your SCSS file locations
      fix: true, // auto-fix fixable rules
      failOnError: false, // optionally prevent build from failing
    }),
  ],
};

You can also add a .stylelintrc to the root, to turn off some of the linting rules

{
  "extends": [
    "stylelint-config-standard-scss",
    "@10up/stylelint-config/scss"
  ],
  "rules": [
    "color-named": null,
    "alpha-value-notation": null,
    "color-function-notation": null,
    "length-zero-no-unit": null,
    "font-weight-notation": null,
    "selector-class-pattern": null,
    "rule-empty-line-before": null,
    "selector-nested-pattern": null,
    "selector-pseudo-element-colon-notation": null,
    "declaration-block-semicolon-newline-after": null,
    "indentation": null
  ]
}

Scaffold a new block

To add a new block, cd into the theme and run: npm run scaffold:block my-block -- --namespace=mytheme

Tips:

Inner Blocks

The 10up Toolkit block scaffold generates a dynamic block. There is no save.js file, and the frontend is rendered in markup.php. If you have a block with Inner Blocks, you will need to update the index.js file’s save function so that the InnerBlocks.Content will be rendered on the frontend:

registerBlockType(metadata.name, {
	...metadata,
	edit: BlockEdit,
	save: () => <InnerBlocks.Content />, // required for dynamic blocks
});

CSS

Remove the style.scss from the /blocks folder and add it to the assets/blocks/<your block namespace>/your-block-name.scss. This will only add the CSS for your block when the block is on the page.

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"
      }
}

Troubleshooting HMR Issues

Probably the biggest headache is getting this to work in the local environment. First thing to do is read the HMR and Fast Refresh section to see if any of the configurations and troubleshooting steps works for you. Here are some steps to make it work in my environment

  • I added the devURL to the package.json in the root.
  "10up-toolkit": {
    "devURL": "http://localhost:8889"
  }
  • I ran into an issue where HMR started reloading the page over and over again, here are steps to fix
    • try updating the refresh webpack plugin: `npm install @pmmmwh/react-refresh-webpack-plugin@0.5.11 react-refresh@0.11.0 –save-dev`
    • do a hard refresh

Style linting issues

  • 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

Block Development Issues

  • If you run into issues with blocks youc an try stopping the npm watch and restarting
  • Stoping the watch and deleting the /dist folder then re-running the npm watch:theme command.

Comments

Reply to post

Your comment will be revised by the site if needed.