vscode-extension-builder

name	vscode-extension-builder
description	Comprehensive VSCode extension development expert that guides you through creating extensions using the official Yeoman generator tool. Provides interactive setup, configuration guidance, and development workflow support. Covers scaffolding with yo code, extension anatomy, debugging, testing, publishing, and API reference. Features primary access to complete VS Code API documentation at `@source/vscode-docs/api/` for authoritative reference. Use when starting new VSCode extensions, setting up development environment, configuring extension manifests, debugging extensions, or when mentioning VSCode extension creation, TypeScript extensions, plugin development, or editor customization. Built with official VS Code documentation, generator best practices, and complete API reference.
allowed-tools	Read, Write, Edit, Glob, Grep, Bash

VSCode Extension Expert

A comprehensive guide for developing Visual Studio Code extensions using TypeScript/JavaScript. This skill is built directly from the official VSCode extension samples repository and covers everything from basic extension creation to advanced language features, custom editors, and publishing workflows.

🎯 Getting Started with Official Generator

The best way to create a new VS Code extension is by using the official Yeoman generator tool.

Prerequisites

Ensure you have Node.js and Git installed.

Creating a New Extension

Option 1: One-time use (recommended)

npx --package yo --package generator-code -- yo code

Option 2: Global installation

npm install --global yo generator-code
yo code

After Creation

1. Open the extension folder in VS Code
2. Navigate to src/extension.ts
3. Press F5 to launch Extension Development Host
4. Test from Command Palette (Ctrl+Shift+P)

🛠️ How to Use This Skill

Starting a New Extension

"I want to create a new VS Code extension"
"Help me set up a VS Code extension project"

During Development

"How do I add a new command?"
"My extension isn't loading, can you help me debug?"
"I want to create a webview panel"

Working with Generated Projects

I'll respect your choices:

• Package manager: npm, yarn, pnpm, or bun
• Bundler: webpack, esbuild, or unbundled
• Language: TypeScript or JavaScript
• Extension type: commands, themes, language support, etc.

Core Concepts

Extension Anatomy

Basic package.json

{
  "name": "my-extension",
  "displayName": "My Extension",
  "version": "0.0.1",
  "engines": { "vscode": "^1.85.0" },
  "categories": ["Other"],
  "activationEvents": ["onCommand:extension.helloWorld"],
  "main": "./out/extension.js",
  "contributes": {
    "commands": [{
      "command": "extension.helloWorld",
      "title": "Hello World"
    }]
  }
}

Extension Entry Point

import * as vscode from 'vscode';

export function activate(context: vscode.ExtensionContext) {
    console.log('Extension "my-extension" is now active!');

    const disposable = vscode.commands.registerCommand('extension.helloWorld', () => {
        vscode.window.showInformationMessage('Hello World!');
    });

    context.subscriptions.push(disposable);
}

export function deactivate() {}

Common Patterns

Command Registration

const commands = [
    vscode.commands.registerCommand('extension.doSomething', () => {
        // Implementation
    }),
    vscode.commands.registerCommand('extension.doSomethingElse', () => {
        // Another command
    })
];

context.subscriptions.push(...commands);

Status Bar Integration

const statusBarItem = vscode.window.createStatusBarItem(
    vscode.StatusBarAlignment.Right,
    100
);
statusBarItem.text = '$(gear) My Extension';
statusBarItem.tooltip = 'My Extension Status';
statusBarItem.command = 'extension.toggleFeature';
statusBarItem.show();

context.subscriptions.push(statusBarItem);

Webview Development

Basic Webview

export function createWebviewPanel(context: vscode.ExtensionContext) {
    const panel = vscode.window.createWebviewPanel(
        'myWebview',
        'My Webview',
        vscode.ViewColumn.One,
        {
            enableScripts: true,
            retainContextWhenHidden: true
        }
    );

    panel.webview.html = getWebviewContent(context.extensionUri);

    panel.webview.onDidReceiveMessage(
        message => {
            switch (message.command) {
                case 'alert':
                    vscode.window.showInformationMessage(message.text);
                    return;
            }
        },
        undefined,
        context.subscriptions
    );

    return panel;
}

Tree View Provider

export class TreeDataProvider implements vscode.TreeDataProvider<TreeItem> {
    private _onDidChangeTreeData: vscode.EventEmitter<TreeItem | undefined | null | void> = new vscode.EventEmitter<TreeItem | undefined | null | void>();
    readonly onDidChangeTreeData: vscode.Event<TreeItem | undefined | null | void> = this._onDidChangeTreeData.event;

