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 the plugin to the ESLint configuration (see below:)

  • Configuration (new: eslint.config.js)
  • Configuration (Legacy: .eslintrc)

Configuration (new: eslint.config.js)

eslint.config.js using recommended.

import cspellESLintPluginRecommended from '@cspell/eslint-plugin/recommended';

export default [
  // other config imports
  cspellESLintPluginRecommended
  // other configs
];

Or

eslint.config.js using configs.

import cspellConfigs from '@cspell/eslint-plugin/configs';

export default [
  // other config imports
  cspellConfigs.recommended
  // other configs
];

Or

eslint.config.js using plugins

import cspellPlugin from '@cspell/eslint-plugin';

export default [
  // other config imports
  {
    plugins: { '@cspell': cspellPlugin },
    rules: {
      '@cspell/spellchecker': ['warn', {}]
    }
  }
  // other configs
];

Configuration (Legacy: .eslintrc)

Add "plugin:@cspell/recommended" to the extends section of the configuration.

.eslintrc

{
  "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;
  /**
   * Some CSpell Settings
   */
  cspell?: {
    /**
     * The language locale to use, i.e. `en-US,en-GB` to enable both
     * American and British English.
     */
    language?: string;
    /** List of words to be considered correct. */
    words?: string[];
    /**
     * List of words to be ignored.
     * An ignored word will not show up as an error, even if it is also
     * in the `flagWords`.
     */
    ignoreWords?: string[];
    /**
     * List of words to always be considered incorrect.
     * Words found in `flagWords` override `words`.
     * Format of `flagWords`
     * - single word entry - `word`
     * - with suggestions - `word:suggestion` or `word->suggestion, suggestions`
     */
    flagWords?: string[];
    /**
     * List of regular expression patterns or pattern names to exclude
     * from spell checking.
     */
    ignoreRegExpList?: string[];
    /**
     * List of regular expression patterns or defined pattern names to
     * match for spell checking.
     * If this property is defined, only text matching the included
     * patterns will be checked.
     */
    includeRegExpList?: string[];
    /** Allows words to be glued together. */
    allowCompoundWords?: boolean;
    /** Import cspell config file. */
    import?: string[];
    /** List of dictionaries to enable */
    dictionaries?: string[];
    /** Define dictionaries. */
    dictionaryDefinitions?: DictionaryDefinition[];
  };
  /**
   * 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;
}

Examples:

eslint.config.js

import cspellPlugin from '@cspell/eslint-plugin';

export default [
  {
    plugins: { '@cspell': cspellPlugin },
    rules: {
      '@cspell/spellchecker': ['warn', { checkComments: false, autoFix: true }]
    }
  }
];

eslint.config.js

import cspellConfigs from '@cspell/eslint-plugin/configs';

export default [
  cspellConfigs.recommended,
  {
    rules: {
      '@cspell/spellchecker': ['warn', { checkComments: false, autoFix: true }]
    }
  }
];

.eslintrc.json

{
  "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