Publishing Your Visual Studio Code Theme Extension

Developing a custom theme for Visual Studio Code is an enjoyable process. Once completed, the next crucial step involves publishing the theme, allowing both its creator and other users to benefit from it.

While publishing a VS Code extension might seem straightforward, it often presents more challenges than anticipated, especially when compared to the simplicity of publishing npm packages.

To ensure broad availability, a theme typically needs to be published in two main locations:

1. Visual Studio Marketplace, primarily for VS Code users.
2. Open VSX, which caters to other compatible text editors.

Additionally, publishing to npm can facilitate the theme’s use in other contexts, such as for syntax highlighting with tools like Shiki.

Preparing Your Theme

When naming a theme, avoid using a scoped format (e.g., @scope/theme-name), as this will prevent publication to Open VSX.

Therefore, ensure the theme name is unscoped. The word “theme” itself is optional:

{
  "name": "twilight-cosmos-theme",
}

To incorporate an icon for the theme, a 128px square image file is required, which must be accessible within the project. Specify this file using the icon property:

{
  "icon": "path/to/icon.png",
}

Next, confirm that a contributes key is present in the package.json file. This key is essential as VS Code and other text editors use it to discover themes.

{
  "contributes": {
    "themes": [
      {
        "label": "<Theme Name>",
        "uiTheme": "vs-dark",
        "path": "./<path-to-theme>.json"
      }
    ]
  },
}

Finally, include several keywords to enhance the theme’s searchability on both the Visual Studio Marketplace and Open VSX.

If difficulties arise in generating keywords, consider using an AI tool by providing it with the theme file and requesting keyword suggestions.

{
  "keywords": [
    "theme",
    "dark theme",
    "twilight",
    "cosmos",
    "color-theme",
    "dark",
    "purple",
    "blue",
    "vscode-theme"
  ],
}

Publishing to Visual Studio Marketplace

Microsoft enables publishing to the Visual Studio Marketplace using vsce, provided a personal access token from an Azure DevOps account is available.

During the creation of this article, issues were encountered when setting up an Azure DevOps account, necessitating the use of the manual publishing method for the extension.

Both publishing methods will be discussed.

Prior to publishing, a Visual Studio Marketplace account is required. Users without an account should sign up.

Then, proceed with the following steps:

• Click on Publish Extension.
• Create a publisher account.

This step is essential for both vsce-based and manual publishing.

Publishing via VSCE

To use this method, an Azure DevOps account is necessary. Once available, a Personal Access Token can be generated by following these steps.

Note: Azure DevOps does not offer lifetime access tokens; the maximum expiry period is approximately one year.

It is worth noting that issues can arise during Azure DevOps account creation, such as backend unresponsiveness or difficulty locating the correct pages. If this occurs, it may be necessary to wait 1-2 days before attempting again, as the process typically resolves itself.

With the personal access token obtained, the remaining steps are generally straightforward.

First, log in to VSCE using the publisher ID established in the Visual Studio Marketplace (ensure the publisher ID, not the user ID, is entered).

npx vsce login <publisher_id>

The access token will need to be provided when prompted. Subsequently, execute the following command to publish to the marketplace:

npx vsce publish

The publishing process is then complete.

Publishing Manually

This manual method is an alternative if issues arise with the personal access token. It is also quite straightforward. Navigate to the Visual Studio Marketplace and perform the following actions:

• Click on Publish Extensions.
• Click New Extension.
• Utilize the vsce package command to bundle the extension into a .vsix file.
• Drag and drop the packaged .vsix file to upload the extension.

This completes the manual publishing process.

Getting Verified on Visual Studio Code

For new extensions, verification on the Visual Studio Marketplace is only possible after the extension has been active for at least six months. To pursue verification, users should set a reminder for six months and then visit this page for detailed instructions.

Publishing to Open VSX

Visual Studio Code primarily utilizes the Visual Studio Marketplace, while other text editors, such as Cursor, often rely on Open VSX for extensions.

The process for publishing to Open VSX involves several steps:

• Log in to Open VSX using GitHub.
• Create an Eclipse Foundation account.
• Link the GitHub repository to the Eclipse Foundation account.
• Sign their agreement.
• Create a publisher namespace and include it as the publisher in the package.json file.
• Generate an access token.
• Finally, run `npx ovsx publish` to publish the package.

Similarly, ovsx will request a personal access token during the initial publishing attempt. Fortunately, ovsx appears to support lifetime access tokens, eliminating concerns about expiration.

Claiming the Publisher Namespace

This process, referred to by Open VSX as “claiming” the publisher namespace, is equivalent to achieving verification. While it may involve some back-and-forth communication, it can be completed immediately, unlike the six-month waiting period for Visual Studio Marketplace verification.

After creating a publisher namespace, a prominent warning sign will appear:

To claim the publisher namespace, it is necessary to create a GitHub issue with the Eclipse Foundation, explicitly stating the intent to claim the namespace.

Within that issue, include the following:

• The GitHub repository URL (if it is publicly available).
• An offer to provide temporary access to the GitHub repository (if it is private).

A team member will then manage the remainder of the process.

The Eclipse Foundation team is generally responsive, so communication issues are unlikely.

Including Images for Your Theme

Including images in the Readme.md file is beneficial for showcasing the theme. This allows potential users to preview the theme’s color scheme and overall appearance before downloading it.

However, both the Visual Studio Marketplace and Open VSX do not support relative URLs for images; using them will result in broken links. Therefore, it is necessary to link to an absolute URL.

The GitHub repository is an ideal location for image hosting, provided it is publicly accessible.

An example URL format is as follows:

![Alt Text](https://raw.githubusercontent.com/<github_username>/<repo-name>/master/<path-to-image>)

Wrapping Up

Publishing a first VS Code editor theme can be a tedious process. However, this should not deter creators from sharing their themes for their own and others’ enjoyment.

For those interested, the author’s first theme is named Twilight Cosmos. Further details on its creation process are available in a previous article.

Embrace the process, even if it presents some frustrations; completion often comes sooner than expected.