Spell Checking

Installation

See: Installation

Basic Usage

Example: recursively spell check all JavaScript files in src

JavaScript files

cspell "src/**/*.js"
# or
cspell lint "src/**/*.js"

Check everything

cspell .
# or
cspell "**"

Adding CSpell to an existing project

In the steps below we will create a cspell configuration file and setup a single custom dictionary for the project.

Steps:

1. Create a configuration file
2. Add words to the project dictionary

1. Create a configuration file.

CSpell can use JSON, Yaml, and JavaScript files for configuration. It automatically searches for one of the following:

• package.json
• .cspell.json
• cspell.json
• .cSpell.json
• cSpell.json
• .cspell.jsonc
• cspell.jsonc
• .cspell.yaml
• cspell.yaml
• .cspell.yml
• cspell.yml
• .cspell.config.json
• cspell.config.json
• .cspell.config.jsonc
• cspell.config.jsonc
• .cspell.config.yaml
• cspell.config.yaml
• .cspell.config.yml
• cspell.config.yml
• .cspell.config.mjs
• cspell.config.mjs
• .cspell.config.cjs
• cspell.config.cjs
• .cspell.config.js
• cspell.config.js
• .cspell.config.mts
• cspell.config.mts
• .cspell.config.cts
• cspell.config.cts
• .cspell.config.ts
• cspell.config.ts
• .cspell.config.toml
• cspell.config.toml
• .config/.cspell.json
• .config/cspell.json
• .config/.cSpell.json
• .config/cSpell.json
• .config/.cspell.jsonc
• .config/cspell.jsonc
• .config/cspell.yaml
• .config/cspell.yml
• .config/.cspell.config.json
• .config/cspell.config.json
• .config/.cspell.config.jsonc
• .config/cspell.config.jsonc
• .config/.cspell.config.yaml
• .config/cspell.config.yaml
• .config/.cspell.config.yml
• .config/cspell.config.yml
• .config/.cspell.config.mjs
• .config/cspell.config.mjs
• .config/.cspell.config.cjs
• .config/cspell.config.cjs
• .config/.cspell.config.js
• .config/cspell.config.js
• .config/.cspell.config.mts
• .config/cspell.config.mts
• .config/.cspell.config.cts
• .config/cspell.config.cts
• .config/.cspell.config.ts
• .config/cspell.config.ts
• config/.cspell.config.toml
• config/cspell.config.toml
• .vscode/.cspell.json
• .vscode/cSpell.json
• .vscode/cspell.json

For now choose to use either JSON or Yaml. Below are examples of each that include a custom dictionary definition. Both of them are equivalent. If you have both, CSpell will look for the .json file first.

cspell.json

{
    "$schema": "https://raw.githubusercontent.com/streetsidesoftware/cspell/main/cspell.schema.json",
    "version": "0.2",
    "dictionaryDefinitions": [
        {
            "name": "project-words",
            "path": "./project-words.txt",
            "addWords": true
        }
    ],
    "dictionaries": ["project-words"],
    "ignorePaths": ["node_modules", "/project-words.txt"]
}

cspell.config.yaml

---
$schema: https://raw.githubusercontent.com/streetsidesoftware/cspell/main/cspell.schema.json
version: '0.2'
dictionaryDefinitions:
    - name: project-words
      path: './project-words.txt'
      addWords: true
dictionaries:
    - project-words
ignorePaths:
    - 'node_modules'
    - '/project-words.txt'

cspell.config.mjs

import { defineConfig } from 'cspell';

export default defineConfig({
    version: '0.2',
    dictionaryDefinitions: [
        {
            name: 'project-words',
            path: './project-words.txt',
            addWords: true,
        },
    ],
    dictionaries: ['project-words'],
    ignorePaths: ['node_modules', '/project-words.txt'],
});

cspell.config.cjs

'use strict';

const { defineConfig } = require('cspell');

module.exports = defineConfig({
    version: '0.2',
    dictionaryDefinitions: [
        {
            name: 'project-words',
            path: './project-words.txt',
            addWords: true,
        },
    ],
    dictionaries: ['project-words'],
    ignorePaths: ['node_modules', '/project-words.txt'],
});

