VSCode Settings Formatter

A generic, pluggable JSONC formatter designed specifically for organizing VSCode settings.json files. This library provides the core logic for formatting and organizing settings, with a focus on preserving comments and unaffected structure.

Features

• Generic & Agnostic: Can be used in any Node.js/Bun environment, not just within VSCode.
• Preserves Unaffected Content: Only formats nodes that match active formatting rules.
• Comment Preservation: Maintains comments and associates them with the correct lines.
• Pluggable Architecture: Easily add new formatting rules.
• Vim Keybindings Support: Built-in rule to organize VSCode Vim keybindings.

Installation

npm install vscode-settings-formatter
# or
bun add vscode-settings-formatter

Usage

CLI

After installation, you can use the CLI to format your settings files:

# Format and output to stdout
vscode-settings-formatter settings.json

# Save to a new file
vscode-settings-formatter settings.json > formatted.json

# In-place formatting (using sponge from moreutils)
vscode-settings-formatter settings.json | sponge settings.json

Options:

• --help, -h - Show help message

Simple Usage (Recommended)

import { formatVSCodeSettings } from "vscode-settings-formatter";

const content = `{ ... }`;
const result = formatVSCodeSettings(content);

if (result.success) {
  console.log(result.formattedText);
} else {
  console.error(result.error);
}

Advanced Usage (Custom Rules)

import { FormatterEngine, VimKeybindingsRule } from "vscode-settings-formatter";

// 1. Configure rules
const rules = [
  new VimKeybindingsRule(true) // Enable Vim keybindings formatting
];

// 2. Create engine
const engine = new FormatterEngine(rules);

// 3. Format
const result = engine.format(content);

if (result.success) {
  console.log(result.formattedText);
} else {
  console.error(result.error);
}

Formatting Rules

The formatVSCodeSettings function applies all available formatting rules by default:

Vim Keybindings Rule

Formats and groups keybindings for the VSCode Vim extension across all vim keybinding properties:

• vim.normalModeKeyBindings / vim.normalModeKeyBindingsNonRecursive
• vim.visualModeKeyBindings / vim.visualModeKeyBindingsNonRecursive
• vim.insertModeKeyBindings
• vim.commandLineModeKeyBindings
• vim.operatorPendingModeKeyBindings

Grouping Strategy:

Keybindings are grouped hierarchically by their first two keys in the before sequence:

1. <leader> combinations - Grouped by second key (e.g., all <leader> + t together)

   • Alphabetical by second key (<leader> + j, then <leader> + t)
   • Sorted alphabetically within each group

2. Modifier keys - <C-...> (Control) and <S-...> (Shift) combinations

   • Grouped and sorted alphabetically

3. Special keys - Other angle-bracket keys like <Esc>, <Tab>, etc.

4. Two-key combinations - Regular keys pressed in sequence (e.g., g + d, g + p)

   • Grouped by first two keys
   • Sorted alphabetically within groups

5. Bracket keys - [, ], <, > standalone

6. Repeated keys - Same key pressed twice (e.g., d + d)

7. Single keys - Single key bindings

Features:

• Preserves comments and associates them with their keybindings
• Maintains commented-out keybindings in their original form
• Groups are separated by blank lines for readability
• Bindings within groups are sorted alphabetically

Before:

"vim.normalModeKeyBindings": [
  { "before": ["g", "p", "d"], "commands": ["editor.action.peekDefinition"] },
  { "before": ["<leader>", "t", "c"], "commands": ["testing.runAtCursor"] },
  { "before": ["<leader>", "t", "f"], "commands": ["testing.runCurrentFile"] },
  { "before": ["<leader>", "j", "w"], "commands": ["workbench.action.switchWindow"] },
  { "before": ["g", "p", "r"], "commands": ["editor.action.goToReferences"] },
  { "before": ["g", "d"], "commands": ["editor.action.revealDefinition"] },
]

After:

"vim.normalModeKeyBindings": [
  { "before": ["<leader>", "j", "w"], "commands": ["workbench.action.switchWindow"] },

  { "before": ["<leader>", "t", "c"], "commands": ["testing.runAtCursor"] },
  { "before": ["<leader>", "t", "f"], "commands": ["testing.runCurrentFile"] },

  { "before": ["g", "d"], "commands": ["editor.action.revealDefinition"] },

  { "before": ["g", "p", "d"], "commands": ["editor.action.peekDefinition"] },
  { "before": ["g", "p", "r"], "commands": ["editor.action.goToReferences"] },
]

Apply To All Profiles Rule

Automatically updates workbench.settings.applyToAllProfiles to include all root-level keys in your settings file, ensuring consistent settings across all profiles.

Before:

{
  "editor.fontSize": 14,
  "workbench.colorTheme": "Dark+",
  "workbench.settings.applyToAllProfiles": ["editor.fontSize"]
}

After:

{
  "editor.fontSize": 14,
  "workbench.colorTheme": "Dark+",
  "workbench.settings.applyToAllProfiles": [
    "editor.fontSize",
    "workbench.colorTheme"
  ]
}

Workbench Settings Rule

Formats workbench-related settings for consistency.

Other Rule

Organizes all other settings alphabetically, grouping by:

1. Known properties (handled by specific rules) appear first
2. Primitive values (strings, numbers, booleans) grouped by namespace
3. Complex values (objects, arrays) grouped by namespace

Block Sorting with >> and << Markers:

Properties can be grouped into blocks using special comment markers:

• // >> marks the start of a block
• // << marks the end of a block

Properties within a block are sorted internally according to the standard rules, but the entire block is treated as a single unit and sorted based on the key of the first property within the block.

Before:

{
  "window.zoomLevel": 0,
  "editor.fontSize": 14,
  // >> ------
  // Block of file and terminal settings
  "files.autoSave": "afterDelay",
  "terminal.integrated.fontSize": 12,
  "files.exclude": {
    "**/.git": true
  },
  // << ------
  "editor.minimap.enabled": false
}

After:

{
  "editor.fontSize": 14,
  "editor.minimap.enabled": false,

  // >> ------
  // Block of file and terminal settings
  "files.autoSave": "afterDelay",
  "files.exclude": {
    "**/.git": true
  },
  "terminal.integrated.fontSize": 12,
  // << ------

  "window.zoomLevel": 0
}

For complete formatting logic and detailed examples, see SPEC.md.

Development

This project uses Bun for development and testing.

# Install dependencies
bun install

# Run tests
bun test

# Build
bun run build

License

MIT