Steve-Dee-Designs
/
woocommerce
mirror of https://github.com/woocommerce/woocommerce.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
woocommerce/plugins/woocommerce-blocks/docs/contributors/getting-started.md

8.3 KiB
Raw Blame History

Getting Started

Table of contents

Before you can begin contributing to the Blocks plugin there are several steps and tools required to setup your local development environment.

Cloning the Git Repository

Before you can start modifying files you'll want to clone this repository locally, either via the command line, or using a Git client such as GitHub Desktop.

To do so from the command line, ensure you have git installed on your machine, and run the clone command:

git clone https://github.com/woocommerce/woocommerce-blocks.git

Configuring your WordPress site

When developing this plugin, you'll must add the following to the wp-config.php file attached to the WordPress instance you are using to test the plugin against:

define( 'JETPACK_AUTOLOAD_DEV', true );

The above constant definition ensures that classes in the cloned plugin are always overriding what's included with WooCommerce core via the Woo Blocks package.

It's also recommended you add the following constant definitions to your wp-config.php file as well to make sure you are catching any PHP notices and/or errors introduced:

define( 'WP_DEBUG', true );
define( 'SCRIPT_DEBUG', true );

Installing dependencies

To install dependencies, you will need the following tools installed on your machine:

  • node and npm via NVM: While you can always install Node or NPM through other means, we recommend using NVM to ensure you're aligned with the version used by our development teams. Our repository contains an .nvmrc file which helps ensure you are using the correct version of Node.
  • PHP: WooCommerce Blocks requires PHP. It is also needed to run Composer and various project build scripts.
  • Composer: We use Composer to manage all of the dependencies for PHP packages and plugins.

See package.json engines and readme.txt for details on required versions.

Once you the above setup, install the dependencies from the command line:

  • Change directory to your repo folder, e.g. $ cd woocommerce-blocks.
  • Ensure the correct version of Node and NPM are installed - $ nvm use
  • Install JavaScript and PHP dependencies - $ npm install && composer install.

Building the plugin files

NPM is used to trigger builds. Building is required for the plugin to functional.

  • Run $ npm run build to build all assets for production.
  • Run $ npm start to run the development build and watch for changes.

These scripts compile the code using webpack which is one of the installed dependencies from earlier.

You can also run $ npx webpack to run the development build and not keep watching for changes.

Create a plugin package in ZIP format

Run $ npm run package-plugin to trigger install and build, and then create a zip file which you can use to install WooCommerce Blocks in WordPress admin.

You can also do different variations of this command. By default it builds a production version of the plugin. You can also:

  • Build a development version of the plugin: $ npm run package-plugin:dev
  • Just do a zip build of the current environment (useful when you already have built files for zipping): $ npm run package-plugin:zip-only

Linting

Run $ npm run lint to check code against our linting rules.

This script runs 3 sub-commands: lint:php, lint:css, lint:js. Use these to run linters across the codebase (linters check for valid syntax).

  • lint:php runs phpcs via composer, which uses the phpcs.xml rule set.
  • lint:css runs stylelint over all the scss code in assets/css, using the rules in .stylelintrc.json.
  • lint:js runs eslint over all the JavaScript, using the rules in .eslintrc.js.

Note; linters are also ran before commits via Git. If there are any violations, you will not be able to commit your changes until they are fixed, unless you add the --no-verify flag to your commit command.

Running the Blocks plugin

To run the Blocks plugin you'll need a WordPress development environment - e.g. VVV or docker.

  • Ensure the repo folder is in the wp-content/plugins folder of your WordPress environment.
  • Activate the WooCommerce Blocks plugin (should be dev version, e.g. 2.6.0-dev).
  • Edit a page or post in block editor - you should see WooCommerce blocks in the block inserter!

Developer Tools (Visual Studio Code)

We recommend configuring your editor to automatically check for syntax and lint errors. This will help you save time as you develop by automatically fixing minor formatting issues.

Here are some directions for setting up Visual Studio Code (most tools are also available for other editors).

EditorConfig

EditorConfig defines a standard configuration for setting up your editor, for example using tabs instead of spaces. You should install the EditorConfig for VS Code extension and it will automatically configure your editor to match the rules defined in the Blocks plugin repository .editorconfig file.

ESLint

ESLint statically analyzes the code to find problems. The lint rules are integrated in the continuous integration process and must pass to be able to commit. You should install the ESLint Extension for Visual Studio Code (see eslint docs for more editor integrations).

With the extension installed, ESLint will use the .eslintrc.js file in the root of the Blocks plugin repository for formatting rules. It will highlight issues as you code.

Prettier

Prettier is a tool that allows you to define an opinionated format, and automate fixing the code to match that format. Prettier and ESlint are similar, Prettier is more about formatting and style, while ESlint is for detecting coding errors.

To use Prettier, you should install the Prettier - Code formatter extension in Visual Studio Code. You can then configure it to be the default formatter and to automatically fix issues on save, by adding the following to your settings.

"[javascript]": {
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.formatOnSave": true
},

This will use the .prettierrc.js file in the root folder of the Blocks plugin repository and the version of Prettier that is installed in the root node_modules folder.

Testing

You’ll find a handful of scripts in package.json that performs the automated tests and linting. You can run the following commands to execute automated tests in your terminal:

  • JS tests: npm run test
  • Run npm run wp-env command to setup the development environment in Docker.

To find out more about how to run automated JavaScript tests, check out the documentation on JavaScript Testing.

We're hiring! Come work with us!

🐞 Found a mistake, or have a suggestion? Leave feedback about this document here.