vscode-extension

name	vscode-extension
description	>- Use when this capability is needed.

VS Code Extension Development

When to Use

• Creating a new VS Code extension from scratch
• Adding commands, keybindings, or menu contributions
• Building tree views, sidebar panels, or webview UIs
• Implementing language features (completion, diagnostics, hover, CodeLens)
• Writing extension tests with @vscode/test-electron
• Packaging and publishing to the VS Code Marketplace

Official Documentation

• VS Code Extension API
• Extension Guides
• VS Code API Reference
• Extension Manifest (package.json)
• Activation Events
• Publishing Extensions

Procedure

Step 1 — Scaffold & Project Structure

Use yo code or manual setup. Follow this structure:

my-extension/
├── .vscode/
│   ├── launch.json          # Extension Host debug config
│   └── tasks.json           # Build tasks
├── src/
│   ├── extension.ts         # Entry point: activate() and deactivate()
│   ├── commands/             # Command handler implementations
│   ├── providers/            # TreeDataProvider, CompletionProvider, etc.
│   ├── views/                # Webview panel creation and messaging
│   ├── services/             # Business logic, API clients
│   └── utils/                # Helpers, constants
├── webview-ui/               # React/Svelte webview source (if applicable)
│   ├── src/
│   └── vite.config.ts
├── test/
│   ├── suite/                # Integration tests (Extension Host)
│   └── unit/                 # Pure unit tests (no VS Code API)
├── package.json              # Extension manifest + contributions
├── tsconfig.json
├── esbuild.config.mjs        # Bundler config
├── .vscodeignore              # Files to exclude from VSIX
├── CHANGELOG.md
└── README.md

Key Rules:

• src/extension.ts exports activate(context) and deactivate().
• Register all disposables via context.subscriptions.push(...).
• Keep activate() lean — lazy-initialize heavy resources.

Step 2 — Extension Manifest (package.json)

