getting-started.mdx

title	categories	sidebar_position	sidebar_label
Getting Started with CSpell	docs	1	Getting Started

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';

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:

{/** @see https://github.com/streetsidesoftware/cspell/blob/main/packages/cspell-lib/src/lib/Settings/Controller/configLoader/configLocations.ts */}

• 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
• .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
• .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.

```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"] } ``` ```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' ``` ```javascript 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'],
    });
    ```
</TabItem>
<TabItem value="commonjs" label="cspell.config.cjs">
    ```javascript
    'use strict';

    const { defineConfig } = require('@cspell/cspell-types');

    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'],
    });
    ```
</TabItem>
<TabItem value="package.json" label="package.json">
    ```json
    {
        ...
        "cspell": {
            "version": "0.2",
            "dictionaryDefinitions": [
                {
                    "name": "project-words",
                    "path": "./project-words.txt",
                    "addWords": true
                }
            ],
            "dictionaries": ["project-words"],
            "ignorePaths": ["node_modules", "/project-words.txt"]
        }
    }
    ```
</TabItem>

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