Complete Guide: Publishing VS Code Extensions to Both Marketplaces

This content originally appeared on DEV Community and was authored by yao tang

Introduction

Publishing a VS Code extension involves more than just writing code. This guide covers the complete process of publishing to both the official Visual Studio Marketplace and the open-source Open VSX Registry.

Table of Contents

• Prerequisites
• Preparing Your Extension
• Publishing to Visual Studio Marketplace
• Publishing to Open VSX Registry
• Automating with CI/CD
• Best Practices

Prerequisites

Required Tools

# Install vsce (Visual Studio Code Extensions CLI)
npm install -g @vscode/vsce

# Install ovsx (Open VSX CLI)
npm install -g ovsx

Required Accounts

1. Microsoft Account – for VS Code Marketplace
2. Azure DevOps Account – for Personal Access Token
3. Eclipse Foundation Account – for Open VSX
4. GitHub Account – linked to Eclipse Foundation

Preparing Your Extension

1. Project Structure

Ensure your extension has the proper structure:

my-extension/
├── src/
│   └── extension.ts
├── package.json
├── README.md
├── CHANGELOG.md
├── LICENSE
├── .vscodeignore
└── icon.png (128x128 recommended)

2. Essential package.json Fields

{
  "name": "my-extension",
  "displayName": "My Awesome Extension",
  "description": "A brief description of what your extension does",
  "version": "0.0.1",
  "publisher": "your-publisher-name",
  "author": "Your Name",
  "license": "MIT",
  "icon": "icon.png",
  "repository": {
    "type": "git",
    "url": "https://github.com/username/repo"
  },
  "engines": {
    "vscode": "^1.80.0"
  },
  "categories": [
    "Other"
  ],
  "keywords": [
    "keyword1",
    "keyword2"
  ]
}

3. Create a .vscodeignore File

