eslint-plugin-wpcalypso

8.0.0 verified Sat Apr 25 auth: no javascript

Custom ESLint rules for the WordPress.com Calypso project, version 8.0.0. This plugin enforces coding conventions specific to the Calypso codebase, such as import ordering without nested folders, JSX classname naming, and i18n string restrictions. It requires ESLint >=8.48.0, @babel/core >=7.17.5, and peer dependencies eslint-plugin-jsdoc, eslint-plugin-react, eslint-plugin-react-hooks, and eslint-plugin-inclusive-language. Unlike general-purpose ESLint plugins, this is tailored for the Calypso monorepo and may not be suitable for other projects.

Common errors

error Error: Failed to load plugin 'wpcalypso' declared in '.eslintrc': Cannot find module 'eslint-plugin-wpcalypso' ↓

cause Plugin not installed as a dependency.

fix

Run npm install --save-dev eslint-plugin-wpcalypso

error TypeError: wpcalypso is not a function ↓

cause Using require() with ESM-only plugin v8.

fix

Use import syntax or update to CJS compatible version <8.

error Error: Cannot find module '@babel/core' ↓

cause Missing peer dependency @babel/core.

fix

Run npm install --save-dev @babel/core

error Parsing error: Unexpected token = ↓

cause Project uses Babel syntax but ESLint is not configured with @babel/eslint-parser.

fix

Install @babel/eslint-parser and configure parser in .eslintrc.

Warnings

breaking ESM-only exports since v8: require() no longer works. Use import statements. ↓

fix Use ES module syntax: import wpcalypso from 'eslint-plugin-wpcalypso'

deprecated Rule 'wpcalypso/no-unsafe-wp-apis' deprecated in favor of 'jest/no-conditional-expect'? ↓

fix Use jest/no-conditional-expect instead if applicable.

gotcha Plugin enforces import ordering with no nested folders: import paths must be flat (e.g., 'components/button' not 'components/button/icon'). ↓

fix Adjust import paths to be flat as per Calypso conventions.

gotcha The rule 'wpcalypso/i18n-no-variables' disallows variables in translate() calls to ensure string extraction. ↓

fix Use string literals directly in translate() calls.

breaking Peer dependencies must be manually installed: eslint-plugin-jsdoc, eslint-plugin-react, eslint-plugin-react-hooks, eslint-plugin-inclusive-language. ↓

fix Run npm install --save-dev eslint-plugin-jsdoc eslint-plugin-react eslint-plugin-react-hooks eslint-plugin-inclusive-language

Install

npm install eslint-plugin-wpcalypso

yarn add eslint-plugin-wpcalypso

pnpm add eslint-plugin-wpcalypso

Imports

default

wrong

const wpcalypso = require('eslint-plugin-wpcalypso')

correct

import wpcalypso from 'eslint-plugin-wpcalypso'

ESM-only since v8

rules

wrong

const rules = require('eslint-plugin-wpcalypso').rules

correct

import { rules } from 'eslint-plugin-wpcalypso'

Access all rules as an object

configs

wrong

const configs = require('eslint-plugin-wpcalypso').configs

correct

import { configs } from 'eslint-plugin-wpcalypso'

Access predefined configs like 'recommended'

Quickstart

Shows how to configure ESLint with the wpcalypso plugin, using the recommended config and customizing a couple of rules.

// .eslintrc.js
module.exports = {
  plugins: ['wpcalypso'],
  extends: ['plugin:wpcalypso/recommended'],
  rules: {
    'wpcalypso/no-unsafe-wp-apis': 'error',
    'wpcalypso/import-dependencies': 'warn',
  },
};