CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-cspell

A comprehensive spell checking tool specifically designed for source code with CLI interface and programmatic API

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

configuration.mddocs/

Configuration

Configuration initialization and management system for creating and updating CSpell configuration files with support for multiple formats, import/export capabilities, and global settings management.

Capabilities

Configuration Initialization

Create new CSpell configuration files with customizable settings, format options, and initial dictionary/locale setup.

/**
 * Initialize a new CSpell configuration file with specified options
 * @param options - Configuration initialization options
 * @returns Promise that resolves when initialization is complete
 */
function createInit(options: InitOptions): Promise<void>;

interface InitOptions {
  /** Path to configuration file (conflicts with output/format options) */
  config?: string;
  /** Define where to write the configuration file */
  output?: string;
  /** File format: yaml, yml, json, or jsonc (default: yaml) */
  format?: string;
  /** Import configuration files or dictionary packages */
  import?: string[];
  /** Define locales for spell checking */
  locale?: string[];
  /** Enable specific dictionaries */
  dictionary?: string[];
  /** Include explanatory comments in config file */
  comments?: boolean;
  /** Add JSON schema reference to config file */
  schema?: boolean;
  /** Write configuration to stdout instead of file */
  stdout?: boolean;
}

Usage Examples:

import { createInit } from "cspell";

// Basic configuration creation
await createInit({
  output: "./cspell.yaml",
  format: "yaml"
});

// Advanced configuration with dictionaries and locales
await createInit({
  output: "./custom-cspell.json",
  format: "json",
  locale: ["en-US", "es-ES"],
  dictionary: ["typescript", "python", "medical"],
  comments: true,
  schema: true
});

// Import existing configurations
await createInit({
  output: "./extended-cspell.yaml",
  import: [
    "./base-cspell.json",
    "@cspell/dict-companies",
    "@cspell/dict-software-terms"
  ],
  dictionary: ["css", "html"]
});

// Create configuration to stdout
await createInit({
  format: "json",
  locale: ["en-GB"],
  dictionary: ["node"],
  stdout: true
});

// Minimal configuration without comments or schema
await createInit({
  output: "./.cspell.json",
  format: "json",
  comments: false,
  schema: false,
  dictionary: ["javascript"]
});

Configuration File Formats

CSpell supports multiple configuration file formats with flexible naming conventions:

// Supported formats and typical filenames
type ConfigFormat = "yaml" | "yml" | "json" | "jsonc";

// Common configuration file names
type ConfigFileName = 
  | "cspell.json" | ".cspell.json"
  | "cspell.yaml" | ".cspell.yaml" 
  | "cspell.yml" | ".cspell.yml"
  | "cspell.config.js" | "cspell.config.cjs"
  | ".cspellrc" | ".cspellrc.json" | ".cspellrc.yaml";

Example Configuration Structures:

# cspell.yaml format
version: "0.2"
language: "en"
words:
  - customword
  - companyname
dictionaries:
  - typescript
  - node
ignoreWords:
  - ignorethis
files:
  - "src/**/*.{ts,js}"
  - "docs/**/*.md"
ignorePaths:
  - "node_modules/**"
  - "dist/**"
{
  "version": "0.2",
  "language": "en",
  "words": ["customword", "companyname"],
  "dictionaries": ["typescript", "node"],
  "ignoreWords": ["ignorethis"],
  "files": ["src/**/*.{ts,js}", "docs/**/*.md"],
  "ignorePaths": ["node_modules/**", "dist/**"]
}

Configuration Import System

Import and extend existing configurations or dictionary packages:

interface ImportConfiguration {
  /** Path to configuration file or npm package name */
  import: string[];
}

// Example import patterns
type ImportPattern = 
  | "./path/to/config.json"           // Relative file path
  | "/absolute/path/to/config.yaml"   // Absolute file path
  | "@cspell/dict-typescript"         // NPM dictionary package
  | "@company/custom-cspell-config"   // Custom configuration package
  | "cspell-config-common";           // Shared configuration module

Usage Examples:

// Import multiple configurations
await createInit({
  output: "./project-cspell.yaml",
  import: [
    "./base-config.json",              // Local base configuration
    "@cspell/dict-typescript",         // TypeScript dictionary
    "@cspell/dict-node",              // Node.js dictionary
    "@company/spelling-standards"      // Company standards
  ],
  dictionary: ["css", "html"],         // Additional dictionaries
  locale: ["en-US"]
});

