Contribution Points

Contribution Points are a set of JSON declarations that you make in the contributes field of the package.json Extension Manifest. Your extension registers Contribution Points to extend various functionalities within Visual Studio Code. Here is a list of all available Contribution Points:

contributes.configuration

Contribute configuration keys that will be exposed to the user. The user will be able to set these configuration options as User Settings or as Workspace Settings, either by using the Settings UI or by editing the JSON settings file directly.

Configuration example

  1. {
  2.   "contributes": {
  3.     "configuration": {
  4.       "title": "TypeScript",
  5.       "properties": {
  6.         "typescript.useCodeSnippetsOnMethodSuggest": {
  7.           "type": "boolean",
  8.           "default": false,
  9.           "description": "Complete functions with their parameter signature."
  10.         },
  11.         "typescript.tsdk": {
  12.           "type": ["string", "null"],
  13.           "default": null,
  14.           "description": "Specifies the folder path containing the tsserver and lib*.d.ts files to use."
  15.         }
  16.       }
  17.     }
  18.   }
  19. }

configuration extension point example

You can read these values from your extension using vscode.workspace.getConfiguration('myExtension').

Configuration schema

Your configuration entry is used both to provide intellisense when editing your settings in the JSON editor, and to define the way they appear in the settings UI.

settings UI screenshot with numbers

title

The title 1️⃣️ is the main heading that will be used for your configuration section. Normally you will only have one section for your extension.

  1. {
  2.   "configuration": {
  3.     "title": "GitMagic"
  4.   }
  5. }

The title should be the exact name of your extension. Words like “Extension”, “Configuration”, and “Settings” are redundant.

  • ✔ "title": "GitMagic"
  • ❌ "title": "GitMagic Extension"
  • ❌ "title": "GitMagic Configuration"
  • ❌ "title": "GitMagic Extension Configuration Settings"

properties

The properties 2️⃣ in your configuration will be a dictionary of configuration properties.

In the Settings UI, your configuration key will be used to namespace and construct a title. Capital letters in your key are used to indicate word breaks. For example, if your key is gitMagic.blame.dateFormat, the generated title for the setting will look like this:

Blame: Date Format

Entries will be grouped according to the hierarchy established in your keys. So for example, these entries

  1. gitMagic.blame.dateFormat
  2. gitMagic.blame.format
  3. gitMagic.blame.heatMap.enabled
  4. gitMagic.blame.heatMap.location

will appear in a single group like this:

Blame: Date Format

Blame: Format

Blame › Heatmap: Enabled

Blame › Heatmap: Location

Otherwise, properties appear in alphabetical order (not the order in which they’re listed in the manifest).

Configuration property schema

Configuration keys are defined using a superset of JSON Schema.

description / markdownDescription

Your description 3️⃣ appears after the title and before the input field, except for booleans, where the description is used as the label for the checkbox. 6️⃣

  1. {
  2.   "gitMagic.blame.heatmap.enabled": {
  3.     "description": "Specifies whether to provide a heatmap indicator in the gutter blame annotations"
  4.   }
  5. }

If you use markdownDescription instead of description, your setting description will be rendered as Markdown in the settings UI.

  1. {
  2.   "gitMagic.blame.dateFormat": {
  3.     "markdownDescription": "Specifies how to format absolute dates (e.g. using the `${date}` token) in gutter blame annotations. See the [Moment.js docs](https://momentjs.com/docs/#/displaying/format/) for valid formats"
  4.   }
  5. }

type

Entries of type number 4️⃣ , string 5️⃣ , boolean 6️⃣ can be edited directly in the Settings UI.

  1. {
  2.   "gitMagic.views.pageItemLimit": {
  3.     "type": "number",
  4.     "default": 20,
  5.     "markdownDescription": "Specifies the number of items to show in each page when paginating a view list. Use 0 to specify no limit"
  6.   }
  7. }

For boolean entries, the description (or markdownDescription) will be used as the label for the checkbox.

  1. {
  2.   "gitMagic.blame.compact": {
  3.     "type": "boolean",
  4.     "description": "Specifies whether to compact (deduplicate) matching adjacent gutter blame annotations"
  5.   }
  6. }

Other types, such as object and array, aren’t exposed directly in the settings UI, and can only be modified by editing the JSON directly. Instead of controls for editing them, users will see a link to Edit in settings.json as shown in the screenshot above. 8️⃣

