DEV Community

yao tang
yao tang

Posted on

Complete Guide: Publishing VS Code Extensions to Both Marketplaces

#vscode #extensions #development #tutorial

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

Required Tools 

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

# Install ovsx (Open VSX CLI)
npm install -g ovsx
Enter fullscreen mode Exit fullscreen mode

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)
Enter fullscreen mode Exit fullscreen mode

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"
  ]
}
Enter fullscreen mode Exit fullscreen mode

3. Create a .vscodeignore File 

.vscode/**
.git/**
.gitignore
node_modules/**
src/**
.eslintrc.json
tsconfig.json
**/*.map
**/*.ts
!dist/**
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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):

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
Enter fullscreen mode Exit fullscreen mode

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 }}
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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 (128x128 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!)
Enter fullscreen mode Exit fullscreen mode

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"
}
Enter fullscreen mode Exit fullscreen mode

Issue: "Icon not found"

Solution:

  • Ensure icon.png exists in root directory
  • Use 128x128 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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Resources

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! 🚀

Top comments (0)