VS Code extension: package.json

package.json is an extension's manifest file. This file is located in the root of the extension's directory structure.

Apparently, package.json is a concept of Yarn where it is used to describe a package.

The four required fields in package.json are

name

All lowercase. Compare with displayName.

version

In Semantic versioning format (maj.min.pch).

publisher

which identifies the identity that is allowed to publish an extension to the Visual Studio Code Marketplace.

engines

Thus, a minimal package.json could be:

{ "name" : "basic-extension" , "version" : "0.0.1" , "publisher" : "tq84" , "engines" :{"vscode": "^1.32.0" }, … }

Other important or interesting fields are

main

The extension's main module, i. e. the name of a JavaScript file, relative to the extension's root. This module must expose the function activate() (which is called when the first event listed in activationEvents is triggerd). The .js suffix can be omitted (in fact, it even seems to be recommended because it is assumed to be a JavaScript file anyway). browser is the same, but for VS Code running in the browser.

activationEvents

List of activation events. The special event * is fired when VS Code is started. When one of the given activation events are triggered, the extension is activated, i. e. the activate() function in the extension's main module is called. activate() is not called multiple times.

contributes

Description of the functionality that is provided («contributed…) by the extension.

engines.vscode

The minimum VS Code API version that the extension requires

dependencies

repository

license

For example "MIT". It's possible to refer to a license file in the root of the extension ("See license in LICENSE")

categories

A list of strings. Permitted values are: Programming Languages, Snippets, Linters, Themes, Debuggers, Formatters, Keymaps, SCM Providers, Other, Extension Packs, Language Packs, Data Science, Machine Learning, Visualization, Notebooks, Education and Testing. Compare with keywords.

displayName

Extension's name in the market place. Compare with name and description.

keywords

A list of up to 5 keywords, used to find the extension on the Marketplace. Campare with cateogries.

publisher dot name (tq84.demo-extension) is the extension's unique ID, used by VS Code to identify the extension.

package.json must be stored as a «pure» JSON file: comments are (as per strict JSON specification) not allowed.

activationEvents

activationEvents is an array whose elements define when an extension is activated.

Possible values for the elements of activationEvents include

`*`	VS Code starts up
`onStartupFinished`	After VS Code is started up. Similar to `*`, but with the intension not to slow down the starting up process.
`onLanguage:xyz`	a file whose language ID is `xyz` is opened
`onCommand:…`
`workspaceContains:*/pattern.`	A folder is opened that contains a file whose name matches the given pattern.
`onDebug`	before a debug session is started
`onDebugInitialConfigurations`	activation is just before the `provideDebugConfigurations` method of the `DebugConfigurationProvider` is called.
`onDebugResolve:type`	activation is just before the `resolveDebugConfiguration` method of the `DebugConfigurationProvider` is called.
`onFileSystem:scheme`	A file with the given scheme (`sftp`, `ftp`, `ssh` …) is opened
`onView:viewID`	A view with the given ID is opened
`onUri`
`onWebviewPanel`

contributes

`configuration`	Specification of extension settings that the user can modify.
`configurationDefaults`	Overwrite default editor configurations
`commands`	add a titled command (and optionally an icon, category and enabled state). Such commands show up in the Command Palette (`ctrl+shift+p`) and possibly in other menus, too.
`menus`
`submenus`
`keybindings`	Assigns a command to combination of keys being pressed (shortcut key)
`languages`	Defines a «new» language (id?)
`debuggers`
`breakpoints`
`grammars`	A TextMate grammar
`themes`	Color theme
`icons`
`iconThemes`	File icon themes, which are shown next to file names
`productIconThemes`
`snippets`
`jsonValidation`
`views`
`viewsWelcome`
`viewsContainers`
`walkthroughs`	intended to introduce an extension to a user
`problemMatchers`
`problemPatterns`
`taskDefinitions`
`colors`
`typescriptServerPlugins`
`resourceLabelFormatters`
`customEditors`
`contributes.con`
`terminal`
`semanticTokenModifiers`
`semanticTokenScopes`
`semanticTokenTypes`

Links

The extension manifest reference has a list of allowed field-names in package.json.