enum / enumDescriptions

If you provide an array of items under the enum 7️⃣ property, the settings UI will render a dropdown menu.

settings UI screenshot of dropdown

You can also provide an enumDescriptions property, which provides descriptive text rendered at the bottom of the dropdown:

  1. {
  2.   "gitMagic.blame.heatmap.location": {
  3.     "type": "string",
  4.     "default": "right",
  5.     "enum": ["left", "right"],
  6.     "enumDescriptions": [
  7.       "Adds a heatmap indicator on the left edge of the gutter blame annotations",
  8.       "Adds a heatmap indicator on the right edge of the gutter blame annotations"
  9.     ]
  10.   }
  11. }

You can also use markdownEnumDescriptions, and your descriptions will be rendered as markdown.

deprecationMessage / markdownDeprecationMessage

If you set deprecationMessage, or markdownDeprecationMessage, the setting will get a warning underline with your specified message. It won’t show up in the settings UI unless it is configured by the user. If you set markdownDeprecationMessage, the markdown will not be rendered in the setting hover or the problems view. If you set both properties, deprecationMessage will be shown in the hover and the problems view, and markdownDeprecationMessage will be rendered as markdown in the settings UI.

Example:

  1. {
  2.   "json.colorDecorators.enable": {
  3.     "type": "boolean",
  4.     "description": "Enables or disables color decorators",
  5.     "markdownDeprecationMessage": "**Deprecated**: Please use `#editor.colorDecorators#` instead.",
  6.     "deprecationMessage": "Deprecated: Please use editor.colorDecorators instead."
  7.   }
  8. }

Other JSON Schema properties

You can use any of the validation JSON Schema properties to describe other constraints on configuration values:

  • default for defining the default value of a property
  • minimum and maximum for restricting numeric values
  • maxLength, minLength for restricting string length
  • pattern for restricting strings to a given regular expression
  • patternErrorMessage for giving a tailored error message when a pattern does not match.
  • format for restricting strings to well-known formats, such as date, time, ipv4, email, and uri
  • maxItems, minItems for restricting array length

Unsupported JSON Schema properties

Not supported in the configuration section are:

  • $ref and definition: The configuration schemas needs to be self-contained and can not make assumptions how the aggregated settings JSON schema document looks like.

For more details on these and other features, see the JSON Schema Reference.

scope

A configuration setting can have one of the following possible scopes:

  • application - Settings that apply to all instances of VS Code and can only be configured in user settings.
  • machine - Machine specific settings that can be set in user or remote settings. For example, an installation path which shouldn’t be shared across machines.
  • machine-overridable - Machine specific settings that can be overridden by workspace or folder settings.
  • window - Windows (instance) specific settings which can be configured in user, workspace, or remote settings.
  • resource - Resource settings, which apply to files and folders, and can be configured in all settings levels, even folder settings.
  • language-overridable - Resource settings that can be overridable at a language level.

Configuration scopes determine when a setting is available to the user through the Settings editor and whether the setting is applicable. If no scope is declared, the default is window.

Below are example configuration scopes from the built-in Git extension:

  1. {
  2.   "contributes": {
  3.     "configuration": {
  4.       "title": "Git",
  5.       "properties": {
  6.         "git.alwaysSignOff": {
  7.           "type": "boolean",
  8.           "scope": "resource",
  9.           "default": false,
  10.           "description": "%config.alwaysSignOff%"
  11.         },
  12.         "git.ignoredRepositories": {
  13.           "type": "array",
  14.           "default": [],
  15.           "scope": "window",
  16.           "description": "%config.ignoredRepositories%"
  17.         }
  18.       }
  19.     }
  20.   }
  21. }

You can see that git.alwaysSignOff has resource scope and can be set per user, workspace, or folder, while the ignored repositories list with window scope applies more globally for the VS Code window or workspace (which might be multi-root).

Linking to settings

You can insert a link to another setting, which will be rendered as a clickable link in the settings UI, by using this special syntax in the markdown-type properties: `#target.setting.id#` . This will work in markdownDescription, markdownEnumDescriptions, and markdownDeprecationMessage. Example:

  1.   "files.autoSaveDelay": {
  2.     "markdownDescription": "Controls the delay in ms after which a dirty editor is saved automatically. Only applies when `#files.autoSave#` is set to `afterDelay`.",
  3.     // ...
  4.   }

In the settings UI, this is rendered as:

