Skip to main content

​
VS Code Extension API Overview

The Visual Studio Code Extension API allows you to extend and customize VS Code. This comprehensive API provides access to the editor’s core functionality, enabling you to create powerful extensions.

​
API Namespaces

The VS Code API is organized into several namespaces, each providing specific functionality:

​
Core Namespaces

commands

Register and execute commands

window

Interact with the editor window and UI

workspace

Access workspace folders and files

languages

Provide language features like IntelliSense

debug

Integrate debugging capabilities

authentication

Implement authentication providers

webview

Create custom webview panels

env

Access environment information

​
Getting Started

Every VS Code extension exports an activate function that receives an ExtensionContext object: 
import * as vscode from 'vscode';

export function activate(context: vscode.ExtensionContext) {
    console.log('Extension activated');
    
    // Register commands, providers, etc.
    let disposable = vscode.commands.registerCommand('extension.helloWorld', () => {
        vscode.window.showInformationMessage('Hello World!');
    });
    
    context.subscriptions.push(disposable);
}

export function deactivate() {
    // Cleanup resources
}

​
Extension Manifest

Extensions are defined by a package.json file that specifies activation events, contributions, and dependencies:
package.json
{
  "name": "my-extension",
  "displayName": "My Extension",
  "version": "1.0.0",
  "engines": {
    "vscode": "^1.80.0"
  },
  "activationEvents": [
    "onCommand:extension.helloWorld"
  ],
  "main": "./out/extension.js",
  "contributes": {
    "commands": [
      {
        "command": "extension.helloWorld",
        "title": "Hello World"
      }
    ]
  }
}

​
Core Concepts

​
Disposables

Many VS Code APIs return Disposable objects that must be disposed to prevent memory leaks: 
const disposable = vscode.commands.registerCommand('my.command', () => {});
context.subscriptions.push(disposable);

// Or manually dispose:
disposable.dispose();
Always add disposables to context.subscriptions to ensure they’re properly cleaned up when your extension is deactivated.

​
Promises and Thenables

Most async operations return Thenable<T> (Promise-compatible): 
vscode.workspace.openTextDocument(uri).then(document => {
    return vscode.window.showTextDocument(document);
}).then(editor => {
    console.log('Document opened in editor');
});

// Or with async/await:
const document = await vscode.workspace.openTextDocument(uri);
const editor = await vscode.window.showTextDocument(document);

​
Events

The API uses an event-driven model. Subscribe to events using the Event<T> interface: 
vscode.workspace.onDidSaveTextDocument(document => {
    console.log(`Document saved: ${document.uri}`);
});

vscode.window.onDidChangeActiveTextEditor(editor => {
    if (editor) {
        console.log(`Active editor changed to: ${editor.document.fileName}`);
    }
});

​
API Versioning

The API version is specified in your package.json: 
"engines": {
  "vscode": "^1.80.0"
}
​
version
string
required
Minimum VS Code version required (semver format)
This ensures your extension only runs on compatible VS Code versions.

​
Common Patterns

​
Configuration Settings

Access and modify settings through the workspace configuration: 
const config = vscode.workspace.getConfiguration('myExtension');
const value = config.get('setting', 'default');

// Update configuration
await config.update('setting', 'newValue', vscode.ConfigurationTarget.Global);

​
Status Bar Items

Create status bar items to display information: 
const statusBar = vscode.window.createStatusBarItem(
    vscode.StatusBarAlignment.Right,
    100
);
statusBar.text = '$(check) Ready';
statusBar.command = 'extension.showStatus';
statusBar.show();
context.subscriptions.push(statusBar);

​
Output Channels

Create output channels for logging: 
const output = vscode.window.createOutputChannel('My Extension');
output.appendLine('Extension started');
output.show();

​
Best Practices

  • Lazy load modules and activate only when needed
  • Use activation events to delay extension loading
  • Dispose of resources properly to prevent memory leaks
  • Avoid synchronous operations that block the UI
  • Provide clear progress indicators for long operations
  • Use appropriate notification severity (info, warning, error)
  • Support keyboard shortcuts and accessibility
  • Follow VS Code’s UI guidelines and conventions
  • Validate user input and external data
  • Use secure protocols for network requests
  • Don’t store secrets in plain text
  • Request minimal permissions

​
Resources

​
Next Steps

Explore specific API areas: