Prettier CSpell Plugin

0.3.0 verified Sat Apr 25 auth: no javascript

A Prettier plugin that sorts dictionary keys in CSpell configuration files, ensuring consistent ordering of words, flagWords, ignoreWords, etc. Version 0.3.0 requires Prettier ^3 and ships TypeScript types. It is the only dedicated plugin for alphabetizing CSpell dictionary entries, focusing on lint-time ordering rather than runtime linting. The plugin is actively maintained with a small scope (dictionary file sorting only; config sorting planned). Alternative: manual sorting or other generic JSON sorters that don't understand CSpell structure.

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module ↓

cause Using CommonJS require() to load the plugin.

fix

Use dynamic import() in scripts, or reference the plugin by string name in Prettier config (e.g., 'prettier-plugin-cspell').

error Cannot find module 'prettier-plugin-cspell' ↓

cause Plugin not installed or not in node_modules.

fix

Run 'npm install -D prettier-plugin-cspell' and ensure it's in package.json.

error prettier --write did not sort my CSpell file ↓

cause Plugin is not registered in Prettier config, or the file is not matched by Prettier's file pattern.

fix

Add 'plugins: ["prettier-plugin-cspell"]' to .prettierrc. Ensure the file has a supported extension (e.g., .json, .yaml) and is within Prettier's range.

Warnings

breaking Requires Prettier 3 or higher. Will not work with Prettier 2. ↓

fix Upgrade Prettier to ^3.0.0

breaking Package is ESM-only. CommonJS require() will throw ERR_REQUIRE_ESM. ↓

fix Use dynamic import() or configure Prettier's plugins array with a string (e.g., 'prettier-plugin-cspell').

gotcha Only sorts dictionary keys (words, flagWords, ignoreWords) in CSpell JSON/YAML files. Does not sort other properties or config keys. ↓

fix Current scope is limited; check documentation for planned features.

gotcha Plugin may interfere with other Prettier plugins if they also modify the same file types. Ensure plugin order in the plugins array. ↓

fix Place this plugin last in the plugins array to avoid conflicts.

Install

npm install prettier-plugin-cspell

yarn add prettier-plugin-cspell

pnpm add prettier-plugin-cspell

Imports

default

wrong

const prettierPluginCspell = require('prettier-plugin-cspell')

correct

import prettierPluginCspell from 'prettier-plugin-cspell'

Package is ESM-only. Use dynamic import() or configure Prettier's plugins array with a string path.

plugins

wrong

// Incorrect if using require(): plugins: [require('prettier-plugin-cspell')] (only works with ESM loader)

correct

// In .prettierrc: { "plugins": ["prettier-plugin-cspell"] }

Prettier accepts plugin names as strings in config. Node.js require() may fail due to ESM-only.

type definitions
```
import type { Plugin } from 'prettier'; // types provided
```
TypeScript types are bundled. No separate @types package needed.

Quickstart

Installation and basic usage of prettier-plugin-cspell to alphabetically sort CSpell dictionary words.

// 1. Install
npm i -D prettier prettier-plugin-cspell

// 2. Configure .prettierrc
{
  "plugins": ["prettier-plugin-cspell"]
}

// 3. Create a CSpell dictionary file (e.g., .cspell/dictionary.txt or cspell.json words array)
// The plugin will sort the words alphabetically on format.

// Example cspell.json before:
{
  "words": ["zebra", "apple", "mango"]
}

// After running prettier --write:
{
  "words": ["apple", "mango", "zebra"]
}