setting link example

contributes.configurationDefaults

Contribute default language-specific editor configurations. This will override default editor configurations for the provided language.

The following example contributes default editor configurations for the markdown language:

Configuration default example

  1. {
  2.   "contributes": {
  3.     "configurationDefaults": {
  4.       "[markdown]": {
  5.         "editor.wordWrap": "on",
  6.         "editor.quickSuggestions": false
  7.       }
  8.     }
  9.   }
  10. }

contributes.commands

Contribute the UI for a command consisting of a title and (optionally) an icon, category, and enabled state. Enablement is expressed with when clauses. By default, commands show in the Command Palette (⇧⌘P (Windows, Linux Ctrl+Shift+P)) but they can also show in other menus.

Presentation of contributed commands depends on the containing menu. The Command Palette, for instance, prefixes commands with their category, allowing for easy grouping. However, the Command Palette doesn’t show icons nor disabled commands. The editor context menu, on the other hand, shows disabled items but doesn’t show the category label.

Note: When a command is invoked (from a key binding, from the Command Palette, any other menu, or programmatically), VS Code will emit an activationEvent onCommand:${command}.

command example

  1. {
  2.   "contributes": {
  3.     "commands": [
  4.       {
  5.         "command": "extension.sayHello",
  6.         "title": "Hello World",
  7.         "category": "Hello",
  8.         "icon": {
  9.           "light": "path/to/light/icon.svg",
  10.           "dark": "path/to/dark/icon.svg"
  11.         }
  12.       }
  13.     ]
  14.   }
  15. }

See the Commands Extension Guide to learn more about using commands in VS Code extensions.

commands extension point example

Command icon specifications

  • Size: Icons should be 16x16 with a 1 pixel padding (image is 14x14) and centered.
  • Color: Icons should use a single color.
  • Format: It is recommended that icons be in SVG, though any image file type is accepted.

command icons

contributes.menus

Contribute a menu item for a command to the editor or Explorer. The menu item definition contains the command that should be invoked when selected and the condition under which the item should show. The latter is defined with the when clause, which uses the key bindings when clause contexts.

In addition to the mandatory command property, an alternative command can be defined using the alt-property. It will be shown and invoked when pressing Alt while opening a menu.

Last, a group property defines sorting and grouping of menu items. The navigation group is special as it will always be sorted to the top/beginning of a menu.

Note that when clauses apply to menus and enablement clauses to commands. The enablement applies to all menus and even keybindings while the when only applies to a single menu.

Currently extension writers can contribute to:

  • The global Command Palette - commandPalette
  • The Explorer context menu - explorer/context
  • The editor context menu - editor/context
  • The editor title menu bar - editor/title
  • The editor title context menu - editor/title/context
  • The debug callstack view context menu - debug/callstack/context
  • The debug callstack view inline actions - debug/callstack/context group inline
  • The debug toolbar - debug/toolbar
  • The SCM title menu - scm/title
  • SCM resource groups menus - scm/resourceGroup/context
  • SCM resources menus - scm/resourceState/context
  • SCM change title menus - scm/change/title
  • The View title menu - view/title
  • The View item menu - view/item/context
  • The macOS Touch Bar - touchBar
  • The comment thread title menu bar - comments/commentThread/title
  • The comment thread context menu - comments/commentThread/context
  • The comment title menu bar - comments/comment/title
  • The comment context menu - comments/comment/context
  • The Timeline view title menu bar - timeline/title
  • The Timeline view item context menu - timeline/item/context
  • The Extensions view context menu - extension/context

Note: When a command is invoked from a (context) menu, VS Code tries to infer the currently selected resource and passes that as a parameter when invoking the command. For instance, a menu item inside the Explorer is passed the URI of the selected resource and a menu item inside an editor is passed the URI of the document.

In addition to a title, commands can also define icons which VS Code will show in the editor title menu bar.

menu example

  1. {
  2.   "contributes": {
  3.     "menus": {
  4.       "editor/title": [
  5.         {
  6.           "when": "resourceLangId == markdown",
  7.           "command": "markdown.showPreview",
  8.           "alt": "markdown.showPreviewToSide",
  9.           "group": "navigation"
  10.         }
  11.       ]
  12.     }
  13.   }
  14. }

menus extension point example

Context specific visibility of Command Palette menu items

