@wordpress/env is a powerful tool designed to streamline the WordPress development process. This utility enables developers to rapidly create consistent, reproducible WordPress environments for building and testing plugins and themes. Key benefits of @wordpress/env include:
- Efficient setup: Create a fully functional WordPress environment in minutes.
- Environment consistency: Maintain uniform development environments across teams and projects.
- Flexible configuration testing: Easily switch between WordPress and PHP versions.
- Seamless workflow integration: Compatible with existing development tools and processes.
In this guide, we’ll walk you through the fundamentals of @wordpress/env and demonstrate how it can optimize your WordPress development workflow.
1. Prerequisites
Before we dive in, make sure you have the following installed:
- Docker
- Node.js
- Git
2.1 Global setup/installation
You can install @wordpress/env globally using npm:
npm -g i @wordpress/env
2.2 Local Setup with package.json
If you prefer to use @wordpress/env as a local package in your project, follow these steps:
- Install @wordpress/env as a dev dependency:
npm install @wordpress/env --save-dev
- Add scripts to your package.json file:
{
"scripts": {
"start": "wp-env start",
"stop": "wp-env stop",
"destroy": "wp-env destroy"
}
}
- Now you can use npm run commands to manage your environment
npm run start
npm run stop
npm run destroy
3. Quick Start
To get started, navigate to your plugin or theme directory and run:
wp-env start
This will set up a local WordPress environment at http://localhost:8888 (username: admin, password: password).
4. Configuration with .wp-env.json
Create a .wp-env.json file in your project root to customize your environment. Here’s a basic example:
{
"core": null,
"plugins": [ ".", "gutenberg", "woocommerce" ],
"themes": [ "./my-custom-theme" ]
}
This configuration uses the latest WordPress version, installs your current directory as a plugin, and installs a theme from the “my-custom-theme” directory.
You can also use any plugins and themes from the WordPress directory; you can add the theme or plugin slug to the plugins and themes arrays.
5. Common Commands
- Start the environment:
wp-env start - Stop the environment:
wp-env stop - Run WP-CLI commands:
wp-env run cli wp user list - Access the environment: http://localhost:8888 (default)
6. Advanced Usage
- Custom ports: Set
"port": 3000in your .wp-env.json - Specific PHP version: Set
"phpVersion": "7.4" - Map additional directories: Use the
"mappings"option. (Mapping of WordPress directories to local directories to be mounted in the WordPress instance. ) - Map wp-config.php constants to their desired values, use
"configs"option
7. Troubleshooting
If you encounter issues:
- Check that Docker is running
- Verify the port numbers
- Try
wp-env start --updateto download updates - Restart Docker
- As a last resort, use
wp-env destroyand start fresh
Further read:
- @wordpress/env – Block Editor Handbook | Developer.WordPress.org
- Docker Desktop | Docker Docs
- Quick and easy local WordPress development with wp-env – WordPress Developer Blog
- wp-env: Simple Local Environments for WordPress. – Make WordPress Core
Conclusion
@wordpress/env simplifies setting up a local WordPress development environment. With its easy-to-use commands and flexible configuration options, you can focus on building great plugins and themes without worrying about complex server setups.
Happy coding!