    private treeItems: TreeItem[] = [];

    refresh(): void {
        this._onDidChangeTreeData.fire();
    }

    getTreeItem(element: TreeItem): vscode.TreeItem {
        return element;
    }

    getChildren(element?: TreeItem): Thenable<TreeItem[]> {
        if (!element) {
            return Promise.resolve(this.treeItems);
        }
        return Promise.resolve([]);
    }
}

Language Features

Code Completion

export class CompletionItemProvider implements vscode.CompletionItemProvider {
    provideCompletionItems(
        document: vscode.TextDocument,
        position: vscode.Position,
        token: vscode.CancellationToken,
        context: vscode.CompletionContext
    ): vscode.CompletionItem[] {
        return [
            new vscode.CompletionItem('console.log', vscode.CompletionItemKind.Method),
            new vscode.CompletionItem('console.error', vscode.CompletionItemKind.Method)
        ];
    }
}

vscode.languages.registerCompletionItemProvider(
    'javascript',
    new CompletionItemProvider(),
    '.'
);

Configuration

Reading Settings

const config = vscode.workspace.getConfiguration('myExtension');
const enabled = config.get<boolean>('enabled', true);
const apiKey = config.get<string>('apiKey', '');

Configuration Schema (package.json)

{
  "contributes": {
    "configuration": {
      "title": "My Extension",
      "properties": {
        "myExtension.enabled": {
          "type": "boolean",
          "default": true,
          "description": "Enable/disable the extension"
        }
      }
    }
  }
}

Testing

Unit Tests

import * as assert from 'assert';
import * as vscode from 'vscode';

suite('Extension Test Suite', () => {
    test('Extension should be present', () => {
        assert.ok(vscode.extensions.getExtension('publisher.my-extension'));
    });

    test('Should register commands', async () => {
        const commands = await vscode.commands.getCommands();
        assert.ok(commands.includes('extension.helloWorld'));
    });
});

Publishing

# Install vsce
npm install -g @vscode/vsce

# Create publisher
vsce create-publisher your-publisher-name

# Package and publish
vsce package
vsce publish

📚 Official Resources

Primary API Documentation (Authoritative)

Complete VS Code API: @source/vscode-docs/api/ - FIRST REFERENCE

Core References:

• Extension API: @source/vscode-docs/api/references/vscode-api.md
• Extension Manifest: @source/vscode-docs/api/references/extension-manifest.md
• Contribution Points: @source/vscode-docs/api/references/contribution-points.md

Development Guides:

• Getting Started: @source/vscode-docs/api/get-started/
• Extension Guides: @source/vscode-docs/api/extension-guides/
• UX Guidelines: @source/vscode-docs/api/ux-guidelines/

Code Examples

Core Features (@source/vscode-extension-samples/):

• command-sample/ - Command registration
• tree-view-sample/ - Custom tree views
• completions-sample/ - Code completion
• webview-sample/ - Custom UI panels
• custom-editor-sample/ - Custom file editors

Quick Reference

Essential APIs

• vscode.commands.registerCommand() - Register commands
• vscode.window.createWebviewPanel() - Create webviews
• vscode.window.createTreeView() - Create tree views
• vscode.languages.registerCompletionItemProvider() - Add completions
• vscode.workspace.getConfiguration() - Read settings
• vscode.window.createStatusBarItem() - Status bar items

Common Contribution Points

• contributes.commands - Register commands
• contributes.views - Add view containers
• contributes.configuration - Add settings
• contributes.languages - Define new languages
• contributes.themes - Custom themes

Essential Commands

npx --package yo --package generator-code -- yo code
npm run compile          # Compile TypeScript
npm run watch           # Watch for changes
npm test                # Run tests
npm run package         # Package extension
vsce publish            # Publish to marketplace

Troubleshooting

Common Issues:

• Extension not loading: Check engines.vscode version
• Commands not registering: Verify command IDs match in package.json
• Activation issues: Check activationEvents

Debug Techniques:

• Use console.log() (Developer Tools console)
• Help > Toggle Developer Tools
• View > Output > Extension Host

See references/ADVANCED.md for advanced topics like file system providers, terminal integration, and performance optimization. See references/EXAMPLES.md for complete extension templates and detailed implementation examples.