CSpell ESLint Plugin

A spell checker plugin for ESLint based upon CSpell.

Feedback Welcome

This plugin is still in active development as part of the CSpell suite of tools and applications.

Quick Setup

Install @cspell/eslint-plugin as a dev-dependency
```
npm install --save-dev @cspell/eslint-plugin
```

Add to it to .eslintrc.json

"extends": ["plugin:@cspell/recommended"]

Options

interface Options {
  /**
   * Automatically fix common mistakes.
   * This is only possible if a single preferred suggestion is available.
   * @default false
   */
  autoFix: boolean;
  /**
   * Number of spelling suggestions to make.
   * @default 8
   */
  numSuggestions: number;
  /**
   * Generate suggestions
   * @default true
   */
  generateSuggestions: boolean;
  /**
   * Ignore import and require names
   * @default true
   */
  ignoreImports?: boolean;
  /**
   * Ignore the properties of imported variables, structures, and types.
   *
   * Example:
   * ```
   * import { example } from 'third-party';
   *
   * const msg = example.property; // `property` is not spell checked.
   * ```
   *
   * @default true
   */
  ignoreImportProperties?: boolean;
  /**
   * Spell check identifiers (variables names, function names, and class names)
   * @default true
   */
  checkIdentifiers?: boolean;
  /**
   * Spell check strings
   * @default true
   */
  checkStrings?: boolean;
  /**
   * Spell check template strings
   * @default true
   */
  checkStringTemplates?: boolean;
  /**
   * Spell check JSX Text
   * @default true
   */
  checkJSXText?: boolean;
  /**
   * Spell check comments
   * @default true
   */
  checkComments?: boolean;
  /**
   * Specify a path to a custom word list file.
   *
   * example:
   * ```js
   * customWordListFile: "./myWords.txt"
   * ```
   */
  customWordListFile?: string | { path: string };
  /**
   * Output debug logs
   * @default false
   */
  debugMode?: boolean;
}

Example:

{
  "plugins": ["@cspell"],
  "rules": {
    "@cspell/spellchecker": ["warn", { "checkComments": false, "autoFix": true }]
  }
}

`autoFix`

When enabled, autoFix corrects any spelling issues that have a single "preferred" suggestion. It attempts to match case and style, but it cannot guarantee correctness of code.

Preferred Suggestions

CSpell offers the ability to flag words as incorrect and to provide suggestions.

cspell.config.yaml

words:
  - allowlist
flagWords:
  - blacklist->allowlist
suggestWords:
  - colour->color

With this configuration, blacklist is flagged as forbidden and allowlist is the "preferred" suggestion. When autoFix is enabled, all instances of blacklist will be replaced with allowlist.

When spell checking, if colour is not in one of the dictionaries, then color will be offered as the preferred suggestion. suggestWords are used to provide preferred suggestions, but will not flag any words as incorrect.

CSpell will match case, but not word stems. blacklist and Blacklist will get replaced, but not blacklists.

In Combination with CSpell

Due to the nature of how files are parsed, the cspell command line tool and this ESLint plugin will give different results. It is recommended that either ESLint or cspell checks a file, but not both. Use ignorePaths setting in cspell.json to tell the cspell command line tool to ignore files checked by ESLint.

Differences:

The CSpell parser is generic across all file types. It just breaks an entire document into words and tests them against the dictionaries. Everything is checked, comments, code, strings, etc.
The CSpell ESLint plugin uses the AST (a way to identify the meaning of the individual parts of your code) provided by ESLint to only check literal strings, identifiers, and comments. See Options on selecting what to check.

Example spell checked with ESLint CSpell Plugin:

Example spell checked with just cspell:

CSpell for Enterprise

Available as part of the Tidelift Subscription.

The maintainers of cspell and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source packages you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact packages you use. Learn more.

Brought to you by Street Side Software Logo Street Side Software

npm