// Layered configuration approach
await createInit({
  output: "./api-cspell.json",
  import: [
    "./shared/base-cspell.yaml",       // Shared base rules
    "./shared/backend-terms.json"      // Backend-specific terms
  ],
  words: ["apikey", "webhook", "microservice"]
});

Dictionary Management

Configure and manage dictionary usage within configuration files:

interface DictionaryConfiguration {
  /** List of enabled dictionaries by name */
  dictionaries?: string[];
  /** Custom dictionary definitions */
  dictionaryDefinitions?: DictionaryDefinition[];
  /** Language-specific dictionary mappings */
  languageSettings?: LanguageSettings[];
}

interface DictionaryDefinition {
  /** Dictionary identifier name */
  name: string;
  /** Path to dictionary file */
  path: string;
  /** Description of dictionary contents */
  description?: string;
  /** Supported file types */
  scope?: string[];
}

interface LanguageSettings {
  /** Language identifier (e.g., "typescript", "python") */
  languageId: string;
  /** Dictionaries to enable for this language */
  dictionaries?: string[];
  /** Language-specific locale */
  locale?: string;
  /** Custom words for this language */
  words?: string[];
}

Usage Examples:

// Create configuration with custom dictionaries
await createInit({
  output: "./advanced-cspell.yaml",
  format: "yaml",
  dictionary: [
    "typescript",           // Built-in TypeScript dictionary
    "node",                // Built-in Node.js dictionary
    "medical-terms"        // Custom medical dictionary
  ]
});

// The resulting configuration might include:
const exampleConfig = {
  dictionaries: ["typescript", "node", "medical-terms"],
  dictionaryDefinitions: [
    {
      name: "medical-terms",
      path: "./dictionaries/medical.txt",
      description: "Medical terminology for healthcare applications"
    }
  ],
  languageSettings: [
    {
      languageId: "typescript",
      dictionaries: ["typescript", "node"],
      locale: "en-US"
    },
    {
      languageId: "python", 
      dictionaries: ["python", "medical-terms"],
      locale: "en-US"
    }
  ]
};

Locale Configuration

Configure language locales and regional spelling preferences:

interface LocaleConfiguration {
  /** Primary language code (e.g., "en", "es", "fr") */
  language?: string;
  /** Specific locale codes (e.g., "en-US", "en-GB", "es-ES") */
  locale?: string | string[];
  /** Local-specific word additions */
  words?: string[];
  /** Locale-specific ignore patterns */
  ignoreWords?: string[];
}

Usage Examples:

// Multi-locale configuration
await createInit({
  output: "./international-cspell.json",
  locale: ["en-US", "en-GB", "fr-FR", "es-ES"],
  dictionary: ["companies", "software-terms"]
});

// Region-specific configuration
await createInit({
  output: "./uk-cspell.yaml", 
  locale: ["en-GB"],
  dictionary: ["british-english", "legal-uk"]
});

// Multiple locale support with fallbacks
const multiLocaleConfig = {
  language: "en",
  locale: ["en-US", "en-GB"],  // US primary, UK fallback
  words: ["customisation", "colour", "analyse"],  // British spellings
  languageSettings: [
    {
      languageId: "markdown",
      locale: "en-GB"  // Use British English for documentation
    }
  ]
};

File Pattern Configuration

Configure which files to include or exclude from spell checking:

interface FilePatternConfiguration {
  /** Glob patterns for files to include */
  files?: string[];
  /** Glob patterns for paths to ignore */
  ignorePaths?: string[];
  /** Glob patterns specifically for files to ignore */
  ignoreFiles?: string[];
  /** Enable .gitignore file integration */
  gitignore?: boolean;
  /** Base directory for relative paths */
  root?: string;
}

Usage Examples:

// Comprehensive file pattern configuration
await createInit({
  output: "./project-cspell.yaml",
  format: "yaml"
});

// The configuration might include file patterns like:
const filePatternConfig = {
  files: [
    "src/**/*.{ts,js,tsx,jsx}",      // Source code files
    "docs/**/*.{md,mdx}",            // Documentation files
    "tests/**/*.{test,spec}.{ts,js}", // Test files
    "*.{json,yaml,yml}"              // Configuration files
  ],
  ignorePaths: [
    "node_modules/**",               // Dependencies
    "dist/**",                       // Build output
    "coverage/**",                   // Test coverage
    ".git/**",                       // Git files
    "**/*.min.js"                    // Minified files
  ],
  ignoreFiles: [
    "package-lock.json",             // Lock files
    "yarn.lock",
    "*.map"                          // Source maps
  ],
  gitignore: true,                   // Use .gitignore patterns
  root: "./src"                      // Base directory
};

