Cspell quickstart

Configure and use CSpell in projects

To set up CSpell in your environment and configure it with custom dictionaries, follow these steps:

Install Cspell

First, you need to install CSpell. If you haven't already, you can install it globally using npm:

npmpnpm

npm install --save-dev cspell

pnpm install -d cspell

Create a Configuration File

CSpell supports JSON, YAML, and JavaScript files for configuration. You can create a cspell.json or cspell.config.yaml file in your project root. Here's an example of a cspell.json configuration file:

cspell.json

{
"$schema": "https://raw.githubusercontent.com/streetsidesoftware/cspell/main/cspell.schema.json",
"version": "0.2",
"ignorePaths": ["node_modules"]
}

Add Words to Your Custom Dictionary

Create a project-words.txt file in your project root and add any word you want to be recognized by CSpell. Each word should be on a new line. This configuration defines a custom dictionary and tells CSpell to ignore files in node_modules and the project-words.txt file itself.

{
"$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"]
}

Adding Community Dictionaries

CSpell supports various community dictionaries. You can find these dictionaries in the cspell-dicts repository. To add a community dictionary, you first need to install it using npm/pnpm. For example, to add the cspell-dict-win32 dictionary, you would run:

npmpnpm

npm install --save-dev @cspell/dict-win32

pnpm install -d @cspell/dict-win32

Then, add the dictionary name to the dictionaries array in your cspell.json configuration file:

"dictionaries": ["project-words", "win32"]

Linking dictionaries

Sometimes when you try to link dictionaries the cspell command fails to import them

cspell link add @cspell/dict-fr-fr
----
Adding:
filename                                                                                                                                                 | errors
/Users/user/path/to/project/node_modules/.pnpm/@cspell+dict-fr-fr@x.x.x/node_modules/@cspell/dict-fr-fr/cspell-ext.json |       

you can import the dictionary manually by adding the import array to your cspell.json:

"import": [
  "@cspell/dict-fr-fr/cspell-ext.json",
],

Running Cspell

To check your project with CSpell, run:

cspell "**/*"

# you can add "--show-suggestions" "--show-context"  to get word sugestions for misspelled/unrecognized words

cspell  --show-suggestions --show-context "**/*"   

This command will check all files in your project. You can also specify specific files or directories to check.

By following these steps, you can set up CSpell in your environment, configure it with custom dictionaries, and ensure that your project's specific terms are recognized correctly by the spell checker.