diff --git a/docs/getting-started/devenv/README.md b/docs/getting-started/devenv/README.md index 7c55bcb6393f1..1fafd53af1130 100644 --- a/docs/getting-started/devenv/README.md +++ b/docs/getting-started/devenv/README.md @@ -1,228 +1,51 @@ -# Development Environment +# Block Development Environment -This guide is for setting up your local environment for JavaScript development for creating plugins and tools to extend WordPress and the block editor. If you are looking to contribute to Gutenberg project itself, see additional documentation in the [Getting Started guide](/docs/contributors/code/getting-started-with-code-contribution.md). +This guide will help you set up the right development environment to create blocks and other plugins that extend and modify the Block Editor in WordPress. -A development environment is a catch-all term for what you need setup on your computer to work. The three main pieces needed for our development environment are: +To contribute to the Gutenberg project itself, refer to the additional documentation in the [code contribution guide](/docs/contributors/code/getting-started-with-code-contribution.md).` -1. Node/NPM Development Tools -2. WordPress Development Site -3. Code Editor +A block development environment includes the tools you need on your computer to successfully develop for the Block Editor. The three essential requirements are: -## Quick Start +1. [Code editor](#code-editor) +2. [Node.js development tools](#nodejs-development-tools) +3. [Local WordPress environment (site)](#local-wordpress-environment) -Here is a summary of the guide. See each section for additional details and explanations. +## Code editor -**1. Install Node development tools** +A code editor is used to write code, and you can use whichever editor you're most comfortable with. The key is having a way to open, edit, and save text files. -Download and install [Node Version Manager](https://github.com/nvm-sh/nvm) (nvm) +If you do not already have a preferred code editor, [Visual Studio Code](https://code.visualstudio.com/) (VS Code) is a popular choice for JavaScript development among Core contributors. It works well across the three major platforms (Windows, Linux, and Mac) and is open-source and actively maintained by Microsoft. VS Code also has a vibrant community providing plugins and extensions, including many for WordPress development. -``` -curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash -``` +## Node.js development tools -Quit and restart terminal -Install Node.js v16. +Node.js (`node`) is an open-source runtime environment that allows you to execute JavaScript outside of the web browser. While Node.js is not required for all WordPress JavaScript development, it's essential when working with modern JavaScript tools and developing for the Block Editor. -``` -nvm install 16 -``` +Node.js and its accompanying development tools allow you to: -**2. WordPress Development Site** +- Install and run WordPress packages needed for Block Editor development, such as `wp-scripts` +- Setup local WordPress environments with `wp-env` and `wp-now` +- Use the latest ECMAScript features and write code in ESNext +- Lint, format, and test JavaScript code +- Scaffold custom blocks with the `create-block` package -First download, install, and start [Docker Desktop](https://www.docker.com/products/docker-desktop) following the instructions for your OS. +The list goes on. While modern JavaScript development can be challenging, WordPress provides several tools, like [`wp-scripts`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/) and [`create-block`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-create-block/), that streamline the process and are made possible by Node.js development tools. -- Install WordPress environment tool +**The recommended Node.js version for block development is [Active LTS](https://nodejs.dev/en/about/releases/) (Long Term Support)**. However, there are times when you need to to use different versions. A Node.js version manager tool like `nvm` is strongly recommended and allows you to easily change your `node` version when required. You will also need Node Package Manager (`npm`) and the Node Package eXecute (`npx`) to work with some WordPress packages. Both are installed automatically with Node.js. -``` -npm -g install @wordpress/env -``` +To install Node.js development tools and learn more about each, refer to the links below. -Start the environment from an existing plugin or theme directory, or a new working directory: +- [Install Node.js for Mac and Linux](/docs/getting-started/devenv/nodejs-development-tools.md#mac-and-linux-installations) +- [Install Node.js for Windows](/docs/getting-started/devenv/nodejs-development-tools.md#windows-or-alternative-installs) -``` -wp-env start -``` +## Local WordPress environment -You will have a full WordPress site installed, navigate to: http://localhost:8888/ using your browser, log in to the WordPress dashboard at http://localhost:8888/wp-admin/ using Username "admin" and Password "password", without the quotes. +A local WordPress environment (site) provides a controlled, efficient, and secure space for development, allowing you to build and test your code before deploying it to a production site. The [same requirements](https://en-gb.wordpress.org/about/requirements/) for WordPress apply to local sites. -**3. Code Editor** +Many tools are available for setting up a local WordPress environment on your computer. The Block Editor Handbook covers `wp-env` and `wp-now`, both of which are open-source and maintained by the WordPress project itself. -You can use any text editor to write code. For example, [Visual Studio Code](https://code.visualstudio.com/) is a popular open-source editor. You can follow instructions on their site to install it for your OS. +Refer to the individual guides below for setup instructions. -## Node Development Tools +- [Get started with `wp-env`](/docs/getting-started/devenv/get-started-with-wp-env.md) +- [Get started with `wp-now`](/docs/getting-started/devenv/get-started-with-wp-now.md) -The tools needed for development are **Node** and **NPM**. **Nodejs** is a runtime environment that allows running JavaScript outside of the browser. NPM is the Node Package Manager, it is used for installing dependencies and running scripts. The script `npx` is also installed with Nodejs—this script is used to run packages not yet installed—we will use `npx` to bootstrap a block. - -The tools are used to convert the JavaScript we are going to write into a format that browsers can run. This is called transpiling or the build step. - -For Mac and Linux, it is recommended to use the [Node Version Manager](https://github.com/nvm-sh/nvm) (nvm). Using `nvm` to install node allows installing specific versions, plus installs locally in your home directory and avoids any global permission issues. - -For Windows, or alternative installs, you can [download a Nodejs installer](https://nodejs.org/en/download/) directly from the main Node.js website, v14 is recommended. Installers are available for Windows and Mac, and binaries available for Linux. See Node.js site for additional installation methods. - -Here are the quick instructions to install using nvm, see the [full installation instructions](https://github.com/nvm-sh/nvm#installing-and-updating) for additional details. - -Run the following on the command-line to install nvm: - -```sh -curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash -``` - -Note: On macOS, the required developer tools are not installed by default, if not already installed you may be prompted to download the install. - -Mac git command requires command line developer tools - -After installing nvm, you need to use it to install Node.js, to install v16, run: - -```sh -nvm install 16 -``` - -If there is an error running the above command, for example a common error that occurs is: - -```sh -$ nvm install 16 -zsh: command not found: nvm -``` - -First, try quitting and restarting your terminal to pick up the installed config. - -If restarting did not resolve the problem, you might need to create the default profile file. - -On macOS Catalina, the default shell is zsh, to create the profile file type `touch ~/.zshrc` on the command-line. It is fine to run if the file already exists. Note, `~/` is a shortcut to your home directory. For Ubuntu, including WSL, the default profile is bash, use `touch ~/.bashrc` to create. - -After creating the profile file, re-run the install command: - -```sh -nvm install 16 -``` - -The important part after installing is being able to use them in your terminal. Open a terminal command-line and type `node -v` and `npm -v` to confirm they are installed. - -```sh -> node -v -v16.20.1 - -> npm -v -8.19.4 -``` - -Your versions may not match exactly, that is fine. The minimum version for Node.js is >= 12 and for npm >= 6.9, using v14 will be supported until upgrade is required. - -## WordPress Development Site - -There are several ways to run WordPress locally on your own computer, or you could even develop on a cloud hosted computer, though this may be slower. - -The WordPress [wp-env package](https://www.npmjs.com/package/@wordpress/env) lets you set up a local WordPress environment for building and testing plugins and themes, without any additional configuration. - -The `wp-env` tool uses Docker to create a virtual machine that runs the WordPress site. There are instructions available for installing Docker on [Windows 10 Pro](https://docs.docker.com/docker-for-windows/install/), [other versions of Windows 10](https://docs.docker.com/docker-for-windows/wsl/), [macOS](https://docs.docker.com/docker-for-mac/install/), and [Linux](https://docs.docker.com/v17.12/install/linux/docker-ce/ubuntu/#install-using-the-convenience-script). If using Ubuntu, see our additional notes for [help installing Docker on Ubuntu](/docs/getting-started/devenv/docker-ubuntu.md). - -After you have installed Docker, go ahead and install the `wp-env` tool. This command will install the tool globally, which means you can run it from any directory: - -```sh -npm -g install @wordpress/env -``` - -To confirm it is installed and available, run: - -```sh -wp-env --version -> 1.6.0 -``` - -The `wp-env` script is used to create a Docker WordPress environment. You can use this script to start an environment with your plugin activated by running it from the directory containing your plugin. For example if you are following the create block tutorial, this would be in the generated directory like so: - -```sh -npx @wordpress/create-block starter-block -cd starter-block -wp-env start -``` - -You can access your environment in your browser at: [http://localhost:8888/](http://localhost:8888/), the default username is `admin` and default password is `password`. For more information controlling the Docker environment see the [@wordpress/env package readme](/packages/env/README.md). - -When using the script while developing a single plugin, `wp-env start` can mount and activate the plugin automatically when run from the directory containing the plugin. Note: This also works for themes when run from the directory in which you are developing the theme. - -If you run `wp-env start` from a directory that is not a plugin or theme, a generic WordPress environment will be created. The script will display the following warning, it is fine if this is your intention. - -``` -!! Warning: could not find a .wp-env.json configuration file and could not determine if 'DIR' is a WordPress installation, a plugin, or a theme. -``` - -You can use the `.wp-env.json` configuration file to create an environment that works with multiple plugins and/or themes. See the [@wordpress/env package for additional details](/packages/env/README.md#wp-envjson). - -#### Troubleshooting - -A common issue when running `wp-env` is `Error while running docker-compose command.` - -- Check that Docker Desktop is started and running. -- Check Docker Desktop dashboard for logs, restart, or remove existing VMs. - -If you see the error: `Host is already in use by another container` - -- The container is already running, or another one is. You can stop an existing container running use `wp-env stop` from the directory you started it. -- If you do not remember the directory you started wp-env in, you can stop all containers with `docker stop $(docker ps -q)`. Please note, this will stop all containers, use caution with this command. - -### Alternative to Docker - -Docker is just one method to run a local WordPress environment. Block development and extending WordPress is done using normal plugins, so any WordPress environment can be used. Here are some alternatives that you can consider which do not require installing Docker. - -- [Local](https://localwp.com/) - Local is a single application you download and install. You will need to know where the plugin directory is located after install. If you create a site called `mywp` typically the plugin directory is installed at `~\Local Sites\mywp\app\public\wp-content\plugins`. When working with gutenberg it is recommended to place your install in your own gutenberg folder. This avoids potential issue with the build processes. - -- [WampServer](http://www.wampserver.com/en/) or [MAMP](https://www.mamp.info/) environments, both are quite similar to Local, combining a web server, PHP, and database. However these tools are not WordPress specific, so if you are not already using them, Local might be an easier option. - -- Remote server - you can work on a remote server, most hosts provide a quick WordPress setup. However, this will require additional time thorughout development syncing to the server, or working directly on the remote server. - -The important part is having a WordPress site installed, and know where and how to update files in the plugins directory. - -## Code Editor - -[Visual Studio Code](https://code.visualstudio.com/) is a popular code editor for JavaScript development. It works quite well across the three major platforms (Windows, Linux, and Mac), it is open-source and actively maintained by Microsoft. Plus Visual Studio Code has a vibrant community providing plugins and extensions; it is becoming the defacto standard for web development. - -Alternative editors include [Sublime Text](https://www.sublimetext.com/) that is also available across platforms, though is a commercial product; or other free alternatives include [Vim](https://www.vim.org/), [Atom](https://atom.io/), and [Notepad++](https://notepad-plus-plus.org/) all support standard JavaScript style development. - -You can use any editor you're comfortable with, it is more a personal preference. The development setup for WordPress block editor is a common JavaScript environment and most editors have plugins and support. The key is having a way to open, edit, and save text files. - -## Uninstall - Start Over - -Here are a few instructions if you need to start over, or want to remove what was installed. - -### Local Environment - -- If you just want to reset and clean the WordPress database: - -``` -wp-env clean all -``` - -- To remove the local environment completely for a specific project: - -``` -wp-env destroy -``` - -- To completely uninstall wp-env tool: - -``` -npm -g uninstall @wordpress/env -``` - -- To uninstall Docker, or Visual Studio Code use your OS method to remove packages. For example, on Windows run "Add or remove programs". You can additionally uninstall from the Docker Desktop app, click the bug icon at the top to switch to this Troubleshoot screen. Click Uninstall or remove. - -![Docker Troubleshoot Screenshot](https://developer.wordpress.org/files/2020/08/docker-uninstall-screen.png) - -### Uninstall Node/NVM - -To uninstall Node/NVM, delete the NVM directory, this is typically installed at `$HOME/.nvm`, delete using - -``` -rm -rf "$HOME/.nvm" -``` - -If this does not work and the `$NVM_DIR` environment variable is set you can remove using `rm -rf "$NVM_DIR"` - -To clean up any installed JavaScript packages remove the global `.npm` directory at `$HOME/.npm`, - -``` -rm -rf "$HOME/.npm" -``` - -Just as you confirmed the installation worked, you can confirm the uninstall worked. First quit and restart terminal and then try to run `npm -v`, `node -v`, and `nvm -v` you should then see a "command not found" error in the terminal. +Of the two, `wp-env` is the more solid and complete solution. It's also the recommended tool for Gutenberg development. On the other hand, `wp-now` offers a simplified setup but is more limited than `wp-env`. Both are valid options, so the choice is yours. diff --git a/docs/getting-started/devenv/docker-ubuntu.md b/docs/getting-started/devenv/docker-ubuntu.md deleted file mode 100644 index 680798d74f4e8..0000000000000 --- a/docs/getting-started/devenv/docker-ubuntu.md +++ /dev/null @@ -1,60 +0,0 @@ -# How to setup local WordPress environment on Ubuntu - -This article covers setting up the local WordPress development environment using Docker on Ubuntu. - -For Ubuntu 20.04.1, the standard docker binaries in the repository work as needed: - -``` -sudo apt install docker.io docker-compose -``` - -For earlier versions of Ubuntu, the docker binaries included in repositories did not support the features needed for the WordPress environment. - -- For Ubuntu prior to 20.04.1, follow these [directions from Docker to install](https://docs.docker.com/install/linux/docker-ce/ubuntu/). Additionally `docker-compose` is required, you may need to install separately, see [ Docker compose documentation](https://docs.docker.com/compose/install/). - -## Troubleshooting - -If you run into this error, when running `npm run wp-env` from the Gutenberg directory: - -``` -ERROR: Couldn't connect to Docker daemon at http+docker://localhost - is it running? - -If it's at a non-standard location, specify the URL with the DOCKER_HOST environment variable. -``` - -First, make sure docker is running. You can check using `ps -ef | grep docker` which should show something like: - -``` -/usr/bin/dockerd -H fd:// --containerd=/run/containerd/containerd.sock -``` - -If docker is not running, try to start the service using: - -``` -sudo systemctl start docker.service -``` - -If docker is running, then it is not listening how the WordPress environment is trying to communicate. Try adding the following service override file to include listening on tcp. See [this Docker documentation](https://docs.docker.com/config/daemon/remote-access/) on how to configure remote access for Docker daemon. - -``` -# /etc/systemd/system/docker.service.d/override.conf -[Service] -ExecStart= -ExecStart=/usr/bin/dockerd -H fd:// -H tcp://0.0.0.0:2376 -``` - -Restart the service from the command-line - -``` -sudo systemctl daemon-reload -sudo systemctl restart docker.service -``` - -After restarting the services, set the environment variable DOCKER_HOST and try starting using: - -``` -export DOCKER_HOST=tcp://127.0.0.1:2376 -npm run wp-env start -``` - -Your environment should be setup at: http://localhost:8888/ diff --git a/docs/getting-started/devenv/get-started-with-wp-env.md b/docs/getting-started/devenv/get-started-with-wp-env.md new file mode 100644 index 0000000000000..dca3ca081317d --- /dev/null +++ b/docs/getting-started/devenv/get-started-with-wp-env.md @@ -0,0 +1,140 @@ +# Get started with wp-env + +The [@wordpress/env](https://www.npmjs.com/package/@wordpress/env) package (`wp-env`) lets you set up a local WordPress environment (site) for building and testing plugins and themes, without any additional configuration. + +Before following this guide, install [Node.js development tools](/docs/getting-started/devenv#install-nodejs-development-tools) if you have not already done so. + +## Quick start + +1. Download, install, and start [Docker Desktop](https://www.docker.com/products/docker-desktop) following the instructions for your operating system. +2. Run `npm -g install @wordpress/env` in the terminal to install `wp-env` globally. +3. In the terminal, navigate to an existing plugin directory, theme directory, or a new working directory. +4. Run `wp-env start` in the terminal to start the local WordPress environment. +5. After the script runs, navigate to `http://localhost:8888/wp-admin/` and log into the WordPress dashboard using username `admin` and password `password`. + +## Set up Docker Desktop + +The `wp-env` tool uses [Docker](https://www.docker.com/) to create a virtual machine that runs the local WordPress site. The Docker Desktop application is free for small businesses, personal use, education, and non-commercial open-source projects. See their [FAQ](https://docs.docker.com/desktop/faqs/general/#do-i-need-to-pay-to-use-docker-desktop) for more information. + +Use the links below to download and install Docker Desktop for your operating system. + +- [Docker Desktop for Mac](https://docs.docker.com/desktop/install/mac-install/) +- [Docker Desktop for Windows](https://docs.docker.com/desktop/install/windows-install/) +- [Docker Desktop for Linux](https://docs.docker.com/desktop/install/linux-install/) + +If you are using a version of Ubuntu prior to 20.04.1, see the additional [troubleshooting notes](#ubuntu-docker-setup) below. + +After successful installation, start the Docker Desktop application and follow the prompts to get set up. You should generally use the recommended (default) settings, and creating a Docker account is optional. + +## Install and run `wp-env` + +The `wp-env` tool is used to create a local WordPress environment with Docker. So, after you have set up Docker Desktop, open the terminal and install the `wp-env` by running the command: + +```sh +npm -g install @wordpress/env +``` + +This will install the `wp-env` globally, allowing the tool to be run from any directory. To confirm it's installed and available, run `wp-env --version`, and the version number should appear. + +Next, navigate to an existing plugin directory, theme directory, or a new working directory in the terminal and run: + +```sh +wp-env start +``` + +Once the script completes, you can access the local environment at: `http://localhost:8888`. Log into the WordPress dashboard using username `admin` and password `password`. + +
+ Some projects, like Gutenberg, include their own specific wp-env configurations, and the documentation might prompt you to run npm run start wp-env instead. +
+ +For more information on controlling the Docker environment, see the [@wordpress/env package](/packages/env/README.md) readme. + +### Where to run `wp-env` + +The `wp-env` tool can run from practically anywhere. When using the script while developing a single plugin, `wp-env start` can mount and activate the plugin automatically when run from the directory containing the plugin. This also works for themes when run from the directory in which you are developing the theme. + +A generic WordPress environment will be created if you run `wp-env start` from a directory that is not a plugin or theme. The script will display the following warning, but ignore if this is your intention. + +``` +!! Warning: could not find a .wp-env.json configuration file and could not determine if 'DIR' is a WordPress installation, a plugin, or a theme. +``` + +You can also use the `.wp-env.json` configuration file to create an environment that works with multiple plugins and/or themes. See the [@wordpress/env package](/packages/env/README.md#wp-envjson) readme for more configuration details. + +### Uninstall or reset `wp-env` + +Here are a few instructions if you need to start over or want to remove what was installed. + +- If you just want to reset and clean the WordPress database, run `wp-env clean all` +- To remove the local environment completely for a specific project, run `wp-env destroy` +- To globally uninstall the `wp-env` tool, run `npm -g uninstall @wordpress/env` + +## Troubleshooting + +### Common errors + +When using `wp-env`, it's common to get the error: `Error while running docker-compose command` + +- Check that Docker Desktop is started and running. +- Check Docker Desktop dashboard for logs, restart, or remove existing virtual machines. +- Then try rerunning `wp-env start`. + +If you see the error: `Host is already in use by another container` + +- The container you are attempting to start is already running, or another container is. You can stop an existing container by running `wp-env stop` from the directory that you started it in. +- If you do not remember the directory where you started `wp-env`, you can stop all containers by running `docker stop $(docker ps -q)`. This will stop all Docker containers, so use with caution. +- Then try rerunning `wp-env start`. + +### Ubuntu Docker setup + +If you are using a version of Ubuntu prior to 20.04.1, you may encounter errors when setting up a local WordPress environment with `wp-env`. + +To resolve this, start by following the [installation guide](https://docs.docker.com/install/linux/docker-ce/ubuntu/) from Docker. `docker-compose` is also required, which you may need to install separately. Refer to the [Docker compose documentation](https://docs.docker.com/compose/install/). + +Once Docker and `wp-env` are installed, and assuming `wp-env` is configured globally, try running `wp-env start` in a directory. If you run into this error: + +``` +ERROR: Couldn't connect to Docker daemon at http+docker://localhost - is it running? + +If it's at a non-standard location, specify the URL with the DOCKER_HOST environment variable. +``` + +First, make sure Docker is running. You can check by running `ps -ef | grep docker`, which should return something like: + +``` +/usr/bin/dockerd -H fd:// --containerd=/run/containerd/containerd.sock +``` + +If Docker is not running, try starting the service by running `sudo systemctl start docker.service`. + +If Docker is running, then it is not listening to how the WordPress environment is trying to communicate. Try adding the following service override file to include listening on `tcp`. See [this Docker documentation](https://docs.docker.com/config/daemon/remote-access/) on how to configure remote access for Docker daemon. + +``` +# /etc/systemd/system/docker.service.d/override.conf +[Service] +ExecStart= +ExecStart=/usr/bin/dockerd -H fd:// -H tcp://0.0.0.0:2376 +``` + +Restart the service from the command-line: + +``` +sudo systemctl daemon-reload +sudo systemctl restart docker.service +``` + +After restarting the services, set the environment variable `DOCKER_HOST` and try starting `wp-env` with: + +``` +export DOCKER_HOST=tcp://127.0.0.1:2376 +wp-env start +``` + +Your environment should now be set up at `http://localhost:8888/`. + +## Additional resources + +- [@wordpress/env](https://www.npmjs.com/package/@wordpress/env) (Official documentation) +- [Docker Desktop](https://docs.docker.com/desktop) (Official documentation) +- [Quick and easy local WordPress development with wp-env](https://developer.wordpress.org/news/2023/03/quick-and-easy-local-wordpress-development-with-wp-env/) (WordPress Developer Blog) diff --git a/docs/getting-started/devenv/get-started-with-wp-now.md b/docs/getting-started/devenv/get-started-with-wp-now.md new file mode 100644 index 0000000000000..8b95008dae4a4 --- /dev/null +++ b/docs/getting-started/devenv/get-started-with-wp-now.md @@ -0,0 +1,66 @@ +# Get started with wp-now + +The [@wp-now/wp-now](https://www.npmjs.com/package/@wordpress/env) package (`wp-now`) is a lightweight tool powered by [WordPress Playground](https://developer.wordpress.org/playground/) that streamlines setting up a local WordPress environment. + +Before following this guide, install [Node.js development tools](/docs/getting-started/devenv#install-nodejs-development-tools) if you have not already done so. It's recommended that you use the latest version of `node`. `wp-now` requires at least `node` v18 and v20 if you intend to use its [Blueprints](https://github.com/WordPress/playground-tools/tree/trunk/packages/wp-now#using-blueprints) feature. + +## Quick start + +1. Run `npm -g install @wp-now/wp-now` in the terminal to install `wp-now` globally. +2. In the terminal, navigate to an existing plugin directory, theme directory, or a new working directory. +3. Run `wp-now start` in the terminal to start the local WordPress environment. +4. After the script runs, your default web browser will automatically open the new local site, and you'll be logged in with the username `admin` and the password `password`. + +## Install and run `wp-now` + +Under the hood, `wp-now` is powered by WordPress Playground and only requires Node.js, unlike `wp-env`, which also requires Docker. To install `wp-now`, open the terminal and run the command: + +```sh +npm -g install @wp-now/wp-now +``` + +This will install the `wp-now` globally, allowing the tool to be run from any directory. To confirm it's installed and available, run `wp-now --version`, and the version number should appear. + +Next, navigate to an existing plugin directory, theme directory, or a new working directory in the terminal and run: + +```sh +wp-now start +``` + +After the script runs, your default web browser will automatically open the new local site, and you'll be logged in with the username `admin` and the password `password`. + +
+ If you encounter any errors when running wp-now start, make sure that you are using at least node v18, or v20 if you are using the Blueprint feature. +
+ +When running `wp-now` you can also pass arguments that modify the behavior of the WordPress environment. For example, `wp-now start --wp=6.3 --php=8` will start a site running WordPress 6.3 and PHP 8, which can be useful for testing purposes. + +Refer to the [@wp-now/wp-now](https://github.com/WordPress/playground-tools/tree/trunk/packages/wp-now) documentation for all available arguments. + +### Where to run `wp-now` + +The `wp-now` tool can be used practically anywhere and has different modes depending on how the directory is set up when you run `wp-now start`. Despite the many options, when developing for the Block Editor, you will likely use: + +- `plugin`, `theme`, or `wp-content`: Loads the project files into a virtual filesystem with WordPress and a SQLite-based database. Everything (including WordPress core files, the database, wp-config.php, etc.) is stored in the user's home directory and loaded into the virtual filesystem. The mode will be determined by: + - `plugin`: Presence of a PHP file with 'Plugin Name:' in its contents. + - `theme`: Presence of a `style.css` file with 'Theme Name:' in its contents. + - `wp-content`: Presence of `/plugins` and `/themes` subdirectories. +- `playground`: If no other mode conditions are matched, `wp-now` launches a completely virtualized WordPress site. + +Refer to the [@wp-now/wp-now](https://github.com/WordPress/playground-tools/tree/trunk/packages/wp-now) documentation for a more detailed explanation of all modes. + +### Known issues + +Since `wp-now` is a relatively new tool, there are a few [known issues](https://github.com/WordPress/playground-tools/tree/trunk/packages/wp-now#known-issues) to be aware of. However, these issues are unlikely to impact most block, theme, or plugin development. + +### Uninstall or reset `wp-now` + +Here are a few instructions if you need to start over or want to remove what was installed. + +- If you just want to reset and clean the WordPress database, run `wp-now --reset` +- To globally uninstall the `wp-now` tool, run `npm -g uninstall @wp-now/wp-now` + +## Additional resources + +- [@wp-now/wp-now](https://github.com/WordPress/playground-tools/tree/trunk/packages/wp-now) (Official documentation) +- [WordPress Playground](https://developer.wordpress.org/playground/) (Developer overview) \ No newline at end of file diff --git a/docs/getting-started/devenv/nodejs-development-tools.md b/docs/getting-started/devenv/nodejs-development-tools.md new file mode 100644 index 0000000000000..09a58a1beeb06 --- /dev/null +++ b/docs/getting-started/devenv/nodejs-development-tools.md @@ -0,0 +1,50 @@ +# Node.js development tools + +When developing for the Block Editor, you will need [Node.js](https://nodejs.org/en) development tools along with a code editor and a local WordPress environment. Node.js (`node`) is an open-source runtime environment that allows you to execute JavaScript code from the terminal (also known as a command-line interface, CLI, or shell) + +Installing `node` will automatically include the Node Package Manager (`npm`) and the Node Package eXecute (`npx`), two tools you will frequently use in block and plugin development. + +Node Package Manager ([`npm`](https://docs.npmjs.com/cli/v10/commands/npm)) serves multiple purposes, including dependency management and script execution. It's the recommended package manager and is extensively featured in all documentation. + +The Node Package eXecute ([`npx`](https://docs.npmjs.com/cli/v10/commands/npx)) tool is used to run commands from packages without installing them globally and is commonly used when scaffolding blocks with the [`create-block`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-create-block/) package. + + +## Node.js installation on Mac and Linux (with `nvm`) + +It's recommended that you use [Node Version Manager](https://github.com/nvm-sh/nvm) (`nvm`) to install Node.js. This allows you to install and manage specific versions of `node`, which are installed locally in your home directory, avoiding any global permission issues. + +Here are the quick instructions for installing `node` using `nvm`. See the [complete installation guide](https://github.com/nvm-sh/nvm#installing-and-updating) for more details. + +1. Open the terminal and run the following to install `nvm`. On macOS, the required developer tools are not installed by default. Install them if prompted. + +```sh +curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash +``` + +2. Quit and restart the terminal. +3. Run `nvm install --lts` in the terminal to install the latest [LTS](https://nodejs.dev/en/about/releases/) (Long Term Support) version of Node.js. +4. Run `node -v` and `npm -v` in the terminal to verify the installed `node` and `npm` versions. + +If needed, you can also install specific versions of `node`. For example, install version 18 by running `nvm install 18`, and switch between different versions by running `nvm use [version-number]`. See the `nvm` [usage guide](https://github.com/nvm-sh/nvm#usage) for more details. + +Some projects, like Gutenberg, include an [`.nvmrc`](https://github.com/WordPress/gutenberg/blob/trunk/.nvmrc) file which specifies the version of `node` that should be used. In this case, running `nvm use` will automatically select the correct version. If the version is not yet installed, you will get an error that tells you what version needs to be added. Run `nvm install [version-number]` followed by `nvm use`. + +## Node.js installation on Windows and others + +You can [download a Node.js installer](https://nodejs.org/en/download/) directly from the main Node.js website. The latest version is recommended. Installers are available for Windows and Mac, and binaries are available for Linux. + +Microsoft also provides a [detailed guide](https://learn.microsoft.com/en-us/windows/dev-environment/javascript/nodejs-on-windows#install-nvm-windows-nodejs-and-npm) on how to install `nvm` and Node.js on Windows and WSL. + +## Troubleshooting + +If you encounter the error `zsh: command not found: nvm` when attempting to install `node`, you might need to create the default profile file. + +The default shell is `zsh` on macOS, so create the profile file by running `touch ~/.zshrc` in the terminal. It's fine to run if the file already exists. The default profile is `bash` for Ubuntu, including WSL, so use `touch ~/.bashrc` instead. Then repeat steps 2-4. + +The latest `node` version should work for most development projects, but be aware that some packages and tools have specific requirements. If you encounter issues, you might need to install and use a previous `node` version. Also, make sure to check if the project has an `.nvmrc` and use the `node` version indicated. + +## Additional resources + +- [Node.js](https://nodejs.org/en) (Official documentation) +- [Node Version Manager](https://github.com/nvm-sh/nvm) (Official documentation) +- [Installing Node.js and npm for local WordPress development](https://learn.wordpress.org/tutorial/installing-node-js-and-npm-for-local-wordpress-development/) (Learn WordPress tutorial) \ No newline at end of file diff --git a/docs/manifest.json b/docs/manifest.json index 75ae7d0b31f67..12c1fd8e58418 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -12,15 +12,27 @@ "parent": null }, { - "title": "Development Environment", + "title": "Block Development Environment", "slug": "devenv", "markdown_source": "../docs/getting-started/devenv/README.md", "parent": "getting-started" }, { - "title": "How to setup local WordPress environment on Ubuntu", - "slug": "docker-ubuntu", - "markdown_source": "../docs/getting-started/devenv/docker-ubuntu.md", + "title": "Node.js development tools", + "slug": "nodejs-development-tools", + "markdown_source": "../docs/getting-started/devenv/nodejs-development-tools.md", + "parent": "devenv" + }, + { + "title": "Get started with wp-env", + "slug": "get-started-with-wp-env", + "markdown_source": "../docs/getting-started/devenv/get-started-with-wp-env.md", + "parent": "devenv" + }, + { + "title": "Get started with wp-now", + "slug": "get-started-with-wp-now", + "markdown_source": "../docs/getting-started/devenv/get-started-with-wp-now.md", "parent": "devenv" }, { diff --git a/docs/toc.json b/docs/toc.json index 233967098f165..5d58e4e188239 100644 --- a/docs/toc.json +++ b/docs/toc.json @@ -7,7 +7,13 @@ { "docs/getting-started/devenv/README.md": [ { - "docs/getting-started/devenv/docker-ubuntu.md": [] + "docs/getting-started/devenv/nodejs-development-tools.md": [] + }, + { + "docs/getting-started/devenv/get-started-with-wp-env.md": [] + }, + { + "docs/getting-started/devenv/get-started-with-wp-now.md": [] } ] },