When registering commands in package.json, they will automatically be shown in the Command Palette (⇧⌘P (Windows, Linux Ctrl+Shift+P)). To allow more control over command visibility, there is the commandPalette menu item. It allows you to define a when condition to control if a command should be visible in the Command Palette or not.

The snippet below makes the ‘Hello World’ command only visible in the Command Palette when something is selected in the editor:

  1. {
  2.   "commands": [
  3.     {
  4.       "command": "extension.sayHello",
  5.       "title": "Hello World"
  6.     }
  7.   ],
  8.   "menus": {
  9.     "commandPalette": [
  10.       {
  11.         "command": "extension.sayHello",
  12.         "when": "editorHasSelection"
  13.       }
  14.     ]
  15.   }
  16. }

Sorting of groups

Menu items can be sorted into groups. They are sorted in lexicographical order with the following defaults/rules. You can add menu items to these groups or add new groups of menu items in between, below, or above.

The editor context menu has these default groups:

  • navigation - The navigation group comes first in all cases.
  • 1_modification - This group comes next and contains commands that modify your code.
  • 9_cutcopypaste - The second last default group with the basic editing commands.
  • z_commands - The last default group with an entry to open the Command Palette.

Menu Group Sorting

The explorer context menu has these default groups:

  • navigation - Commands related to navigation across VS Code. This group comes first in all cases.
  • 2_workspace - Commands related to workspace manipulation.
  • 3_compare - Commands related to comparing files in the diff editor.
  • 4_search - Commands related to searching in the search view.
  • 5_cutcopypaste - Commands related to cutting, copying, and pasting of files.
  • 6_copypath - Commands related to copying file paths.
  • 7_modification - Commands related to the modification of file.

The editor tab context menu has these default groups:

  • 1_close - Commands related to closing editors.
  • 3_preview - Commands related to pinning editors.

The editor title menu has these default groups:

  • navigation - Commands related to navigating.
  • 1_run - Commands related to running and debugging the editor.
  • 1_diff - Commands related to working with diff editors.
  • 3_open - Commands related to opening editors.
  • 5_close - Commands related to closing editors.

navigation and 1_run are shown in the primary editor title area. The other groups are shown in the secondary area - under the ... menu.

The Timeline view item context menu has these default groups:

  • inline - Important or frequently used timeline item commands. Rendered as a toolbar.
  • 1_actions - Commands related to working with timeline items.
  • 5_copy - Commands related to copying timeline item information.

The Extensions view context menu has these default groups:

  • 1_copy - Commands related to copying extension information.
  • 2_configure - Commands related to configuring an extension.

Sorting inside groups

The order inside a group depends on the title or an order-attribute. The group-local order of a menu item is specified by appending @<number> to the group identifier as shown below:

  1. {
  2.   "editor/title": [
  3.     {
  4.       "when": "editorHasSelection",
  5.       "command": "extension.Command",
  6.       "group": "myGroup@1"
  7.     }
  8.   ]
  9. }

contributes.keybindings

Contribute a key binding rule defining what command should be invoked when the user presses a key combination. See the Key Bindings topic where key bindings are explained in detail.

Contributing a key binding will cause the Default Keyboard Shortcuts to display your rule, and every UI representation of the command will now show the key binding you have added. And, of course, when the user presses the key combination the command will be invoked.

Note: Because VS Code runs on Windows, macOS and Linux, where modifiers differ, you can use “key” to set the default key combination and overwrite it with a specific platform.

Note: When a command is invoked (from a key binding or from the Command Palette), VS Code will emit an activationEvent onCommand:${command}.

keybinding example

Defining that Ctrl+F1 under Windows and Linux and Cmd+F1 under macOS trigger the "extension.sayHello" command:

  1. {
  2.   "contributes": {
  3.     "keybindings": [
  4.       {
  5.         "command": "extension.sayHello",
  6.         "key": "ctrl+f1",
  7.         "mac": "cmd+f1",
  8.         "when": "editorTextFocus"
  9.       }
  10.     ]
  11.   }
  12. }

keybindings extension point example

contributes.languages

Contribute definition of a language. This will introduce a new language or enrich the knowledge VS Code has about a language.

The main effects of contributes.languages are:

  • Define a languageId that can be reused in other parts of VS Code API, such as vscode.TextDocument.getLanguageId() and the onLanguage Activation Events.
    • You can contribute a human-readable using the aliases field. The first item in the list will be used as the human-readable label.
  • Associate file name extensions, file name patterns, files that begin with a specific line (such as hashbang), mimetypes to that languageId.
  • Contribute a set of Declarative Language Features for the contributed language. Learn more about the configurable editing features in the Language Configuration Guide.

