Publishing Extensions

Once you have made a high-quality extension, you can publish it to the VS Code Extension Marketplace so others can find, download, and use your extension. Alternatively, you can package an extension into the installable VSIX format and share it with other users.

This topics covers:

• Using vsce, the CLI tool for managing VS Code extensions
• Packaging, publishing and unpublishing extensions
• Registering a publisherId necessary for publishing extensions

vsce

vsce, short for “Visual Studio Code Extensions”, is a command-line tool for packaging, publishing and managing VS Code extensions.

Installation

Make sure you have Node.js installed. Then run:

npm install -g vsce

Usage

You can use vsce to easily package and publish your extensions:

$ cd myExtension
$ vsce package
# myExtension.vsix generated
$ vsce publish
# <publisherID>.myExtension published to VS Code MarketPlace

vsce can also search, retrieve metadata, and unpublish extensions. For a reference on all the available vsce commands, run vsce --help.

Publishing extensions

Note: Due to security concerns, vsce will not publish extensions which contain user-provided SVG images.

The publishing tool checks the following constraints:

• The icon provided in package.json may not be an SVG.
• The badges provided in the package.json may not be SVGs unless they are from trusted badge providers.
• Image URLs in README.md and CHANGELOG.md need to resolve to https URLs.
• Images in README.md and CHANGELOG.md may not be SVGs unless they are from trusted badge providers.

Visual Studio Code leverages Azure DevOps for its Marketplace services. This means that authentication, hosting, and management of extensions are provided through Azure DevOps.

vsce can only publish extensions using Personal Access Tokens. You need to create at least one in order to publish an extension.

Get a Personal Access Token

First, make sure you have an Azure DevOps organization.