Global Configuration Management

Manage system-wide CSpell settings and dictionary links:

// Global configuration typically stored in:
// ~/.cspell/cspell.json (user-specific)
// /etc/cspell/cspell.json (system-wide)

interface GlobalConfiguration {
  /** Globally enabled dictionaries */
  dictionaries?: string[];
  /** Global word additions */
  words?: string[];
  /** Global ignore patterns */
  ignorePaths?: string[];
  /** Import global configuration packages */
  import?: string[];
}

Usage Examples:

// Create user-specific global configuration
await createInit({
  output: "~/.cspell/cspell.json",
  dictionary: [
    "companies",
    "software-terms", 
    "medical",
    "@mycompany/corporate-terms"
  ],
  locale: ["en-US"],
  comments: true
});

// Project configuration extending global settings
await createInit({
  output: "./cspell.json",
  import: ["~/.cspell/cspell.json"],  // Inherit global settings
  dictionary: ["typescript", "react"], // Add project-specific dictionaries
  words: ["projectname", "apiendpoint"]
});

Advanced Configuration Options

Handle complex configuration scenarios and edge cases:

interface AdvancedConfiguration {
  /** Configuration file version */
  version?: string;
  /** Enable/disable case-sensitive checking */
  caseSensitive?: boolean;
  /** Allow/disallow compound words */
  allowCompoundWords?: boolean;
  /** Minimum word length to check */
  minWordLength?: number;
  /** Maximum number of suggestions to generate */
  maxNumberOfProblems?: number;
  /** Maximum duplicate problems per file */
  maxDuplicateProblems?: number;
  /** Custom regular expressions for word parsing */
  patterns?: PatternDefinition[];
  /** Validation rules for in-document directives */
  validateDirectives?: boolean;
}

interface PatternDefinition {
  /** Pattern name identifier */
  name: string;
  /** Regular expression pattern */
  pattern: string;
  /** Description of what the pattern matches */
  description?: string;
}

Usage Examples:

// Advanced configuration with custom patterns
const advancedConfig = {
  version: "0.2",
  caseSensitive: false,
  allowCompoundWords: true,
  minWordLength: 3,
  maxNumberOfProblems: 100,
  patterns: [
    {
      name: "UUIDs",
      pattern: "/\\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\\b/gi",
      description: "UUID patterns to ignore"
    },
    {
      name: "HexColors", 
      pattern: "/#[0-9a-fA-F]{3,8}\\b/g",
      description: "CSS hex color codes"
    }
  ],
  validateDirectives: true
};

await createInit({
  output: "./regex-cspell.json",
  format: "json",
  dictionary: ["css", "html"]
});

Configuration File Examples

Basic Project Configuration

# Basic cspell.yaml for TypeScript project
version: "0.2"
language: "en-US"
dictionaries:
  - typescript
  - node
  - npm
files:
  - "src/**/*.{ts,tsx}"
  - "tests/**/*.{ts,spec.ts}"
  - "*.md"
ignoreWords:
  - "transpiled"
  - "polyfill"
words:
  - "MyCompany"
  - "productname"

Enterprise Configuration

{
  "version": "0.2",
  "language": "en-US",
  "import": [
    "@mycompany/cspell-config",
    "@cspell/dict-companies"
  ],
  "dictionaries": [
    "typescript",
    "node", 
    "medical",
    "legal"
  ],
  "languageSettings": [
    {
      "languageId": "typescript",
      "dictionaries": ["typescript", "node"],
      "caseSensitive": false
    },
    {
      "languageId": "markdown",
      "dictionaries": ["companies", "medical"],
      "allowCompoundWords": true
    }
  ],
  "files": [
    "src/**/*.{ts,tsx,js,jsx}",
    "docs/**/*.{md,mdx}",
    "api/**/*.yaml"
  ],
  "ignorePaths": [
    "node_modules/**",
    "dist/**",
    "coverage/**"
  ],
  "words": ["companyname", "productline"],
  "minWordLength": 3,
  "maxNumberOfProblems": 1000
}

Install with Tessl CLI

npx tessl i tessl/npm-cspell

docs

cli-commands.md

configuration.md

index.md

programmatic-api.md

reporters.md

tile.json