language example

  1. {
  2.   "contributes": {
  3.     "languages": [
  4.       {
  5.         "id": "python",
  6.         "extensions": [".py"],
  7.         "aliases": ["Python", "py"],
  8.         "filenames": [],
  9.         "firstLine": "^#!/.*\\bpython[0-9.-]*\\b",
  10.         "configuration": "./language-configuration.json"
  11.       }
  12.     ]
  13.   }
  14. }

contributes.debuggers

Contribute a debugger to VS Code. A debugger contribution has the following properties:

  • type is a unique ID that is used to identify this debugger in a launch configuration.
  • label is the user visible name of this debugger in the UI.
  • program the path to the debug adapter that implements the VS Code debug protocol against the real debugger or runtime.
  • runtime if the path to the debug adapter is not an executable but needs a runtime.
  • configurationAttributes is the schema for launch configuration arguments specific to this debugger. Please note that the JSON schema constructs $ref and definition are not supported.
  • initialConfigurations lists launch configurations that are used to populate an initial launch.json.
  • configurationSnippets lists launch configurations that are available through IntelliSense when editing a launch.json.
  • variables introduces substitution variables and binds them to commands implemented by the debugger extension.
  • languages those languages for which the debug extension could be considered the “default debugger”.

debugger example

  1. {
  2.   "contributes": {
  3.     "debuggers": [
  4.       {
  5.         "type": "node",
  6.         "label": "Node Debug",
  8.         "program": "./out/node/nodeDebug.js",
  9.         "runtime": "node",
  11.         "languages": ["javascript", "typescript", "javascriptreact", "typescriptreact"],
  13.         "configurationAttributes": {
  14.           "launch": {
  15.             "required": ["program"],
  16.             "properties": {
  17.               "program": {
  18.                 "type": "string",
  19.                 "description": "The program to debug."
  20.               }
  21.             }
  22.           }
  23.         },
  25.         "initialConfigurations": [
  26.           {
  27.             "type": "node",
  28.             "request": "launch",
  29.             "name": "Launch Program",
  30.             "program": "${workspaceFolder}/app.js"
  31.           }
  32.         ],
  34.         "configurationSnippets": [
  35.           {
  36.             "label": "Node.js: Attach Configuration",
  37.             "description": "A new configuration for attaching to a running node program.",
  38.             "body": {
  39.               "type": "node",
  40.               "request": "attach",
  41.               "name": "${2:Attach to Port}",
  42.               "port": 9229
  43.             }
  44.           }
  45.         ],
  47.         "variables": {
  48.           "PickProcess": "extension.node-debug.pickNodeProcess"
  49.         }
  50.       }
  51.     ]
  52.   }
  53. }

For a full walkthrough on how to integrate a debugger, go to Debugger Extension.

contributes.breakpoints

Usually a debugger extension will also have a contributes.breakpoints entry where the extension lists the language file types for which setting breakpoints will be enabled.

  1. {
  2.   "contributes": {
  3.     "breakpoints": [
  4.       {
  5.         "language": "javascript"
  6.       },
  7.       {
  8.         "language": "javascriptreact"
  9.       }
  10.     ]
  11.   }
  12. }

contributes.grammars

Contribute a TextMate grammar to a language. You must provide the language this grammar applies to, the TextMate scopeName for the grammar and the file path.

Note: The file containing the grammar can be in JSON (filenames ending in .json) or in XML plist format (all other files).

grammar example

  1. {
  2.   "contributes": {
  3.     "grammars": [
  4.       {
  5.         "language": "markdown",
  6.         "scopeName": "text.html.markdown",
  7.         "path": "./syntaxes/markdown.tmLanguage.json",
  8.         "embeddedLanguages": {
  9.           "meta.embedded.block.frontmatter": "yaml"
  10.         }
  11.       }
  12.     ]
  13.   }
  14. }

See the Syntax Highlight Guide to learn more about how to register TextMate grammars associated with a language to receive syntax highlighting.

grammars extension point example

contributes.themes

Contribute a color theme to VS Code, defining workbench colors and styles for syntax tokens in the editor.

