Language Configuration Guide (original) (raw)

In this article

The contributes.languages Contribution Point allows you to define a language configuration that controls the following Declarative Language Features:

Here is a Language Configuration sample that configures the editing experience for JavaScript files. This guide explains the content of language-configuration.json:

Note: If your language configuration file name is or ends with language-configuration.json, you will get autocompletion and validation in VS Code.

{
  "comments": {
    "lineComment": "//",
    "blockComment": ["/*", "*/"]
  },
  "brackets": [
    ["{", "}"],
    ["[", "]"],
    ["(", ")"]
  ],
  "autoClosingPairs": [
    { "open": "{", "close": "}" },
    { "open": "[", "close": "]" },
    { "open": "(", "close": ")" },
    { "open": "'", "close": "'", "notIn": ["string", "comment"] },
    { "open": "\"", "close": "\"", "notIn": ["string"] },
    { "open": "`", "close": "`", "notIn": ["string", "comment"] },
    { "open": "/**", "close": " */", "notIn": ["string"] }
  ],
  "autoCloseBefore": ";:.,=}])>` \n\t",
  "surroundingPairs": [
    ["{", "}"],
    ["[", "]"],
    ["(", ")"],
    ["'", "'"],
    ["\"", "\""],
    ["`", "`"]
  ],
  "folding": {
    "markers": {
      "start": "^\\s*//\\s*#?region\\b",
      "end": "^\\s*//\\s*#?endregion\\b"
    }
  },
  "wordPattern": "(-?\\d*\\.\\d\\w*)|([^\\`\\~\\!\\@\\#\\%\\^\\&\\*\\(\\)\\-\\=\\+\\[\\{\\]\\}\\\\\\|\\;\\:\\'\\\"\\,\\.\\<\\>\\/\\?\\s]+)",
  "indentationRules": {
    "increaseIndentPattern": "^((?!\\/\\/).)*(\\{[^}\"'`]*|\\([^)\"'`]*|\\[[^\\]\"'`]*)$",
    "decreaseIndentPattern": "^((?!.*?\\/\\*).*\\*/)?\\s*[\\)\\}\\]].*$"
  }
}

VS Code offers two commands for comment toggling. Toggle Line Comment and Toggle Block Comment. You can specify comments.blockComment and comments.lineComment to control how VS Code should comment out lines / blocks.

{
  "comments": {
    "lineComment": "//",
    "blockComment": ["/*", "*/"]
  }
}

Brackets definition

When you move the cursor to a bracket defined here, VS Code will highlight that bracket together with its matching pair.

{
  "brackets": [
    ["{", "}"],
    ["[", "]"],
    ["(", ")"]
  ]
}

Moreover, when you run Go to Bracket or Select to Bracket, VS Code will use the definition above to find the nearest bracket and its matching pair.

Autoclosing

When you type ', VS Code creates a pair of single quotes and puts your cursor in the middle: '|'. This section defines such pairs.

{
  "autoClosingPairs": [
    { "open": "{", "close": "}" },
    { "open": "[", "close": "]" },
    { "open": "(", "close": ")" },
    { "open": "'", "close": "'", "notIn": ["string", "comment"] },
    { "open": "\"", "close": "\"", "notIn": ["string"] },
    { "open": "`", "close": "`", "notIn": ["string", "comment"] },
    { "open": "/**", "close": " */", "notIn": ["string"] }
  ]
}

The notIn key disables this feature in certain code ranges. For example, when you are writing the following code:

// ES6's Template String
`ES6's Template String`;

The single quote will not be autoclosed.

Pairs that do not require a notIn property can also use a simpler syntax:

{
  "autoClosingPairs": [
    ["{", "}"],
    ["[", "]"]
  ]
}

Users can tweak the autoclosing behavior with the editor.autoClosingQuotes and editor.autoClosingBrackets settings.

Autoclosing before

By default, VS Code only autocloses pairs if there is whitespace right after the cursor. So when you type { in the following JSX code, you would not get autoclose:

const Component = () =>
  <div className={>
                  ^ Does not get autoclosed by default
  </div>

However, this definition overrides that behavior:

{
  "autoCloseBefore": ";:.,=}])>` \n\t"
}

Now when you enter { right before >, VS Code autocloses it with }.

Autosurrounding

When you select a range in VS Code and enter an opening bracket, VS Code surrounds the selected content with a pair of brackets. This feature is called Autosurrounding, and here you can define the autosurrounding pairs for a specific language:

{
  "surroundingPairs": [
    ["{", "}"],
    ["[", "]"],
    ["(", ")"],
    ["'", "'"],
    ["\"", "\""],
    ["`", "`"]
  ]
}

Users can tweak the autosurrounding behavior with the editor.autoSurround setting.

Folding

In VS Code, folding is defined either indentation-based, or defined by contributed folding range providers:

The following JSON creates folding markers for //#region and //#endregion.

{
  "folding": {
    "markers": {
      "start": "^\\s*//\\s*#?region\\b",
      "end": "^\\s*//\\s*#?endregion\\b"
    }
  }
}

Word Pattern

wordPattern defines what's considered as a word in the programming language. Code suggestion features will use this setting to determine word boundaries if wordPattern is set. Note this setting won't affect word-related editor commands, which are controlled by the editor setting editor.wordSeparators.

{
  "wordPattern": "(-?\\d*\\.\\d\\w*)|([^\\`\\~\\!\\@\\#\\%\\^\\&\\*\\(\\)\\-\\=\\+\\[\\{\\]\\}\\\\\\|\\;\\:\\'\\\"\\,\\.\\<\\>\\/\\?\\s]+)"
}

Indentation Rules

indentationRules defines how the editor should adjust the indentation of current line or next line when you type, paste, and move lines.

{
  "indentationRules": {
    "increaseIndentPattern": "^((?!\\/\\/).)*(\\{[^}\"'`]*|\\([^)\"'`]*|\\[[^\\]\"'`]*)$",
    "decreaseIndentPattern": "^((?!.*?\\/\\*).*\\*/)?\\s*[\\)\\}\\]].*$"
  }
}

For example, if (true) { matches increaseIndentPattern, then if you press Enter after the open bracket {, the editor will automatically indent once, and your code will end up as:

if (true) {
  console.log();

In addition to increaseIndentPattern and decreaseIndentPattern, there are two other indentation rules:

If there is no indentation rule set for the programming language, the editor will indent when the line ends with an open bracket and outdent when you type a closing bracket. The bracket here is defined by brackets.

Notice that editor.formatOnPaste setting is controlled by the DocumentRangeFormattingEditProvider and not affected by auto indentation.

On Enter Rules

onEnterRules defines a list of rules that will be evaluated when Enter is pressed in the editor.

{
  "onEnterRules": [
    {
      "beforeText": "^\\s*(?:def|class|for|if|elif|else|while|try|with|finally|except|async).*?:\\s*$",
      "action": { "indent": "indent" }
    }
  ]
}

When pressing Enter, the text before, after, or one line above the cursor is checked against the following properties:

If all the specified properties match, the rule is considered to match and no further onEnterRules will be evaluated. An onEnterRule can specify the following actions:

05/08/2025