cspell.config.mts

// TypeScript version of the CSpell config.
// Requires Node.js >= 22.18 to run natively.
import { defineConfig } from 'cspell';

export default defineConfig({
    version: '0.2',
    dictionaryDefinitions: [
        {
            name: 'project-words',
            path: './project-words.txt',
            addWords: true,
        },
    ],
    dictionaries: ['project-words'],
    ignorePaths: ['node_modules', '/project-words.txt'],
});

cspell.config.cts

// CommonJS TypeScript version of the CSpell config.
// Requires Node.js >= 22.18 to run natively.
const { defineConfig } = require('cspell');

module.exports = defineConfig({
    version: '0.2',
    dictionaryDefinitions: [
        {
            name: 'project-words',
            path: './project-words.txt',
            addWords: true,
        },
    ],
    dictionaries: ['project-words'],
    ignorePaths: ['node_modules', '/project-words.txt'],
});

package.json

{
    ...
    "cspell": {
        "version": "0.2",
        "dictionaryDefinitions": [
            {
                "name": "project-words",
                "path": "./project-words.txt",
                "addWords": true
            }
        ],
        "dictionaries": ["project-words"],
        "ignorePaths": ["node_modules", "/project-words.txt"]
    }
}

These configuration files do three things:

1. Define the custom dictionary project-words.
2. Tell the spell checker to use the custom dictionary.
3. Tell the spell checker to ignore any files inside of node_modules and the file project-words.txt.

2. Add words to the project dictionary

It might take a few iterations to get fully setup, but the process in the same.

Steps:

1. Create the dictionary file

   touch project-words.txt

2. Choose a set of files to start with, like all Markdown files, **/*.md and run the spell checker.

   cspell "**/*.md"

3. Look for any directories that need to be ignored and add them to ignorePaths. Example:

   • "bin" - to ignore any directory / file called bin.
   • "translations/**" - to ignore all files under the translations directory.
   • "packages/*/dist" - to ignore the dist directory in each package.

   Once you have finished identifying directories and files to be ignored, it is now time to add words to the custom dictionary.

4. Have CSpell populate it with the words from your project.

   echo "# New Words" >> project-words.txt
   cspell --words-only --unique "**/*.md" | sort --ignore-case >> project-words.txt

   This will append all new issues to the end of project-words.txt

5. Review the words in project-words.txt to check for any actual misspellings and remove them (the spell checker already thinks they are wrong).

6. Fix spelling issues.

   To show the issues and suggestions, use:

   cspell --no-progress --show-suggestions --show-context "**/*.md"

7. Repeat the process with the other file types you want to check.

3. Fine-tuning

The following resources can help you with fine-tuning your configurations:

• Making words forbidden
• Defining Custom Dictionaries
• About Dictionaries
• Understanding CSpell Globs

Help

Command: lint -- Spell Checking

The lint command is used for spell checking files.

Help

cspell lint --help

Options

