eslint-config-wpcalypso

6.1.0 verified Sat Apr 25 auth: no javascript

ESLint shareable config for WordPress.com's Calypso JavaScript Coding Guidelines. Current stable version is 6.1.0. It enforces the Calypso style guide and is maintained by Automattic. Requires ESLint 7+, eslint-plugin-jsdoc, eslint-plugin-wpcalypso, and eslint-plugin-inclusive-language as peer dependencies. Distinct from generic WordPress ESLint configs by focusing on Calypso-specific conventions used in the WordPress.com dashboard.

Common errors

error Failed to load plugin 'jsdoc' declared in 'eslint-config-wpcalypso': Cannot find module 'eslint-plugin-jsdoc' ↓

cause Missing peer dependency eslint-plugin-jsdoc

fix

Run: yarn add --dev eslint-plugin-jsdoc@^18.0.0

error ESLint couldn't find the config "wpcalypso" to extend from. ↓

cause eslint-config-wpcalypso is not installed or not in node_modules

fix

Run: yarn add --dev eslint-config-wpcalypso

error Configuration for rule 'jsdoc/check-alignment' is invalid ↓

cause Version mismatch: eslint-plugin-jsdoc >18 causes rule schema changes

fix

Install eslint-plugin-jsdoc@18.0.0 exactly: yarn add --dev eslint-plugin-jsdoc@18.0.0

Warnings

breaking Peer dependency eslint-plugin-wpcalypso requires version ^3.4.1 || ^4.0.0, which may not be compatible with newer versions. ↓

fix Install eslint-plugin-wpcalypso@4.0.0 if using eslint-config-wpcalypso@6.1.0.

breaking Requires eslint@^7.0.0, which is outdated. Using eslint@8+ will fail. ↓

fix Downgrade ESLint to version 7.x, or use an older eslint-config-wpcalypso version that supports ESLint 8.

breaking Peer dependency eslint-plugin-jsdoc requires version ^18.0.0, which is outdated. Newer versions of eslint-plugin-jsdoc are not compatible. ↓

fix Install eslint-plugin-jsdoc@18.x specifically.

breaking The react superset 'wpcalypso/react' requires eslint-plugin-react as a peer dependency, but it is not listed as a required peer in package.json. ↓

fix Manually install eslint-plugin-react if using the react config.

gotcha Using both 'wpcalypso' and 'wpcalypso/react' extends may cause rule conflicts; only extend the react variant if you need React rules. ↓

fix Decide on one: either 'wpcalypso' for non-React projects, or 'wpcalypso/react' for React projects.

Install

npm install eslint-config-wpcalypso

yarn add eslint-config-wpcalypso

pnpm add eslint-config-wpcalypso

Imports

extends
wrong
```
{
  "extends": "eslint-config-wpcalypso"
}
```
correct
```
{
  "extends": "wpcalypso"
}
```
When using shareable configs, you can omit the eslint-config- prefix.
extends (React)
wrong
```
{
  "extends": ["wpcalypso", "plugin:react/recommended"]
}
```
correct
```
{
  "extends": "wpcalypso/react"
}
```
Use the /react sub-config to opt into React-specific rules instead of manually adding react plugin.
plugins (all)
wrong
```
{
  "extends": "wpcalypso",
  "plugins": []
}
```
correct
```
{
  "plugins": ["jsdoc", "wpcalypso", "inclusive-language"]
}
```
The shareable config automatically loads its plugins when extended, so you don't need to specify them separately.

Quickstart

This shows the minimal ESLint configuration using the wpcalypso preset. Install peer dependencies with yarn add --dev eslint-config-wpcalypso eslint eslint-plugin-jsdoc eslint-plugin-wpcalypso eslint-plugin-inclusive-language.

// .eslintrc.json
{
  "extends": "wpcalypso"
}