This article shows how to move your custom cSpell words out of VS Code’s settings.json and into a dedicated global dictionary. This keeps your configuration clean while providing a single, reusable place for technical terms, product names, and other words you use across projects.
When using the Code Spell Checker (cSpell) extension in VS Code, custom words can be added directly to settings.json using cSpell.userWords. Over time, however, this list can become large and clutter the VS Code configuration.
A cleaner approach is to maintain custom words in a separate global dictionary file.
Note: These instructions assume you are using macOS.
Create the Dictionary File
Create a global cSpell dictionary in your home directory:
touch ~/.cspell-dictionary.txt
For a user named username, the full path to the file would be:
/Users/username/.cspell-dictionary.txt
Open the file in VS Code:
code ~/.cspell-dictionary.txt
Add custom words to the dictionary with one word per line:
bootcamp
cfadmin
cfconfig
cfcs
cfdocument
cfengine
cfformat
cfinvoke
cflog
cfoutput
cfpm
cfschedule
cfscript
cfset
cfusion
CommandBox
Fixinator
Flexbox
Glyphicons
labwc
Lucee
LUCEEONLY
Mailpit
mailsent
navbars
Ollama
raspi
strikethrough
Udemy
Webroot
WebUI
Unlike settings.json, the dictionary file does not use JSON syntax. Do not include quotes, commas, or brackets.
Configure cSpell
Open your VS Code settings.json and add the following:
"cSpell.dictionaryDefinitions": [
{
"name": "my-words",
"path": "/Users/username/.cspell-dictionary.txt",
"addWords": true
}
],
"cSpell.dictionaries": [
"my-words"
],
This defines a dictionary named my-words and tells cSpell to use it globally.
The addWords setting allows cSpell to add new words to this dictionary when using its Add Word to Dictionary functionality.
Remove cSpell.userWords
If the same words are currently stored in settings.json:
"cSpell.userWords": [
"CFML",
"CommandBox",
"Fixinator",
"Lucee",
"Ollama"
],
copy those words into .cspell-dictionary.txt, then remove the cSpell.userWords setting.
Your custom words will now be maintained in the global dictionary instead of settings.json.
Adding New Words
When cSpell flags a legitimate word such as:
Ollama
use the cSpell quick fix in VS Code and add the word to the my-words dictionary.
Because the dictionary was configured with:
"addWords": true
new words can be written to:
~/.cspell-dictionary.txt
instead of continually expanding cSpell.userWords in settings.json.
The dictionary will gradually grow as new project-specific terminology, product names, acronyms, and technical terms are encountered.
Result
The VS Code configuration remains small:
"cSpell.dictionaryDefinitions": [
{
"name": "my-words",
"path": "/Users/username/.cspell-dictionary.txt",
"addWords": true
}
],
"cSpell.dictionaries": [
"my-words"
],
while the potentially much larger collection of custom words lives separately in:
~/.cspell-dictionary.txt
This keeps settings.json cleaner and provides a single global dictionary that can be maintained independently of VS Code’s other settings.
