eslint-plugin-wc

3.1.0 verified Sat Apr 25 auth: no javascript

ESLint plugin enforcing best practices for Web Components, compatible with custom elements and libraries like LitElement. Current stable version 3.1.0, maintained actively. Requires ESLint >=8.40.0 and ships TypeScript types. Key differentiator: dedicated Web Components lint rules covering lifecycle callbacks, naming conventions, and shadow DOM correctness. ESM-only since v3.0.0; provides both legacy .eslintrc and flat config support.

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module not supported ↓

cause Using require() on an ESM-only package (v3+).

fix

Switch to import statement or use dynamic import().

error ESLint couldn't find the plugin 'eslint-plugin-wc'. ↓

cause Plugin not installed or not in node_modules.

fix

Run npm install eslint-plugin-wc --save-dev.

error Configuration for rule 'wc/no-constructor-attributes' is invalid. ↓

cause Invalid rule options passed.

fix

Check rule documentation for valid option schema; options are typically an empty array or specific format.

error Cannot read properties of undefined (reading 'recommended') ↓

cause Wrong import path for flat config.

fix

Use import { configs } from 'eslint-plugin-wc' and access configs['flat/recommended'].

Warnings

breaking ESM-only since v3.0.0: require() will fail. ↓

fix Use import statements or update to dynamic import().

breaking Requires ESLint >=8.40.0; older versions not supported. ↓

fix Update ESLint to version 8.40.0 or later.

deprecated The `rules` object export may be considered internal; prefer using the plugin default or configs. ↓

fix Use default import or configs export for configuration.

gotcha Flat config users must reference `configs['flat/recommended']`; the `recommended` config is not the same object. ↓

fix Use `configs['flat/recommended']` in eslint.config.js.

gotcha Some rules require `settings.wc.elementBaseClasses` to recognize base classes like LitElement. ↓

fix Add settings.wc.elementBaseClasses in your ESLint config.

Install

npm install eslint-plugin-wc

yarn add eslint-plugin-wc

pnpm add eslint-plugin-wc

Imports

plugin (default)
wrong
```
const plugin = require('eslint-plugin-wc')
```
correct
```
import plugin from 'eslint-plugin-wc'
```
ESM-only since v3.0.0; default export is the plugin object
configs
wrong
```
const { configs } = require('eslint-plugin-wc')
```
correct
```
import { configs } from 'eslint-plugin-wc'
```
Named export for flat configs; requires ESM import. Use configs['flat/recommended'] for flat config.
rules
```
import { rules } from 'eslint-plugin-wc'
```
Named export containing all rule definitions, useful for custom rule inspection.

Quickstart

Minimal configuration to enable recommended Web Components linting with both legacy .eslintrc and flat config formats.

// Install: npm install eslint-plugin-wc --save-dev

// .eslintrc.json
{
  "plugins": ["wc"],
  "extends": ["plugin:wc/recommended"],
  "rules": {
    "wc/no-constructor-attributes": "error",
    "wc/attach-shadow-constructor": "warn"
  },
  "settings": {
    "wc": {
      "elementBaseClasses": ["LitElement"]
    }
  }
}

// or flat config (eslint.config.js)
import plugin from 'eslint-plugin-wc';
export default [
  plugin.configs['flat/recommended'],
  {
    rules: {
      'wc/no-constructor-attributes': 'error',
      'wc/attach-shadow-constructor': 'warn'
    },
    settings: {
      wc: {
        elementBaseClasses: ['LitElement']
      }
    }
  }
];