Setting up Linting

Introduction

Setting up linting is an important part of ensuring quality in a WooCommerce project because it helps protect your project from programming errors, sub-optimal approaches, stylistic inconsistencies, and other issues. If these issues go unnoticed, while they might not prevent your code from executing, they can make code difficult to read, debug, or maintain over time. Follow the steps below to set up the linting tools in your project.

---

Setting up Sniffs

Installing PHP_CodeSniffer

There are several ways to install PHP_CodeSniffer. You can find the most up-to-date instructions in its repository on GitHub.

Because Composer is one of the recommended prerequisites for WooCommerce development, we can use it for setting things up:

composer global require "squizlabs/php_codesniffer=*"

If you’re using a composer.json file for managing project dependencies, you can add PHP_CodeSniffer as a development dependency and it will be available as an executable in the ./vendor/bin directory of your project.

{
    "require-dev": {
        "squizlabs/php_codesniffer": "3.*"
    }
}

When adding new Composer dependencies to a project’s composer.json file, be sure to make sure you install them with:

composer install

Configuring WooCommerce Sniffs

WooCommerce Sniffs is a collection of coding standards (known colloquially as sniffs) that help ensure consistent coding patterns across all of WooCommerce core and across ecosystem extensions. This is the set of coding standards against which extensions in the WooCommerce Marketplace are evaluated.

To use WooCommerce Sniffs in your project, use Composer to require the package as a dependency:

composer require woocommerce/woocommerce-sniffs

Once the package has been added as a dependency, you can use it in a number of ways. To scan a single file from the command-line, for instance:

./vendor/bin/phpcs --standard=WooCommerce-Core <file>

You can also use a PHP_CodeSniffer configuration file to set up a set of rules for checking certain files in your project against WooCommerce Sniffs:

<?xml version="1.0"?>
<ruleset name="WooCommerce Coding Standards">
    <description>My projects ruleset.</description>

    <!-- Configs -->
    <config name="minimum_supported_wp_version" value="5.6" />
    <config name="testVersion" value="7.2-" />

    <!-- Rules -->
    <rule ref="WooCommerce-Core" />

    <rule ref="WordPress.WP.I18n">
        <properties>
            <property name="text_domain" type="array" value="my-project-text-domain" />
        </properties>
    </rule>

    <rule ref="PHPCompatibility">
        <exclude-pattern>tests/</exclude-pattern>
    </rule>
</ruleset>

---

Setting up JavaScript Linting

Installing ESLint

There are a few different ways to install ESLint. Because NPM is one of the recommended prerequisites for WooCommerce development, you can use it to add ESLint as a dependency in your project. From your project root, run the following command:

npm install --eslint --save-dev

Configuring WooCommerce Linting

Once ESLint is installed, you’ll want to set up a configuration file to manage how ESLint processes the files in your project. You could let ESLint set one up from scratch for you using the npx eslint --init command, but WooCommerce has a dedicated ESLint plugin that you can use. Using this plugin helps ensure your JavaScript adheres to the same coding standards that WooCommerce core, WooCommerce Admin, WooCommerce Blocks, and other ecosystem extensions use.

To use the WooCommerce ESLint plugin, use NPM to add it as a development dependency:

npm install --save-dev @woocommerce/eslint-plugin

Once the WooCommerce ESLint plugin is installed, create an ESLint configuration file at your project root:

touch .eslintrc.js

When you have created your empty configuration file, populate it with the sample configuration below:

module.exports = {
    extends: [ 'plugin:@woocommerce/eslint-plugin/recommended' ],
    rules: {
        // You can use the 'rules' key to override specific settings in the WooCommerce plugin
        '@wordpress/i18n-translator-comments': 'warn',
        '@wordpress/valid-sprintf': 'warn',
        'jsdoc/check-tag-names': [
            'error',
            { definedTags: [ 'jest-environment' ] },
        ],
    },
};

The WooCommerce ESLint plugin is, itself, primarily an extension of the @wordpress/eslint-plugin/recommended plugin for ESLint. You can read more about what it does and how to use it in the package’s official documentation.

---

There are many ways to configure your linting tools, depending on the structure of your project. As always, it’s best to refer to the official documentation for ESLint, PHP_CodeSniffer and WooCommerce Sniffs for the most up-to-date usage instructions.

---