You must specify a label, whether the theme is a dark theme or a light theme (such that the rest of VS Code changes to match your theme) and the path to the file (JSON format).

theme example

  1. {
  2.   "contributes": {
  3.     "themes": [
  4.       {
  5.         "label": "Monokai",
  6.         "uiTheme": "vs-dark",
  7.         "path": "./themes/monokai-color-theme.json"
  8.       }
  9.     ]
  10.   }
  11. }

color theme extension point example

See the Color Theme Guide on how to create a Color Theme.

contributes.iconThemes

Contribute a file icon theme to VS Code. File icons are shown next to file names, indicating the file type.

You must specify an id (used in the settings), a label and the path to the file icon definition file.

file icon theme example

  1. {
  2.   "contributes": {
  3.     "iconThemes": [
  4.       {
  5.         "id": "metro",
  6.         "label": "Metro File Icons",
  7.         "path": "./fileicons/metro-file-icon-theme.json"
  8.       }
  9.     ]
  10.   }
  11. }

file icon theme extension point example

See the File Icon Theme Guide on how to create a File Icon Theme.

contributes.productIconThemes

Contribute a product icon theme to VS Code. Product icons are all icons used in VS Code except file icons and icons contributed from extensions.

You must specify an id (used in the settings), a label and the path to the icon definition file.

product icon theme example

  1. {
  2.   "contributes": {
  3.     "productIconThemes": [
  4.       {
  5.         "id": "elegant",
  6.         "label": "Elegant Icon Theme",
  7.         "path": "./producticons/elegant-product-icon-theme.json"
  8.       }
  9.     ]
  10.   }
  11. }

product icon theme extension point example

See the Product Icon Theme Guide on how to create a Product Icon Theme.

contributes.snippets

Contribute snippets for a specific language. The language attribute is the language identifier and the path is the relative path to the snippet file, which defines snippets in the VS Code snippet format.

The example below shows adding snippets for the Go language.

  1. {
  2.   "contributes": {
  3.     "snippets": [
  4.       {
  5.         "language": "go",
  6.         "path": "./snippets/go.json"
  7.       }
  8.     ]
  9.   }
  10. }

contributes.jsonValidation

Contribute a validation schema for a specific type of json file. The url value can be either a local path to a schema file included in the extension or a remote server URL such as a json schema store.

  1. {
  2.   "contributes": {
  3.     "jsonValidation": [
  4.       {
  5.         "fileMatch": ".jshintrc",
  6.         "url": "https://json.schemastore.org/jshintrc"
  7.       }
  8.     ]
  9.   }
  10. }

contributes.views

Contribute a view to VS Code. You must specify an identifier and name for the view. You can contribute to following view containers:

  • explorer: Explorer view container in the Activity Bar
  • scm: Source Control Management (SCM) view container in the Activity Bar
  • debug: Run and Debug view container in the Activity Bar
  • test: Test view container in the Activity Bar
  • Custom view containers contributed by Extensions.

When the user opens the view, VS Code will then emit an activationEvent onView:${viewId} (onView:nodeDependencies for the example below). You can also control the visibility of the view by providing the when context value. The icon specified will be used when the title cannot be shown (e.g. when the view is dragged to the Activity Bar). The contextualTitle is used when the view is moved out of its default view container and needs additional context.

  1. {
  2.   "contributes": {
  3.     "views": {
  4.       "explorer": [
  5.         {
  6.           "id": "nodeDependencies",
  7.           "name": "Node Dependencies",
  8.           "when": "workspaceHasPackageJSON",
  9.           "icon": "media/dep.svg",
  10.           "contextualTitle": "Package Explorer"
  11.         }
  12.       ]
  13.     }
  14.   }
  15. }

views extension point example

The content of a view can be populated in two ways:

contributes.viewsWelcome

Contribute welcome content to Custom views. Welcome content only applies to empty tree views. A view is considered empty if the tree has no children. By convention, any command links that are on a line by themselves are displayed as a button. You can specify the view that the welcome content should apply to with the view property. Visibility of the welcome content can be controlled with the when context value. The text to be displayed as the welcome content is set with the contents property.

  1. {
  2.   "contributes": {
  3.     "viewsWelcome": [
  4.       {
  5.         "view": "scm",
  6.         "contents": "In order to use git features, you can open a folder containing a git repository or clone from a URL.\n[Open Folder](command:vscode.openFolder)\n[Clone Repository](command:git.clone)\nTo learn more about how to use git and source control in VS Code [read our docs](https://aka.ms/vscode-scm).",
  7.         "when": "config.git.enabled && git.state == initialized && workbenchState == empty"
  8.       }
  9.     ]
  10.   }
  11. }

