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

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"
}

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

Performance

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

User Experience

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

Security

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:

Commands API - Register and execute commands
Text Editor API - Manipulate text documents
Workspace API - Work with files and folders
Languages API - Provide language features
Debugging API - Integrate debuggers
Authentication API - Implement auth providers
Webview API - Create custom UI panels

Extension API

Core Services

Platform APIs

VS Code Extension API Overview

VS Code Extension API Overview

API Namespaces

Core Namespaces

commands

window

workspace

languages

debug

authentication

webview

env

Getting Started

Extension Manifest

Core Concepts

Disposables

Promises and Thenables

Events

API Versioning

Common Patterns

Configuration Settings

Status Bar Items

Output Channels

Best Practices

Resources

Next Steps

​VS Code Extension API Overview

​API Namespaces

​Core Namespaces

commands

window

workspace

languages

debug

authentication

webview

env

​Getting Started

​Extension Manifest

​Core Concepts

​Disposables

​Promises and Thenables

​Events

​API Versioning

​Common Patterns

​Configuration Settings

​Status Bar Items

​Output Channels

​Best Practices

​Resources

​Next Steps

VS Code Extension API Overview

API Namespaces

Core Namespaces

Getting Started

Extension Manifest

Core Concepts

Disposables

Promises and Thenables

Events

API Versioning

Common Patterns

Configuration Settings

Status Bar Items

Output Channels

Best Practices

Resources

Next Steps