VS Code Extensions Manager

The @vscode/vsce tool is the Visual Studio Code Extension Manager used for packaging and publishing VS Code extensions. It is primarily used as a command-line tool via npx or as a library.

Requirements

• Node.js: version 22.x.x or higher.
• Package Managers: Supports npm >=6 and yarn >=1 <2.

Basic Usage

You can verify the installation by checking the version:

npx @vscode/vsce --version

You can publish extensions from GitHub Actions without storing a Personal Access Token (PAT) by using OpenID Connect (OIDC). This method exchanges a GitHub Actions token for a short-lived Marketplace credential.

Prerequisites

1. Configure a trusted publishing policy for your repository and workflow on the Visual Studio Marketplace.
2. Grant the workflow id-token: write permissions.

GitHub Actions Workflow Example

Use the --oidc flag in your publish command:

jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci
      - run: npx @vscode/vsce publish --oidc

Note: OIDC publishing does not fall back to a PAT if token acquisition or exchange fails.

The vsce command-line tool is used to package, publish, and manage VS Code extensions. It provides commands for lifecycle management, including listing files, packaging extensions into .vsix files, publishing to the Marketplace, and managing publisher credentials.

Common workflows include:

• Packaging: Creating a .vsix file from your extension source.
• Publishing: Uploading your extension to the Marketplace.
• Discovery: Searching the extension gallery or viewing extension metadata.
• Publisher Management: Logging in/out of publishers and managing Personal Access Tokens (PATs).

The ExtensionKind type determines the execution context of your extension. This is crucial for optimizing performance and ensuring compatibility with VS Code Web and Remote environments.

Supported values:

• 'ui': The extension runs in the UI thread (standard).
• 'workspace': The extension runs in the workspace/extension host process.
• 'web': The extension is compatible with VS Code for the Web.

You can provide a single value or an array of values via the extensionKind key in the manifest.

Authentication for publishing to the Marketplace is handled via the getPAT function, which resolves a Personal Access Token (PAT) using one of three methods in this priority order:

1. OpenID Connect (OIDC): If oidc: true is passed, it attempts to acquire a short-lived credential via OIDC.
2. Explicit PAT: If pat is provided in the options, it uses that string.
3. Azure Credentials: If azureCredential: true is passed, it uses Azure identity to acquire a token.
4. Stored PAT: If none of the above are provided, it retrieves the PAT associated with the publisher from the local store.

Constraints:

• You cannot use oidc and pat together.
• You cannot use oidc and azureCredential together.

You can customize the behavior of vsce using CLI flags or by defining a vsce configuration object in your package.json to avoid repetitive typing.

Using CLI Flags

Pass flags directly to the command:

npx @vscode/vsce publish --baseImagesUrl https://my.custom/base/images/url

Using package.json

Add a vsce key to your package.json to persist settings:

{
  "vsce": {
    "baseImagesUrl": "https://my.custom/base/images/url",
    "dependencies": true,
    "yarn": false
  }
}

The vsce tool manages Personal Access Tokens (PATs) for publishers to allow authenticated actions like publishing extensions.

• loginPublisher(publisherName): Prompts for a PAT for the specified publisher and saves it to the credential store. If the publisher is already known, it will ask for permission to overwrite the existing PAT.
• logoutPublisher(publisherName): Removes the stored PAT for the specified publisher from the credential store.
• listPublishers(): Displays a list of all publisher names currently stored in the credential manager.
• deletePublisher(publisherName): A destructive operation that deletes the publisher from the Marketplace (via the Gallery API) and then removes their credentials from the local store. This requires manual confirmation.

On Linux, @vscode/vsce uses keytar (which relies on libsecret) to save credentials safely. If libsecret is not installed, publishing may fail.

Install libsecret dependencies

Depending on your distribution, run the appropriate command:

• Debian/Ubuntu: sudo apt-get install libsecret-1-dev
• Alpine: apk add libsecret
• Red Hat-based: sudo yum install libsecret-devel
• Arch Linux: sudo pacman -S libsecret

Bypassing keytar

If you cannot install libsecret, you can avoid using keytar by:

1. Setting the VSCE_STORE=file environment variable to use a file-based credential store.
2. Using the VSCE_PAT environment variable to provide a Personal Access Token directly.

By default, vsce attempts to use a system credential manager (via keytar). If this fails, it falls back to a local file store.

You can force vsce to use the file-based store by setting the VSCE_STORE environment variable to file.

File Store Location: If using the file store, the credentials are saved in a JSON file at ~/.vsce (on Linux/macOS) or the equivalent home directory path.

The verifySignature function verifies the integrity of a VSIX package by checking its signature against the manifest and signature files.

await verifySignature(
  './extension-1.0.0.vsix',
  './extension-1.0.0.signature.manifest',
  './extension-1.0.0.signature.p7s'
);