Skip to main content

spellcheck-comments

Targeted pattern scope​

This rule checks regular line comments, block comments, and JSDoc-style comment text with cspell dictionaries.

It uses the plugin's markdown-aware comment projection layer, so inline code spans such as `eslint.config.mjs` are ignored instead of being spellchecked as normal prose. Directive comments such as eslint-disable and TypeScript suppression comments are also skipped.

What this rule reports​

The rule reports words that are unknown, misspelled, or explicitly flagged by the imported cspell dictionaries plus the plugin's built-in technical vocabulary.

That means normal prose typos such as documeant or incorect are reported, while common engineering terms such as eslint, repo, tsconfig, and Node.js are accepted by default.

Why this rule exists​

Typos in comments make documentation look less trustworthy and harder to skim. A lightweight comment-only spellcheck catches those mistakes before they spread through code review, generated docs, or copied snippets.

❌ Incorrect​

// This documeant stays incorect after review.
publish();
/**
 * Keep this changelog entry acurate and searchable.
 */
save();

✅ Correct​

// This document stays correct after review.
publish();
/**
 * Keep this changelog entry accurate and searchable.
 */
save();

Behavior and migration notes​

  • The rule is report only. It does not rewrite comment text for you.
  • Built-in cspell imports cover American English, common misspellings, British/Commonwealth English variants, and a broad set of coding dictionaries such as Bash, CSS, Git, HTML, Makefile, MIME types, mnemonics, Node.js, npm, PowerShell, public licenses, scientific terms, shell, software terms, SQL, TypeScript, and Win32 terminology.
  • Use ignoreWords to add repository-specific jargon, abbreviations, or product names inline in ESLint config.
  • Use ignoreWordFiles to load accepted words from cspell-style dictionary text files instead of copying a long allowlist into your ESLint config.
  • Use cspellConfigImports to import extra cspell dictionary packages or local cspell config files.
  • The three dictionary-related options expect different formats:
    • ignoreWords: a plain array of accepted tokens written directly in ESLint config.
    • ignoreWordFiles: an array of file paths to cspell-style word lists, resolved from the repository root when ESLint runs.
    • cspellConfigImports: an array of cspell config imports, either local config files such as "./cspell.json" / "./config/cspell/project-terms.yaml" or package dictionary entrypoints such as "@cspell/dict-rust/cspell-ext.json".
  • No safe "only spellcheck known words" mode exists. Unknown words are exactly where real typos and repository-specific terms overlap, so extend the accepted vocabulary instead of suppressing all unknowns.
  • This rule is intentionally kept out of the recommended preset because spellchecking tends to be more repository-specific than prose quality or task hygiene.

Additional examples​

Rule option shape and defaults:

type SpellcheckCommentsOptions = {
        cspellConfigImports?: readonly string[];
        ignoreDigits?: boolean;
        ignoreLiteral?: boolean;
        ignoreWordFiles?: readonly string[];
        ignoreWords?: readonly string[];
        maxSuggestions?: number;
        normalizeApostrophes?: boolean;
        useDefaultDictionaries?: boolean;
};

const defaults = {
        cspellConfigImports: [],
        ignoreDigits: true,
        ignoreLiteral: true,
        ignoreWordFiles: [],
        ignoreWords: [],
        maxSuggestions: 5,
        normalizeApostrophes: true,
        useDefaultDictionaries: true,
};

For ignoreWordFiles, use normal cspell word-list formatting:

AcmeCloud
Synclet
WriteGoodComments

Accept local product names and limit each report to three candidates:

import writeGoodComments from "eslint-plugin-write-good-comments-2";

export default [
    {
        plugins: {
            "write-good-comments": writeGoodComments,
        },
        rules: {
            "write-good-comments/spellcheck-comments": [
                "error",
                {
                    ignoreWords: ["AcmeCloud", "Synclet"],
                    maxSuggestions: 3,
                },
            ],
        },
    },
];

Load repository vocabulary from a cspell-style word list file:

import writeGoodComments from "eslint-plugin-write-good-comments-2";

export default [
    {
        plugins: {
            "write-good-comments": writeGoodComments,
        },
        rules: {
            "write-good-comments/spellcheck-comments": [
                "error",
                {
                    ignoreWordFiles: ["./config/cspell/project-words.txt"],
                },
            ],
        },
    },
];

Import an additional cspell package dictionary for repository-specific terms:

import writeGoodComments from "eslint-plugin-write-good-comments-2";

export default [
    {
        plugins: {
            "write-good-comments": writeGoodComments,
        },
        rules: {
            "write-good-comments/spellcheck-comments": [
                "error",
                {
                    cspellConfigImports: ["@cspell/dict-rust/cspell-ext.json"],
                },
            ],
        },
    },
];

Import a local cspell config file that already groups project-specific dictionaries:

import writeGoodComments from "eslint-plugin-write-good-comments-2";

export default [
    {
        plugins: {
            "write-good-comments": writeGoodComments,
        },
        rules: {
            "write-good-comments/spellcheck-comments": [
                "error",
                {
                    cspellConfigImports: ["./config/cspell/project-terms.yaml"],
                },
            ],
        },
    },
];

ESLint flat config example​

import writeGoodComments from "eslint-plugin-write-good-comments-2";

export default [
    {
        files: ["**/*.{ts,tsx,js,jsx}"],
        plugins: {
            "write-good-comments": writeGoodComments,
        },
        rules: {
            "write-good-comments/spellcheck-comments": "error",
        },
    },
];

When not to use it​

Do not use this rule when your repository relies heavily on rapidly changing domain language and the team is unwilling to maintain an allowlist of accepted terms.

If the rule is useful but specific terms are noisy, prefer ignoreWords over disabling the rule entirely.

Package documentation​

Upstream package documentation:

Rule catalog ID: R005

Further reading​