Updated How to set up WooCommerce development environment (markdown)
Christopher Allford
parent
703c393c35
commit
3292a45aed
|
|
@ -17,170 +17,17 @@ This page will guide you through the process of setting up WooCommerce developme
|
|||
|
||||
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
|
||||
|
||||
## Pre-requisites
|
||||
## Getting Started
|
||||
|
||||
Before starting, make sure you have the following software installed and working on your machine:
|
||||
Please check out [our getting started guide](https://github.com/woocommerce/woocommerce#getting-started) for information about prerequisites and initial setup.
|
||||
|
||||
1. [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) to clone the WooCommerce repository (or your fork of the WooCommerce repository).
|
||||
2. [NVM](https://github.com/nvm-sh/nvm) to install Node.js and NPM.
|
||||
3. [Composer](https://getcomposer.org/download/) to install PHP packages required by WooCommerce such as the `woocommerce-rest-api` and the `jetpack-autoloader`. It's also necessary to use the PHP CodeSniffer that ensures your code follows code standards.
|
||||
4. Nx: Follow [instructions on nx.dev site](https://nx.dev/l/r/getting-started/nx-setup) to install the Node.js flavour of Nx.
|
||||
5. pnpm: Follow [instructions on pnpm.io site](https://pnpm.io/installation) to install pnpm.
|
||||
## Development Information
|
||||
|
||||
## Configure a local WordPress instance with VVV
|
||||
We also have [more in-depth documentation](https://github.com/woocommerce/woocommerce/blob/trunk/DEVELOPMENT.md) on how to develop in our repository. This also includes information about how to set up the development environment.
|
||||
|
||||
For this guide we will use [VVV](https://github.com/Varying-Vagrant-Vagrants/VVV), which is a local WordPress development environment built using Vagrant and VirtualBox, to run a local WordPress instance and install WooCommerce on top of it. But it is worth noting that it is possible to set up a WooCommerce development environment using several other stacks (docker, LAMP, etc). If you opt to use a solution other than VVV, you can skip to the next section. Keep in mind that you might need to make some small adjustments to the steps in the rest of this guide.
|
||||
## Troubleshooting
|
||||
|
||||
To configure our local WordPress instance, you will need to:
|
||||
|
||||
1. Install [VirtualBox](https://www.virtualbox.org/)
|
||||
2. Install [vagrant](https://www.vagrantup.com/)
|
||||
3. Install and provision [VVV](https://varyingvagrantvagrants.org/docs/en-US/installation/)
|
||||
4. If everything worked as expected, you should have a WordPress installation running on the following URL: https://one.wordpress.test. This is the WP site that we will use to install WooCommerce.
|
||||
|
||||
## Configure a local WordPress instance with wp-env
|
||||
|
||||
### Prerequisites
|
||||
|
||||
Please install WP-ENV before getting started. You can find more about WP-ENV on [here](https://github.com/WordPress/gutenberg/tree/master/packages/env).
|
||||
|
||||
The following command installs WP-ENV globally.
|
||||
|
||||
`pnpm -g i @wordpress/env`
|
||||
|
||||
|
||||
### Starting WP-ENV
|
||||
|
||||
1. Navigate to the root of WooCommerce Admin source code.
|
||||
2. Start the docker container by running `wp-env start`
|
||||
|
||||
You should see the following output
|
||||
|
||||
```
|
||||
WordPress development site started at http://localhost:8888/
|
||||
WordPress test site started at http://localhost:8889/
|
||||
MySQL is listening on port 55003
|
||||
```
|
||||
|
||||
The port # might be different depending on your `.wp-env.override.json` configuration.
|
||||
|
||||
### Overriding the Default Configuration
|
||||
|
||||
The default configuration comes with PHP 7.4, WooCommerce 5.0, and a few WordPress config values.
|
||||
|
||||
You can create `.wp-env.override.json` file and override the default configuration values.
|
||||
|
||||
You can find more about `.wp-env.override.json` configuration [here](https://github.com/WordPress/gutenberg/tree/master/packages/env#wp-envoverridejson).
|
||||
|
||||
**Example: Overriding PHP version to 8.0**
|
||||
|
||||
Create `.wp-env.override.json` in the root directory with the following content.
|
||||
|
||||
|
||||
```json
|
||||
{
|
||||
"phpVersion": "8.0"
|
||||
}
|
||||
```
|
||||
|
||||
**Exampe: Adding a locally installed plugin**
|
||||
|
||||
Method 1 - Adding to the `plugins` array
|
||||
|
||||
Open the default `.wp-env.json` and copy `plugins` array and paste it into the `.wp-env.override.json` and add your locally installed plugin. Copying the default `plugins` is needed as WP-ENV does not merge the values of the `plugins`.
|
||||
|
||||
```json
|
||||
{
|
||||
"plugins": [
|
||||
"./plugins/woocommerce",
|
||||
"../woocommerce-admin-test-helper",
|
||||
"https://downloads.wordpress.org/plugin/wp-crontrol.1.10.0.zip"
|
||||
]
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Method 2 - Adding to the `mappings`
|
||||
|
||||
This method is simpler, but the plugin does not get activated on startup. You need to manually activate it yourself on the first startup.
|
||||
|
||||
```json
|
||||
{
|
||||
"mappings": {
|
||||
"wp-content/plugins/wp-crontrol": "../woocommerce"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Accessing MariaDB
|
||||
|
||||
The MariaDB port can change when you restart your container.
|
||||
|
||||
You can get the current MariaDB port via running docker ps and inspecting the PORTS column allows you to determine which port MariaDB is currently using.
|
||||
|
||||
1. Open your choice of MariaDB tool.
|
||||
2. Use the following values to access the MariaDB container.
|
||||
|
||||
| Name | Value |
|
||||
|--------|-----|
|
||||
| Host | 127.0.0.1 |
|
||||
| Username | root |
|
||||
| Password | password |
|
||||
| Port | Port from the command |
|
||||
|
||||
### How do I ssh into the container?
|
||||
|
||||
Run the following command to ssh into the container
|
||||
`wp-env run wordpress /bin/bash`
|
||||
|
||||
You can run a command in the container with the following syntax. You can find more about on the `run` command [here](https://github.com/WordPress/gutenberg/tree/master/packages/env#wp-env-run-container-command)
|
||||
|
||||
Syntax:
|
||||
`wp-env run :container-type :linux-command`
|
||||
|
||||
|
||||
## Clone WooCommerce repository
|
||||
|
||||
To install WooCommerce on your WordPress installation, you need to decide whether you will clone the WooCommerce repository directly or your WooCommerce fork. If you plan to contribute to WooCommerce code base, it is recommended that you clone your fork. If needed, see [this GitHub document on how to create a fork](https://help.github.com/en/articles/fork-a-repo).
|
||||
|
||||
In your terminal:
|
||||
|
||||
1. Go to the WordPress installation folder:
|
||||
```
|
||||
$ cd ~/vagrant-local/www/wordpress-one/
|
||||
```
|
||||
2. Clone the repository:
|
||||
* If cloning WooCommerce repository:
|
||||
```
|
||||
$ git clone git@github.com:woocommerce/woocommerce.git woocommerce-monorepo
|
||||
```
|
||||
* If cloning your own fork replace `USER_NAME` with your GitHub username:
|
||||
```
|
||||
$ git clone git@github.com:USER_NAME/woocommerce.git woocommerce-monorepo
|
||||
```
|
||||
3. Link the plugin to your WordPress plugins directory:
|
||||
```
|
||||
$ ln -s ~/vagrant-local/www/wordpress-one/woocommerce-monorepo/plugins/woocommerce ~/vagrant-local/www/wordpress-one/public_html/wp-content/plugins/woocommerce
|
||||
```
|
||||
|
||||
## Install dependencies and generate assets
|
||||
|
||||
To install WooCommerce dependencies (this includes some functionality such as Gutenberg Blocks and the REST API that are developed as separate projects and Grunt that is used to generated minified versions of the SCSS and JS files):
|
||||
|
||||
```
|
||||
$ cd ~/vagrant-local/www/wordpress-one/public_html/wp-content/plugins/woocommerce
|
||||
$ nvm install
|
||||
$ nvm use
|
||||
$ npm install -g pnpm@^6.24.2
|
||||
$ pnpm install
|
||||
$ pnpm nx composer-install woocommerce
|
||||
```
|
||||
|
||||
The source code found on GitHub does not contain compiled CSS or Javascript. To generate those assets run the following command from the WooCommerce root directory:
|
||||
|
||||
```
|
||||
pnpm nx build woocommerce
|
||||
```
|
||||
## Build Out-of-memory Error
|
||||
|
||||
_Note: Depending on your PHP settings, you may encounter an out-of-memory error similar to the following..._
|
||||
|
||||
|
|
@ -195,76 +42,6 @@ _If this happens, increase the `memory_limit` setting in your php.ini configurat
|
|||
|
||||
_Alternatively, you might encounter 'Maximum function nesting level reached' error from xDebug. In that case, disable xDebug in your PHP installation temporarily._
|
||||
|
||||
_Note: Sometimes, if you're using an old version of `pnpm`, you may see an error such as the following..._
|
||||
|
||||
```
|
||||
❯ pnpm nx build woocommerce-legacy-assets
|
||||
|
||||
> nx run woocommerce-legacy-assets:build
|
||||
/bin/sh: 1: pnpx: not found
|
||||
```
|
||||
_If you see this type of error, update your `pnpm` to fix it._
|
||||
|
||||
To automatically rebuild the assets whenever a JS or SCSS file is modified run:
|
||||
|
||||
```
|
||||
pnpm nx build-watch woocommerce
|
||||
```
|
||||
|
||||
To trigger a one-time rebuild, run
|
||||
|
||||
```
|
||||
pnpm nx build woocommerce-legacy-assets
|
||||
```
|
||||
|
||||
## Run the lint tools
|
||||
|
||||
### Lint JS
|
||||
|
||||
```
|
||||
pnpx nx lint:js woocommerce
|
||||
```
|
||||
|
||||
### Lint PHP
|
||||
|
||||
```
|
||||
cd plugins/woocommerce
|
||||
composer run-script phpcs <file|folder>
|
||||
|
||||
# Standardize lint Executor https://github.com/woocommerce/woocommerce/issues/32554
|
||||
pnpx nx lint:php woocommerce
|
||||
```
|
||||
|
||||
## WooCommerce Admin Development
|
||||
|
||||
WooCommerce Admin is a dependency of WooCommerce, so when you build woocommerce via nx, it will automatically build the WooCommerce Admin.
|
||||
|
||||
If you want to WooCommerce Admin independently, you can use these commands:
|
||||
|
||||
- `pnpm nx build woocommerce-admin` : Build a production version
|
||||
- `pnpm nx dev woocommerce-admin` : Build a development version
|
||||
- `pnpm nx start woocommerce-admin` : Build a development version, watch files (including packages/js/*) for changes
|
||||
- `pnpm nx build-watch woocommerce-admin` : Build a development version, watch client files for changes
|
||||
- `pnpm nx watch woocommerce-admin` : Watch client files for changes
|
||||
- `pnpm nx storybook woocommerce-admin`: View the storybook docs hosted standalone for `@woocommerce/components`
|
||||
|
||||
### Helper Scripts
|
||||
|
||||
There are a number of helper scripts exposed via our `package.json` and `project.json` (below list is not exhaustive, you can view the [`package.json`](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce-admin/package.json) and [`project.json`](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce-admin/project.json) file directly to see all):
|
||||
|
||||
- `pnpm nx lint woocommerce-admin` : Run eslint over the javascript files and stylelint over scss files
|
||||
- `pnpm nx test woocommerce-admin` : Run the JS test suite
|
||||
- `pnpm nx test:watch woocommerce-admin` : Watch the JS test suite
|
||||
|
||||
### Typescript
|
||||
|
||||
The `pnpm nx ts:check woocommerce-admin` command will check your TypeScript files for errors, and has been added to `.vscode/tasks.json`.
|
||||
Running this task in vscode will highlight the errors in your editor file navigator.
|
||||
|
||||
If you allow the `npm nx ts:check:watch woocommerce-admin` command to run automatically as configured, it will run in the background and pick up any errors as you save the files.
|
||||
Note: Even if you don't run this task, the IDE uses its language server to pick up type errors in files that are open. This is only necessary for picking up errors
|
||||
across the entire repository even when they haven't been opened in the IDE.
|
||||
|
||||
## Debugging
|
||||
|
||||
### Using Xdebug in the wp-env environment
|
||||
|
|
@ -293,7 +70,6 @@ localStorage.setItem( 'debug', 'wc-admin:*' );
|
|||
|
||||
[WooCommerce Admin Test Helper](https://github.com/woocommerce/woocommerce-admin-test-helper) is a plugin that makes it easier to test the WooCommerce Admin plugin.
|
||||
|
||||
|
||||
## IDE integrations
|
||||
|
||||
WooCommerce core has linting rules in place via pre-commit hooks to ensure code standards are used. Ensure you have installed NPM and Composer packages, so these are set up!
|
||||
|
|
|
|||
Loading…
Reference in New Issue