Usage: cspell lint [options] [globs...] [file://<path> ...] [stdin[://<path>]]

Patterns:
 - [globs...]            Glob Patterns
 - [stdin]               Read from "stdin" assume text file.
 - [stdin://<path>]      Read from "stdin", use <path> for file type and config.
 - [file://<path>]       Check the file at <path>

Examples:
    cspell .                        Recursively check all files.
    cspell lint .                   The same as "cspell ."
    cspell "*.js"                   Check all .js files in the current directory
    cspell "**/*.js"                Check all .js files recursively
    cspell "src/**/*.js"            Only check .js under src
    cspell "**/*.txt" "**/*.js"     Check both .js and .txt files.
    cspell "**/*.{txt,js,md}"       Check .txt, .js, and .md files.
    cat LICENSE | cspell stdin      Check stdin
    cspell stdin://docs/doc.md      Check stdin as if it was "./docs/doc.md"

Check spelling

Options:
  -c, --config <cspell.json>     Configuration file to use.  By default cspell
                                 looks for cspell.json in the current directory.
  --no-config-search             Disable automatic searching for additional
                                 configuration files in parent directories. Only
                                 the specified config file (if any) will be
                                 used.
  --stop-config-search-at <dir>  Specify a directory at which to stop searching
                                 for configuration files when walking up from
                                 the files being checked. Useful for limiting
                                 config inheritance.
  -v, --verbose                  Display more information about the files being
                                 checked. Add more than one -v for increased
                                 verbosity.
  --locale <locale>              Set language locales. i.e. "en,fr" for English
                                 and French, or "en-GB" for British English.
  --language-id <file-type>      Force programming language for unknown
                                 extensions. i.e. "php" or "scala"
  --words-only                   Only output the words not found in the
                                 dictionaries.
  -u, --unique                   Only output the first instance of a word not
                                 found in the dictionaries.
  -e, --exclude <glob>           Exclude files matching the glob pattern. This
                                 option can be used multiple times to add
                                 multiple globs.
  --file-list <path or stdin>    Specify a list of files to be spell checked.
                                 The list is filtered against the glob file
                                 patterns. Note: the format is 1 file path per
                                 line.
  --file [file...]               Specify files to spell check. They are filtered
                                 by the [globs...].
  --no-issues                    Do not show the spelling errors.
  --no-progress                  Turn off progress messages
  --no-summary                   Turn off summary message in console.
  -s, --silent                   Silent mode, suppress error messages.
  --no-exit-code                 Do not return an exit code if issues are found.
  --quiet                        Only show spelling issues or errors.
  --fail-fast                    Exit after first file with an issue or error.
  --continue-on-error            Continue processing files even if there is a
                                 configuration error.
  -r, --root <root folder>       Root directory, defaults to current directory.
  --no-relative                  Issues are displayed with absolute path instead
                                 of relative to the root.
  --show-context                 Show the surrounding text around an issue.
  --show-suggestions             Show spelling suggestions.
  --no-show-suggestions          Do not show spelling suggestions or fixes.
  --no-must-find-files           Do not error if no files are found.
  --cache                        Use cache to only check changed files.
  --no-cache                     Do not use cache.
  --cache-reset                  Reset the cache file.
  --cache-strategy <strategy>    Strategy to use for detecting changed files.
                                 (choices: "content", "metadata", default:
                                 "content")
  --cache-location <path>        Path to the cache file or directory. (default:
                                 ".cspellcache")
  --dot                          Include files and directories starting with `.`
                                 (period) when matching globs.
  --gitignore                    Ignore files matching glob patterns found in
                                 .gitignore files.
  --no-gitignore                 Do NOT use .gitignore files.
  --gitignore-root <path>        Prevent searching for .gitignore files past
                                 root.
  --validate-directives          Validate in-document CSpell directives.
  --max-file-size <size>         Prevent checking large files. i.e 1MB, 50KB,
                                 1GB
  --color                        Force color.
  --no-color                     Turn off color.
  --no-default-configuration     Do not load the default configuration and
                                 dictionaries.
  --dictionary <name>            Enable a dictionary by name.
  --disable-dictionary <name>    Disable a dictionary by name.
  --reporter <module|path>       Specify one or more reporters to use.
  --report <level>               Set how unknown words are reported (choices:
                                 "all", "simple", "typos", "flagged")
  --issue-template [template]    Use a custom issue template. See --help
                                 --issue-template for details.
  -h, --help                     display help for command

More Examples:

    cspell "**/*.js" --reporter @cspell/cspell-json-reporter
        This will spell check all ".js" files recursively and use
        "@cspell/cspell-json-reporter".

    cspell . --reporter default
        This will force the default reporter to be used overriding
        any reporters defined in the configuration.

    cspell . --reporter ./<path>/reporter.cjs
        Use a custom reporter. See API for details.

    cspell "*.md" --exclude CHANGELOG.md --files README.md CHANGELOG.md
        Spell check only check "README.md" but NOT "CHANGELOG.md".

    cspell "/*.md" --no-must-find-files --files $FILES
        Only spell check the "/*.md" files in $FILES,
        where $FILES is a shell variable that contains the list of files.

    cspell --help --verbose
        Show all options including hidden options.

References:
    https://cspell.org
    https://github.com/streetsidesoftware/cspell