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:

Yaml

• .cspell.config.yaml
• .cspell.config.yml
• cspell.config.yaml
• cspell.config.yml
• .cspell.yaml
• .cspell.yml
• cspell.yaml
• cspell.yml

Json

• package.json
• .cspell.json
• cspell.json
• .cSpell.json
• cSpell.json
• .cspell.jsonc
• cspell.jsonc
• .cspell.config.json
• .cspell.config.jsonc
• cspell.config.json
• cspell.config.jsonc

JavaScript

• cspell.config.mjs
• cspell.config.cjs
• cspell.config.js
• .cspell.config.mjs
• .cspell.config.cjs
• .cspell.config.js

TypeScript

• cspell.config.mts
• cspell.config.ts
• cspell.config.cts
• .cspell.config.mts
• .cspell.config.ts
• .cspell.config.cts

Toml

• cspell.config.toml
• .cspell.config.toml

.vscode

• .vscode/cspell.json
• .vscode/cSpell.json
• .vscode/.cspell.json

info

cspell configuration files can be prefixed with . and or .config, i.e. .cspell.config.yaml, .config/cspell.config.yaml and .config/.cspell.config.yaml.

info

package.json: Only the cspell field in package.json is considered.

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 stdin; <path> sets 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 .js files in this 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 "./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...].
  --force-check                  Force the --file or --file-list
                                 documents to be checked even if it
                                 would normally be excluded.
  --follow-symlinks              Allow checking --file and --file-list
                                 documents referenced by symbolic links.
  --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.
  --glob-symlinks                Follow symbolic links 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 containing the list of files.

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

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