{
  "name": "my-extension",
  "displayName": "My Extension",
  "description": "A VS Code extension that does X",
  "version": "0.1.0",
  "publisher": "your-publisher-id",
  "engines": { "vscode": "^1.96.0" },
  "categories": ["Other"],
  "activationEvents": [],
  "main": "./dist/extension.js",
  "contributes": {
    "commands": [
      {
        "command": "myExtension.helloWorld",
        "title": 
         
      
    
     
      
         
         
         
      
    
     
       
             
      
    
     
       
       
         
           
           
           
        
      
    
  

Key Rules:

• Use activationEvents: [] for lazy activation (VS Code 1.74+).
• Prefix all commands with extensionName.commandName.
• Declare every command in both commands and menus as needed.
• Use when clauses for conditional command availability.

Step 3 — Commands & Activation

import * as vscode from 'vscode';

export function activate(context: vscode.ExtensionContext): void {
    // Register commands
    context.subscriptions.push(
        vscode.commands.registerCommand('myExtension.helloWorld', async () => {
            const name = await vscode.window.showInputBox({
                prompt: 'Enter your name',
                placeHolder: 'World'
            });
            vscode.window.showInformationMessage(`Hello, ${name ?? 'World'}!`);
        })
    );

    // Register providers
    const treeProvider = new MyTreeDataProvider();
    context.subscriptions.push(
        vscode.window.registerTreeDataProvider('myExtension.treeView', treeProvider)
    );
}

export function deactivate(): void {
    // Cleanup resources if needed
}

Key Rules:

• Always push disposables to context.subscriptions.
• Use async commands with proper error handling.
• Show progress for long-running operations via vscode.window.withProgress().
• Read configuration via vscode.workspace.getConfiguration('myExtension').

Step 4 — Tree Views

import * as vscode from 'vscode';

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

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

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

    async getChildren(element?: TreeItem): Promise<TreeItem[]> {
        if (!element) {
            // Root items
            return this.getRootItems();
        }
        // Child items
        return this.getChildItems(element);
    }

    private async getRootItems(): <[]> {
         [
             (, vscode..),
             (, vscode..)
        ];
    }

      (: ): <[]> {
         [];
    }
}

    {
    () {
        (label, collapsibleState);
    }
}

Declare in package.json:

"contributes": {
    "views": {
        "explorer": [
            { "id": "myExtension.treeView", "name": "My Items" }
        ]
    },
    "viewsContainers": {
        "activitybar": [
            {
                "id": "myExtension-sidebar",
                "title": "My Extension",
                "icon": "resources/icon.svg"
            }
        ]
    }
}

Step 5 — Webview Panels

export class MyWebviewPanel {
    private panel: vscode.WebviewPanel | undefined;

    constructor(private readonly extensionUri: vscode.Uri) {}

    show(): void {
        if (this.panel) {
            this.panel.reveal();
            return;
        }

        this.panel = vscode.window.createWebviewPanel(
            'myExtension.panel',
            'My Panel',
            vscode.ViewColumn.One,
            {
                enableScripts: true,
                retainContextWhenHidden: true,
                localResourceRoots: [
                    vscode.Uri.joinPath(this.extensionUri, 'dist', 'webview')
                ]
            }
        );

        this.panel.webview.html = this.getHtml(this.panel.);

        
        ...(
             {
                 (message.) {
                     :
                        .(message.);
                        ;
                }
            },
            ,
            []
        );

        ..( {
            . = ;
        });
    }

     (: vscode.):  {
         scriptUri = webview.(
            vscode..(., , , )
        );
         nonce = ();

         ;
    }

     (: ):  {
        
    }
}

 ():  {
     text = ;
     chars = ;
     ( i = ; i < ; i++) {
        text += chars.(.(.() * chars.));
    }
     text;
}

Key Rules:

• Always set Content-Security-Policy with nonce — never allow inline scripts.
• Use localResourceRoots to restrict file access.
• Communicate via postMessage / onDidReceiveMessage — no direct DOM access.
• Use retainContextWhenHidden sparingly — it increases memory usage.

Step 6 — Language Features

// Completion Provider
class MyCompletionProvider implements vscode.CompletionItemProvider {
    provideCompletionItems(
        document: vscode.TextDocument,
        position: vscode.Position
    ): vscode.CompletionItem[] {
        const item = new vscode.CompletionItem('mySnippet', vscode.CompletionItemKind.Snippet);
        item.insertText = new vscode.SnippetString('console.log($1);');
        item.documentation = new vscode.MarkdownString('Inserts a console.log statement');
        return [item];
    }
}

// Diagnostics
const diagnosticCollection = vscode.languages.createDiagnosticCollection('myExtension');

function updateDiagnostics(document: vscode.TextDocument): void {
    const diagnostics: vscode.Diagnostic[] = [];
    // Analyze document and add diagnostics
    const range = new vscode.Range(0, 0, 0, 10);
    diagnostics.( vscode.(range, , vscode..));
    diagnosticCollection.(., diagnostics);
}


context..(
    vscode..(,  ()),
    diagnosticCollection
);

Step 7 — Testing

Integration Tests (run in Extension Host):

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

suite('Extension Test Suite', () => {
    vscode.window.showInformationMessage('Start all tests.');

    test('Command is registered', async () => {
        const commands = await vscode.commands.getCommands(true);
        assert.ok(commands.includes('myExtension.helloWorld'));
    });

    test('Command executes successfully', async () => {
        await vscode.commands.executeCommand('myExtension.helloWorld');
        // Verify side effects
    });
});

Unit Tests (no VS Code dependency):

import { describe, it, expect } from 'vitest';
import { parseInput } from '../src/utils/parser';

describe('Parser', () => {
    it('should parse valid input', () => {
        const result = parseInput('test input');
        expect(result).toBeDefined();
    });
});

Key Rules:

• Use @vscode/test-electron for integration tests that need the Extension Host.
• Use Vitest for pure logic unit tests (no VS Code API dependency).
• Mock vscode namespace in unit tests when needed.
• Test both command registration and execution.

Step 8 — Bundling & Publishing

Use esbuild for fast bundling:

// esbuild.config.mjs
import * as esbuild from 'esbuild';

const production = process.argv.includes('--production');

await esbuild.build({
    entryPoints: ['src/extension.ts'],
    bundle: true,
    outfile: 'dist/extension.js',
    external: ['vscode'],
    format: 'cjs',
    platform: 'node',
    target: 'node20',
    sourcemap: !production,
    minify: production,
});

Publishing Checklist:

1. Update version in package.json
2. Update CHANGELOG.md
3. Run tests: npm test
4. Package: vsce package
5. Test VSIX locally: code --install-extension my-extension-0.1.0.vsix
6. Publish: vsce publish

.vscodeignore:

.vscode/**
src/**
test/**
webview-ui/src/**
node_modules/**
.gitignore
tsconfig.json
esbuild.config.mjs
**/*.map

Quick Reference

Concept	API
Show message	vscode.window.showInformationMessage()
Input box	vscode.window.showInputBox()
Quick pick	vscode.window.showQuickPick()
Progress	vscode.window.withProgress()
File picker	vscode.window.showOpenDialog()
Status bar	vscode.window.createStatusBarItem()
Output channel	vscode.window.createOutputChannel()
Read config	vscode.workspace.getConfiguration()
File system	vscode.workspace.fs.readFile()
Watch files	vscode.workspace.createFileSystemWatcher()
Decorations	vscode.window.createTextEditorDecorationType()
CodeLens	vscode.languages.registerCodeLensProvider()
Hover	vscode.languages.registerHoverProvider()
Definition	vscode.languages.registerDefinitionProvider()

Anti-Patterns

• Never block the extension host with synchronous operations — always use async.
• Never use eval() or Function() in webviews — use nonce-based CSP.
• Never store secrets in configuration — use context.secrets (SecretStorage API).
• Never bundle node_modules in the VSIX — use esbuild to bundle into a single file.
• Never use global state for communication between components — use event emitters.

---

Source: congiuluc/my-awesome-copilot — distributed by TomeVault.