In the following examples, the organization’s name is vscode. From your organization’s home page (for example: https://dev.azure.com/vscode), open the User settings dropdown menu next to your profile image and select Personal access tokens:

On the Personal Access Tokens page, click New Token to create a new Personal Access Token:

Give the Personal Access Token a name, optionally extend its expiration date to one year, make it accessible to every organization, select a custom defined scope ruleset and click Show all scopes:

Finally, scroll down the list of possible scopes until you find Marketplace and select Manage:

Select Create and you’ll be presented with your newly created Personal Access Token. Copy it, you’ll need it to create a publisher.

Create a publisher

A publisher is an identity who can publish extensions to the Visual Studio Code Marketplace. Every extension needs to include a publisher name in its package.json file.

Once you have a Personal Access Token, you can create a new publisher using vsce:

vsce create-publisher (publisher name)

vsce will remember the provided Personal Access Token for future references to this publisher.

Note: Alternatively, create your publisher in the Marketplace publisher management page and log in through vsce, as described in the next section.

Log in to a publisher

If you already created a publisher before and want to use it with vsce:

vsce login (publisher name)

Similarly to the create-publisher command, vsce will ask you for the Personal Access Token and remember it for future commands.

You can also enter your Personal Access Token as you publish with an optional parameter -p <token>.

vsce publish -p <token>

Review extension installs and ratings

You can see how your extension is doing on the Marketplace by going to the Manage Publishers & Extensions page at https://marketplace.visualstudio.com/manage/publishers/{publisher ID}, providing your publisher ID in the URL. Here you’ll see all extensions published under your publisher ID and can select an extension to see the Acquisition Trend over time, as well as Total Acquisition counts and Ratings & Reviews.

Auto-incrementing the extension version

You can auto-increment an extension’s version number when you publish by specifying the SemVer compatible number to increment: major, minor, or patch.

For example, if you want to update an extension’s version from 1.0.0 to 1.1.0, you would specify minor:

vsce publish minor

This will modify the extension’s package.json version attribute before publishing the extension.

You can also specify a complete SemVer compatible version on the command line:

vsce publish 2.0.1

Note: If vsce publish is run in a git repo, it will also create a version commit and tag via npm-version. The default commit message will be extension’s version, but you can supply a custom commit message using the -m flag. (The current version can be referenced from the commit message with %s.)

Unpublishing extensions

You can unpublish an extension with the vsce tool by specifying the extension ID publisher.extension.

vsce unpublish (publisher name).(extension name)

Note: When you unpublish an extension, the Marketplace will remove any extension statistics it has collected. You may want to update your extension rather than unpublish it.

Packaging extensions

If you want to test an extension on your local install of VS Code or distribute an extension without publishing it to VS Code MarketPlace, you can choose to package your extension. vsce can package your extension into a VSIX file, from which users can easily install. Some extensions publish VSIX files to each GitHub release.

For extension authors, they can run vsce package in extension root folder to create such VSIX files.

For users who receive such a VSIX file, they can install the extension with code --install-extension my-extension-0.0.1.vsix.

Sharing privately with others

If you want to share your extension with others privately, you can send them your packaged extension .vsix file.

Your extension folder

To load an extension, you need to copy the files to your VS Code extensions folder .vscode/extensions. Depending on your platform, it is located in the following folders:

• Windows %USERPROFILE%\.vscode\extensions
• macOS ~/.vscode/extensions
• Linux ~/.vscode/extensions

Visual Studio Code compatibility

When authoring an extension, you will need to describe what is the extension’s compatibility to Visual Studio Code itself. This can be done via the engines.vscode field inside package.json:

{
  "engines": {
    "vscode": "^1.8.0"
  }
}

A value of 1.8.0 means that your extension is compatible only with VS Code 1.8.0. A value of ^1.8.0 means that your extension is compatible with VS Code 1.8.0 and onwards, including 1.8.1, 1.9.0, etc.

You can use the engines.vscode field to make sure the extension only gets installed for clients that contain the API you depend on. This mechanism plays well with the Stable release as well as the Insiders one.

For example, imagine that the latest Stable version of VS Code is 1.8.0 and that during 1.9.0‘s development a new API is introduced and thus made available in the Insider release through version 1.9.0-insider. If you want to publish an extension version that benefits from this API, you should indicate a version dependency of ^1.9.0. Your new extension version will be installed only on VS Code >=1.9.0, which means all current Insider customers will get it, while the Stable ones will only get the update when Stable reaches 1.9.0.

Advanced usage

Marketplace integration

You can customize how your extension looks in the Visual Studio Marketplace. See the Go extension for an example.

Here are some tips for making your extension look great on the Marketplace:

• A README.md file at the root of your extension will be used to populate the extension’s Marketplace page’s contents. vsce will modify README links for you in two different ways:
  • If you add a repository field to your package.json and it is a public GitHub repository, vsce will automatically detect it and adjust relative links accordingly, using the master branch by default. You can override the GitHub branch with the --githubBranch flag when running vsce package or vsce publish.
  • For more fine-grained control, you can set the --baseContentUrl and --baseImagesUrl flags to set the base URLs for relative links.
• A LICENSE file at the root of your extension will be used as the contents for the extension’s license.
• A CHANGELOG.md file at the root of your extension will be used as the contents for the extension’s change log.
• You can set the banner background color by setting galleryBanner.color to the intended hex value in package.json.
• You can set an icon by setting icon to a relative path to a squared 128px PNG file included in your extension, in package.json.

Also see Marketplace Presentation Tips.

.vscodeignore

You can create a .vscodeignore file to exclude some files from being included in your extension’s package. This file is a collection of glob patterns, one per line.

For example:

**/*.ts
**/tsconfig.json
!file.ts

You should ignore all files not needed at runtime. For example, if your extension is written in TypeScript, you should ignore all **/*.ts files, like in the previous example.

Note: Development dependencies listed in devDependencies will be automatically ignored, you don’t need to add them to the .vscodeignore file.

Pre-publish step

It’s possible to add a pre-publish step to your manifest file. The command will be called every time the extension is packaged.

{
  "name": "uuid",
  "version": "0.0.1",
  "publisher": "someone",
  "engines": {
    "vscode": "0.10.x"
  },
  "scripts": {
    "vscode:prepublish": "tsc"
  }
}

This will always invoke the TypeScript compiler whenever the extension is packaged.

Next steps

• Extension Marketplace - Learn more about VS Code’s public extension Marketplace.
• Testing Extensions - Add tests to your extension project to ensure high quality.
• Bundling Extensions - Improve load times by bundling your extension files with webpack.

Common questions

I get 403 Forbidden (or 401 Unauthorized) error when I try to publish my extension?

One easy mistake to make when creating the PAT (Personal Access Token) is to not select All accessible organizations in the Organizations field drop-down (instead selecting a specific organization). You should also set the Authorized Scopes to Marketplace (Manage) for the publish to work.

I can’t unpublish my extension through the vsce tool?

You may have changed your extension ID or publisher name. You can also manage your extensions directly on the Marketplace by going to the manage page. You can update or unpublish your extension from your publisher manage page.

Why does vsce not preserve file attributes?

Please note that when building and publishing your extension from Windows, all the files included in the extension package will lack POSIX file attributes, namely the executable bit. Some node_modules dependencies rely on those attributes to properly function. Publishing from Linux and macOS works as expected.

Can I publish from a continuous integration (CI) build?

Yes, see the Automated publishing section of the Continuous Integration topic to learn how to configure Azure DevOps, GitHub Actions, and Travis CI to automatically publish your extension to the Marketplace.