Welcome content example

Multiple welcome content items can be contributed to one view. When this happens, the content that come from VS Code core comes first, followed by content from built-in extensions, followed by content from all other extensions.

contributes.viewsContainers

Contribute a view container into which Custom views can be contributed. You must specify an identifier, title, and an icon for the view container. At present, you can contribute them to the Activity Bar (activitybar) and Panel (panel). Below example shows how the Package Explorer view container is contributed to the Activity Bar and how views are contributed to it.

  1. {
  2.   "contributes": {
  3.     "viewsContainers": {
  4.       "activitybar": [
  5.         {
  6.           "id": "package-explorer",
  7.           "title": "Package Explorer",
  8.           "icon": "resources/package-explorer.svg"
  9.         }
  10.       ]
  11.     },
  12.     "views": {
  13.       "package-explorer": [
  14.         {
  15.           "id": "package-dependencies",
  16.           "name": "Dependencies"
  17.         },
  18.         {
  19.           "id": "package-outline",
  20.           "name": "Outline"
  21.         }
  22.       ]
  23.     }
  24.   }
  25. }

Custom views container

Icon specifications

  • Size: Icons should be 24x24 and centered.

  • Color: Icons should use a single color.

  • Format: It is recommended that icons be in SVG, though any image file type is accepted.

  • States: All icons inherit the following state styles:

    StateOpacity
    Default60%
    Hover100%
    Active100%

contributes.problemMatchers

Contribute problem matcher patterns. These contributions work in both the output panel runner and in the terminal runner. Below is an example to contribute a problem matcher for the gcc compiler in an extension:

  1. {
  2.   "contributes": {
  3.     "problemMatchers": [
  4.       {
  5.         "name": "gcc",
  6.         "owner": "cpp",
  7.         "fileLocation": ["relative", "${workspaceFolder}"],
  8.         "pattern": {
  9.           "regexp": "^(.*):(\\d+):(\\d+):\\s+(warning|error):\\s+(.*)$",
  10.           "file": 1,
  11.           "line": 2,
  12.           "column": 3,
  13.           "severity": 4,
  14.           "message": 5
  15.         }
  16.       }
  17.     ]
  18.   }
  19. }

This problem matcher can now be used in a tasks.json file via a name reference $gcc. An example looks like this:

  1. {
  2.   "version": "2.0.0",
  3.   "tasks": [
  4.     {
  5.       "label": "build",
  6.       "command": "gcc",
  7.       "args": ["-Wall", "helloWorld.c", "-o", "helloWorld"],
  8.       "problemMatcher": "$gcc"
  9.     }
  10.   ]
  11. }

Also see: Defining a Problem Matcher

contributes.problemPatterns

Contributes named problem patterns that can be used in problem matchers (see above).

contributes.taskDefinitions

Contributes and defines an object literal structure that allows to uniquely identify a contributed task in the system. A task definition has at minimum a type property but it usually defines additional properties. For example a task definition for a task representing a script in a package.json file looks like this:

  1. {
  2.   "taskDefinitions": [
  3.     {
  4.       "type": "npm",
  5.       "required": ["script"],
  6.       "properties": {
  7.         "script": {
  8.           "type": "string",
  9.           "description": "The script to execute"
  10.         },
  11.         "path": {
  12.           "type": "string",
  13.           "description": "The path to the package.json file. If omitted the package.json in the root of the workspace folder is used."
  14.         }
  15.       }
  16.     }
  17.   ]
  18. }