.vscode/**
.git/**
.gitignore
node_modules/**
src/**
.eslintrc.json
tsconfig.json
**/*.map
**/*.ts
!dist/**

4. Write Quality Documentation

README.md should include:

• What the extension does
• Features with screenshots/GIFs
• Installation instructions
• Usage examples
• Configuration options
• Known issues
• Contribution guidelines

CHANGELOG.md format:

# Change Log

## [0.0.1] - 2025-01-15
### Added
- Initial release
- Feature X
- Feature Y

Publishing to Visual Studio Marketplace

Step 1: Create Azure DevOps Organization

1. Go to https://dev.azure.com/
2. Sign in with your Microsoft account
3. Create a new organization (if you don’t have one)

Step 2: Generate Personal Access Token (PAT)

1. Click on your profile icon → User settings → Personal access tokens
2. Click New Token
3. Configure:
   • Name: VS Code Extension Publishing
   • Organization: Select your organization
   • Expiration: Custom (set to 1 year or more)
   • Scopes: Custom defined → Check Marketplace → Manage
4. Click Create and copy the token immediately (you won’t see it again!)

Step 3: Create Publisher

# Create publisher (first time only)
vsce create-publisher your-publisher-name

Or create manually at: https://marketplace.visualstudio.com/manage

Step 4: Login with vsce

vsce login your-publisher-name
# Enter your Personal Access Token when prompted

Step 5: Package and Publish

# Test packaging first
vsce package

# This creates a .vsix file you can test locally
# Install it in VS Code: Extensions → ... → Install from VSIX

# Publish to marketplace
vsce publish

# Or publish with version bump
vsce publish patch  # 0.0.1 → 0.0.2
vsce publish minor  # 0.0.1 → 0.1.0
vsce publish major  # 0.0.1 → 1.0.0

Step 6: Verify Publication

1. Go to https://marketplace.visualstudio.com/
2. Search for your extension
3. Check that all information displays correctly

Publishing to Open VSX Registry

Step 1: Setup Eclipse Foundation Account

1. Create account at https://accounts.eclipse.org/
2. Sign the Eclipse Contributor Agreement (ECA):
   • Go to https://accounts.eclipse.org/user/eca
   • Read and sign the agreement

Step 2: Link GitHub Account

1. Go to https://accounts.eclipse.org/user/edit
2. Find “Social Accounts” section
3. Connect your GitHub account
4. Verify the connection is successful

Step 3: Create Namespace on Open VSX

1. Log in to https://open-vsx.org/ with GitHub
2. Go to https://open-vsx.org/user-settings/namespaces
3. Create a namespace (should match your publisher name)
4. Wait for approval (usually instant if ECA is signed)

Step 4: Generate Access Token

1. Go to https://open-vsx.org/user-settings/tokens
2. Click Generate New Token
3. Give it a description (e.g., “CLI Publishing”)
4. Copy the token immediately

Step 5: Publish with ovsx

# Login (first time only)
ovsx create-namespace your-namespace
# Enter your access token when prompted

# Package the extension (if not already packaged)
vsce package

# Publish to Open VSX
ovsx publish -p YOUR_ACCESS_TOKEN

# Or publish specific file
ovsx publish your-extension-0.0.1.vsix -p YOUR_ACCESS_TOKEN

Step 6: Verify on Open VSX

Visit https://open-vsx.org/ and search for your extension.

Automating with CI/CD

GitHub Actions Example

Create .github/workflows/publish.yml:

name: Publish Extension

on:
  release:
    types: [created]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'

      - name: Install dependencies
        run: npm install

      - name: Build extension
        run: npm run compile

      - name: Package extension
        run: npx vsce package

      - name: Publish to VS Marketplace
        run: npx vsce publish -p ${{ secrets.VSCE_TOKEN }}

      - name: Publish to Open VSX
        run: npx ovsx publish -p ${{ secrets.OVSX_TOKEN }}

Setup GitHub Secrets

1. Go to your repository → Settings → Secrets and variables → Actions
2. Add secrets:
   • VSCE_TOKEN: Your Azure DevOps PAT
   • OVSX_TOKEN: Your Open VSX access token

Best Practices

Version Management

// Use semantic versioning
{
  "version": "MAJOR.MINOR.PATCH"
}

// Example:
// 1.0.0 - Initial stable release
// 1.1.0 - New features, backward compatible
// 1.1.1 - Bug fixes
// 2.0.0 - Breaking changes

Pre-publish Checklist

• [ ] Test extension thoroughly in VS Code
• [ ] Update CHANGELOG.md
• [ ] Update version in package.json
• [ ] Update README.md if features changed
• [ ] Check all links work
• [ ] Verify icon displays correctly (128×128 PNG)
• [ ] Run vsce package and test the .vsix locally
• [ ] Commit and push all changes
• [ ] Create Git tag for version

Security Best Practices

# Never commit tokens to Git
# Add to .gitignore:
echo "*.vsix" >> .gitignore
echo ".env" >> .gitignore

# Store tokens in environment variables
export VSCE_TOKEN="your-token"
export OVSX_TOKEN="your-token"

# Or use a .env file (don't commit!)

Extension Quality Guidelines

1. Performance

   • Minimize activation time
   • Use activation events efficiently
   • Lazy load heavy dependencies

2. User Experience

   • Provide clear error messages
   • Add configuration options
   • Include helpful documentation

3. Compatibility

   • Test on multiple VS Code versions
   • Support both Windows and Unix line endings
   • Consider different VS Code themes

Common Issues and Solutions

Issue: “Publisher not found”

Solution: Create publisher first with vsce create-publisher or via web interface.

Issue: “Missing repository field”

Solution: Add repository to package.json:

"repository": {
  "type": "git",
  "url": "https://github.com/username/repo"
}

Issue: “Icon not found”

Solution:

• Ensure icon.png exists in root directory
• Use 128×128 PNG format
• Reference it in package.json: "icon": "icon.png"

Issue: Open VSX “Must sign Publisher Agreement”

Solution: See my other article on solving this specific issue.

Issue: “Invalid version”

Solution: Use semantic versioning format (X.Y.Z) in package.json.

Updating Your Extension

# 1. Make your changes
# 2. Update CHANGELOG.md
# 3. Test thoroughly

# 4. Bump version and publish
vsce publish patch  # or minor, or major

# 5. Publish to Open VSX
ovsx publish -p YOUR_TOKEN

# 6. Create Git tag
git tag v0.0.2
git push --tags

Useful Commands Reference

# Package without publishing
vsce package

# Publish with specific version
vsce publish 1.0.0

# Unpublish (use carefully!)
vsce unpublish publisher.extension-name

# List all versions
vsce show publisher.extension-name

# Open VSX commands
ovsx get extension-name
ovsx publish package.vsix -p TOKEN
ovsx version

Resources

• VS Code Extension API
• Publishing Extensions Guide
• VS Marketplace Management
• Open VSX Wiki
• vsce Documentation
• ovsx Documentation

Conclusion

Publishing VS Code extensions requires setup, but once configured, the process is straightforward. Key points:

1. Set up accounts and tokens for both marketplaces
2. Prepare quality documentation
3. Test thoroughly before publishing
4. Automate with CI/CD for efficiency
5. Keep both marketplaces in sync

Remember: Open VSX is important for VS Code forks like VSCodium, Gitpod, and others that don’t use the Microsoft Marketplace.

Happy publishing!

This content originally appeared on DEV Community and was authored by yao tang