How to publish a VS Code theme?

To publish a VS Code theme, you'll use the vsce publishing tool to package your theme and then upload it to the Visual Studio Code Marketplace. This process involves preparing your theme's package.json file, obtaining a publisher ID and a Personal Access Token (PAT), and using vsce commands to package and publish your extension.

How to Publish a VS Code Theme?

Publishing a VS Code theme makes it available to millions of users directly through the VS Code Extensions view. The vsce (Visual Studio Code Extensions) command-line tool is your primary utility for this task, handling the packaging and publishing process.

Prerequisites for Publishing Your Theme

Before you begin, ensure you have the following set up:

Node.js and npm: Required to install and run vsce. Download from nodejs.org.
Git: Essential for version control and required by vsce for versioning.
Azure DevOps Organization: You'll need an Azure DevOps organization to register a publisher ID. If you don't have one, you can create a free one at azure.microsoft.com/en-us/services/devops.
Personal Access Token (PAT): A PAT from your Azure DevOps organization is needed for vsce to authenticate and publish your theme.

Step-by-Step Guide to Publishing Your VS Code Theme

Follow these steps to get your theme live on the Marketplace:

1. Install the `vsce` Publishing Tool

Open your terminal or command prompt and install vsce globally using npm:

npm install -g vsce

2. Prepare Your Theme's `package.json`

Your package.json file is crucial for the Marketplace listing. Ensure it contains the following key fields:

name: A unique, lowercase identifier for your theme.
displayName: The human-readable name of your theme that appears in the Marketplace.
description: A concise explanation of your theme. Tip: To make it easy for users to find your theme, include the word "theme" in the extension description.
publisher: Your unique publisher ID (created in the next step). This must exactly match the publisher ID you register.
version: The current version of your theme (e.g., "1.0.0").
engines.vscode: The minimum VS Code version your theme is compatible with (e.g., "^1.60.0").

categories: Specify "Themes" to correctly categorize your theme in the Marketplace.

{
  "name": "my-awesome-theme",
  "displayName": "My Awesome Theme",
  "description": "A dark theme for VS Code, designed for awesome developers. Includes a 'theme' for code clarity.",
  "version": "1.0.0",
  "publisher": "YourPublisherID",
  "engines": {
    "vscode": "^1.60.0"
  },
  "categories": [
    "Themes"
  ],
  "contributes": {
    "themes": [
      {
        "label": "My Awesome Theme",
        "uiTheme": "vs-dark",
        "path": "./themes/My Awesome Theme-color-theme.json"
      }
    ]
  },
  "icon": "icon.png",
  "repository": {
    "type": "git",
    "url": "https://github.com/yourusername/my-awesome-theme.git"
  },
  "bugs": {
    "url": "https://github.com/yourusername/my-awesome-theme/issues"
  },
  "homepage": "https://github.com/yourusername/my-awesome-theme#readme"
}

Ensure your contributes.themes section correctly points to your theme's JSON file. Consider adding an icon.png (128x128 pixels) for better visibility.

3. Obtain a Publisher ID and Personal Access Token (PAT)

Create a Publisher:
- Go to the VS Code Marketplace Publisher management page.
- Sign in with the Microsoft account linked to your Azure DevOps organization.
- Click "Create new publisher" and follow the prompts to create your unique publisher ID. Remember this ID, as it must match the publisher field in your package.json.
Generate a Personal Access Token (PAT):
- Navigate to your Azure DevOps organization (e.g., https://dev.azure.com/<yourorganization>).
- Go to User settings (usually a gear icon) > Personal access tokens.
- Click "New Token".
- Give it a descriptive name (e.g., "VS Code Theme Publisher").
- Set its scope to "Marketplace (Publish)". This is crucial for vsce to have the necessary permissions.
- Set an expiration date.
- Click "Create".
- Copy the generated PAT immediately. You will not be able to see it again.

4. Log In with `vsce`

In your terminal, navigate to your theme's root directory and log in using vsce:

vsce login <your-publisher-id>

When prompted, paste the Personal Access Token you copied.

5. Package Your Theme

Before publishing, it's good practice to package your theme into a .vsix file to test it locally. This command creates the installable package:

vsce package

This will generate a file like my-awesome-theme-1.0.0.vsix in your project directory. You can install this locally in VS Code via "Install from VSIX..." in the Extensions view menu (...).

6. Publish Your Theme to the Marketplace

Once you're satisfied, publish your theme using the vsce publish command:

vsce publish

If it's your first time publishing, vsce will create a new entry in the Marketplace. For subsequent updates, it will increment the version number in package.json and push the new version.

Key Considerations for Discoverability

description Field: As mentioned, including the word "theme" in your description helps users find your creation.
categories Field: Setting categories to ["Themes"] in your package.json ensures your theme appears under the correct filter in the Marketplace.
Metadata: Provide a comprehensive README.md with screenshots, an icon.png, and links to a repository or issues page. These elements significantly improve your theme's appeal and inform users.
Keywords: While not a direct field, ensure relevant keywords are present in your displayName and description to optimize search results.

Publishing Checklist

Feature	Requirement
`vsce` Tool	Installed globally (`npm install -g vsce`)
`package.json`	`displayName`, `name`, `description` (with "theme"), `publisher`, `version`, `engines.vscode`, `categories: ["Themes"]`, `contributes.themes` correctly defined
Publisher ID	Created on the VS Code Marketplace management page and matching `package.json`
PAT	Generated from Azure DevOps with "Marketplace (Publish)" scope, copied, and used for `vsce login`
Theme Files	Color theme JSON file correctly referenced in `contributes`
Git Repository	Initialized and committed (required by `vsce`)
README.md	Informative and well-formatted with screenshots
Icon (Optional)	`icon.png` (128x128px) specified in `package.json` for visual appeal

By following these steps, your custom VS Code theme will soon be discoverable and installable by the global developer community.

How to publish a VS Code theme?