The task definition is defined using JSON schema syntax for the required and properties property. The type property defines the task type. If the above example:

  • "type": "npm" associates the task definition with the npm tasks
  • "required": [ "script" ] defines that script attributes as mandatory. The path property is optional.
  • "properties" : { … }` defines the additional properties and their types.

When the extension actually creates a Task, it needs to pass a TaskDefinition that conforms to the task definition contributed in the package.json file. For the npm example a task creation for the test script inside a package.json file looks like this:

  1. let task = new vscode.Task({ type: 'npm', script: 'test' }, ....);

contributes.colors

Contributes new themable colors. These colors can be used by the extension in editor decorators and in the status bar. Once defined, users can customize the color in the workspace.colorCustomization setting and user themes can set the color value.

  1. {
  2.   "contributes": {
  3.     "colors": [
  4.       {
  5.         "id": "superstatus.error",
  6.         "description": "Color for error message in the status bar.",
  7.         "defaults": {
  8.           "dark": "errorForeground",
  9.           "light": "errorForeground",
  10.           "highContrast": "#010203"
  11.         }
  12.       }
  13.     ]
  14.   }
  15. }

Color default values can be defined for light, dark and high contrast theme and can either be a reference to an existing color or a Color Hex Value.

Extensions can consume new and existing theme colors with the ThemeColor API:

  1. const errorColor = new vscode.ThemeColor('superstatus.error');

contributes.typescriptServerPlugins

Contributes TypeScript server plugins that augment VS Code’s JavaScript and TypeScript support:

  1. {
  2.   "contributes": {
  3.     "typescriptServerPlugins": [
  4.       {
  5.         "name": "typescript-styled-plugin"
  6.       }
  7.     ]
  8.   }
  9. }

The above example extension contributes the typescript-styled-plugin which adds styled-component IntelliSense for JavaScript and TypeScript. This plugin will be loaded from the extension and must be installed as a normal NPM dependency in the extension:

  1. {
  2.   "dependencies": {
  3.     "typescript-styled-plugin": "*"
  4.   }
  5. }

TypeScript server plugins are loaded for all JavaScript and TypeScript files when the user is using VS Code’s version of TypeScript. They are not activated if the user is using a workspace version of TypeScript, unless the plugin explicitly sets "enableForWorkspaceTypeScriptVersions": true.

  1. {
  2.   "contributes": {
  3.     "typescriptServerPlugins": [
  4.       {
  5.         "name": "typescript-styled-plugin",
  6.         "enableForWorkspaceTypeScriptVersions": true
  7.       }
  8.     ]
  9.   }
  10. }

contributes.resourceLabelFormatters

Contributes resource label formatters that specify how to display URIs everywhere in the workbench. For example here’s how an extension could contribute a formatter for URIs with scheme remotehub:

  1. {
  2.   "contributes": {
  3.     "resourceLabelFormatters": [
  4.       {
  5.         "scheme": "remotehub",
  6.         "formatting": {
  7.           "label": "${path}",
  8.           "separator": "/",
  9.           "workspaceSuffix": "GitHub"
  10.         }
  11.       }
  12.     ]
  13.   }
  14. }

This means that all URIs that have a scheme remotehub will get rendered by showing only the path segment of the URI and the separator will be /. Workspaces which have the remotehub URI will have the GitHub suffix in their label.

Plugin configuration

Extensions can send configuration data to contributed TypeScript plugins through an API provided by VS Code’s built-in TypeScript extension:

  1. // In your VS Code extension
  3. export async function activate(context: vscode.ExtensionContext) {
  4.   // Get the TS extension
  5.   const tsExtension = vscode.extensions.getExtension('vscode.typescript-language-features');
  6.   if (!tsExtension) {
  7.     return;
  8.   }
  10.   await tsExtension.activate();
  12.   // Get the API from the TS extension
  13.   if (!tsExtension.exports || !tsExtension.exports.getAPI) {
  14.     return;
  15.   }
  17.   const api = tsExtension.exports.getAPI(0);
  18.   if (!api) {
  19.     return;
  20.   }
  22.   // Configure the 'my-typescript-plugin-id' plugin
  23.   api.configurePlugin('my-typescript-plugin-id', {
  24.     someValue: process.env['SOME_VALUE']
  25.   });
  26. }

The TypeScript server plugin receives the configuration data through an onConfigurationChanged method:

  1. // In your TypeScript plugin
  3. import * as ts_module from 'typescript/lib/tsserverlibrary';
  5. export = function init({ typescript }: { typescript: typeof ts_module }) {
  6.   return {
  7.     create(info: ts.server.PluginCreateInfo) {
  8.       // Create new language service
  9.     },
  10.     onConfigurationChanged(config: any) {
  11.       // Receive configuration changes sent from VS Code
  12.     }
  13.   };
  14. };

This API allows VS Code extensions to synchronize VS Code settings with a TypeScript server plugin, or dynamically change the behavior of a plugin. Take a look at the TypeScript TSLint plugin and lit-html extensions to see how this API is used in practice.