Introduction to
VSCode Extensions

Visual Studio Code launched in 2015 and quickly became the most popular code editor in the world. The Stack Overflow Developer Survey consistently shows 70%+ adoption. The secret is its extension model.

Unlike monolithic IDEs, VSCode ships a lean core and delegates language support, debugging, themes, and tooling to extensions. This means the community — not Microsoft — drives most of the editor's capability.

my-extension/
├── .vscode/
│   └── launch.json        # debug config
├── src/
│   └── extension.ts       # entry point
├── package.json           # manifest (critical!)
├── tsconfig.json          # TypeScript config
├── README.md              # Marketplace listing
├── CHANGELOG.md           # version history
└── icon.png               # 128x128 Marketplace icon

{
  "name": "my-extension",
  "displayName": "My Extension",
  "version": "1.0.0",
  "engines": { "vscode": "^1.85.0" },
  "activationEvents": [],
  "main": "./out/extension.js",
  "contributes": {
    "commands": [{
      "command": "myExt.helloWorld",
      "title": "Hello World"
    }],
    "keybindings": [{
      "command": "myExt.helloWorld",
      "key": "ctrl+shift+h",
      "when": "editorTextFocus"
    }],
    "configuration": {
      "title": "My Extension",
      "properties": {
        "myExt.greeting": {
          "type": "string",
          "default": "Hello"
        }
      }
    }
  }
}

# Install the generator
npm install -g yo generator-code

# Scaffold a new extension
yo code

# Choose:
#   ▸ New Extension (TypeScript)
#   Name: hello-world
#   Identifier: hello-world
#   Enable strict mode: Yes

import * as vscode from 'vscode';

// Called when the extension is activated
export function activate(context: vscode.ExtensionContext) {

  // Register a command
  const disposable = vscode.commands.registerCommand(
    'hello-world.helloWorld',
    () => {
      // Read from configuration
      const config = vscode.workspace.getConfiguration('myExt');
      const greeting = config.get<string>('greeting', 'Hello');

      // Show an information message
      vscode.window.showInformationMessage(
        `${greeting} from Hello World!`
      );
    }
  );

  // Push to subscriptions for cleanup
  context.subscriptions.push(disposable);
}

// Called when the extension is deactivated
export function deactivate() {}

Commands are the primary interaction model in VSCode. Every action — from opening a file to formatting code — is a command. Extensions register commands and bind them to menus, keybindings, or other triggers.

// Register a text editor command
const cmd = vscode.commands.registerTextEditorCommand(
  'myExt.insertDate',
  (editor, edit) => {
    const date = new Date().toISOString().split('T')[0];
    edit.insert(editor.selection.active, date);
  }
);

// Execute another extension's command
await vscode.commands.executeCommand(
  'editor.action.formatDocument'
);

"when": "editorLangId == typescript && !editorReadonly"
"when": "resourceScheme == file"
"when": "view == myCustomView"

"contributes": {
  "menus": {
    "editor/context": [{
      "command": "myExt.insertDate",
      "when": "editorTextFocus",
      "group": "1_modification"
    }],
    "explorer/context": [{
      "command": "myExt.processFile",
      "when": "resourceExtname == .csv"
    }],
    "editor/title": [{
      "command": "myExt.togglePreview",
      "group": "navigation"
    }],
    "commandPalette": [{
      "command": "myExt.insertDate",
      "when": "editorIsOpen"
    }]
  }
}

// Completion provider
vscode.languages.registerCompletionItemProvider(
  'markdown',
  {
    provideCompletionItems(doc, pos) {
      const items = [
        new vscode.CompletionItem('TODO',
          vscode.CompletionItemKind.Keyword),
        new vscode.CompletionItem('FIXME',
          vscode.CompletionItemKind.Keyword),
      ];
      return items;
    }
  },
  '@'  // trigger character
);

// Hover provider
vscode.languages.registerHoverProvider('json', {
  provideHover(doc, pos) {
    const range = doc.getWordRangeAtPosition(pos);
    const word = doc.getText(range);
    return new vscode.Hover(`Key: **${word}**`);
  }
});

The Language Server Protocol is a JSON-RPC protocol between an editor and a language-specific server. Invented by Microsoft for VSCode, it's now used by Vim, Emacs, Sublime, and others.

// Client side (extension.ts)
import { LanguageClient, TransportKind }
  from 'vscode-languageclient/node';

const serverModule = context.asAbsolutePath(
  'server/out/server.js'
);

const client = new LanguageClient(
  'myLangServer', 'My Language Server',
  { module: serverModule, transport: TransportKind.ipc },
  { documentSelector: [{ scheme: 'file', language: 'myLang' }] }
);

client.start();

TreeViews let you add custom panels to the sidebar, panel area, or Activity Bar. They display hierarchical data with icons, descriptions, and context menus.

"contributes": {
  "viewsContainers": {
    "activitybar": [{
      "id": "myExtExplorer",
      "title": "My Extension",
      "icon": "resources/icon.svg"
    }]
  },
  "views": {
    "myExtExplorer": [{
      "id": "myExt.projectsView",
      "name": "Projects"
    }, {
      "id": "myExt.tasksView",
      "name": "Tasks"
    }]
  }
}

class ProjectProvider
  implements vscode.TreeDataProvider<ProjectItem> {

  private _onDidChange = new vscode.EventEmitter<
    ProjectItem | undefined
  >();
  readonly onDidChangeTreeData = this._onDidChange.event;

  getTreeItem(el: ProjectItem): vscode.TreeItem {
    return el;
  }

  async getChildren(el?: ProjectItem) {
    if (!el) {
      return this.getProjects();  // root items
    }
    return el.getFiles();          // child items
  }

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

// Register the provider
vscode.window.registerTreeDataProvider(
  'myExt.projectsView',
  new ProjectProvider()
);

// Create a Webview panel
const panel = vscode.window.createWebviewPanel(
  'myPreview',           // internal ID
  'My Preview',          // title
  vscode.ViewColumn.Two, // editor column
  {
    enableScripts: true,           // allow JS
    retainContextWhenHidden: true, // keep state
    localResourceRoots: [          // restrict access
      vscode.Uri.joinPath(context.extensionUri, 'media')
    ]
  }
);

// Set HTML content
panel.webview.html = getHtmlContent(panel.webview);

// Receive messages from webview
panel.webview.onDidReceiveMessage(msg => {
  if (msg.command === 'save') {
    saveData(msg.data);
  }
});

<!-- Inside the webview HTML -->
<script>
  const vscode = acquireVsCodeApi();

  // Send message to extension
  vscode.postMessage({
    command: 'save',
    data: { name: 'test' }
  });

  // Receive messages from extension
  window.addEventListener('message', event => {
    const msg = event.data;
    if (msg.command === 'update') {
      document.getElementById('content')
        .textContent = msg.text;
    }
  });

  // Persist state across visibility changes
  vscode.setState({ scrollPos: 42 });
  const state = vscode.getState();
</script>

// Find files
const files = await vscode.workspace.findFiles(
  '**/*.test.ts',    // include
  '**/node_modules/**' // exclude
);

// Read & write files
const uri = vscode.Uri.file('/path/to/file.txt');
const data = await vscode.workspace.fs.readFile(uri);
await vscode.workspace.fs.writeFile(uri, Buffer.from('new'));

// Watch for changes
const watcher = vscode.workspace.createFileSystemWatcher(
  '**/*.json'
);
watcher.onDidChange(uri => console.log('Changed:', uri));
watcher.onDidCreate(uri => console.log('Created:', uri));
watcher.onDidDelete(uri => console.log('Deleted:', uri));

// Apply a batch of edits
const wsEdit = new vscode.WorkspaceEdit();
wsEdit.replace(uri, range, 'replacement text');
wsEdit.createFile(newUri, { ignoreIfExists: true });
await vscode.workspace.applyEdit(wsEdit);

// Read configuration
const config = vscode.workspace.getConfiguration('myExt');
const value = config.get<string>('greeting', 'default');

// Write configuration
await config.update(
  'greeting', 'Bonjour',
  vscode.ConfigurationTarget.Workspace
);

// Watch for config changes
vscode.workspace.onDidChangeConfiguration(e => {
  if (e.affectsConfiguration('myExt.greeting')) {
    // reload
  }
});

VSCode has first-class support for debugging extensions. Press F5 to launch an Extension Development Host — a second VSCode window with your extension loaded.

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Run Extension",
      "type": "extensionHost",
      "request": "launch",
      "args": ["--extensionDevelopmentPath=${workspaceFolder}"],
      "outFiles": ["${workspaceFolder}/out/**/*.js"],
      "preLaunchTask": "npm: watch"
    },
    {
      "name": "Extension Tests",
      "type": "extensionHost",
      "request": "launch",
      "args": [
        "--extensionDevelopmentPath=${workspaceFolder}",
        "--extensionTestsPath=${workspaceFolder}/out/test"
      ]
    }
  ]
}

// Create a dedicated output channel
const log = vscode.window.createOutputChannel('My Extension');
log.appendLine('Extension activated');
log.show();  // focus the channel

// Use console.log too — appears in Debug Console
console.log('Debug info:', someObject);

Extension tests run inside a real VSCode instance via @vscode/test-electron. This gives tests full access to the VSCode API, real file systems, and installed extensions.

// src/test/runTest.ts
import { runTests } from '@vscode/test-electron';
import path from 'path';

async function main() {
  await runTests({
    extensionDevelopmentPath: path.resolve(__dirname, '../../'),
    extensionTestsPath: path.resolve(__dirname, './suite/index'),
    launchArgs: [
      '--disable-extensions',  // isolate your extension
      path.resolve(__dirname, '../../test-fixtures')
    ]
  });
}
main();

// src/test/suite/extension.test.ts
import * as assert from 'assert';
import * as vscode from 'vscode';

suite('Extension Tests', () => {

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

  test('Inserts date at cursor', async () => {
    const doc = await vscode.workspace.openTextDocument({
      content: '', language: 'plaintext'
    });
    const editor = await vscode.window.showTextDocument(doc);

    await vscode.commands.executeCommand('myExt.insertDate');

    const text = doc.getText();
    assert.match(text, /^\d{4}-\d{2}-\d{2}$/);
  });
});

const controller = vscode.notebooks
  .createNotebookController(
    'myKernel', 'my-notebook', 'My Kernel'
  );

controller.executeHandler = async (cells) => {
  for (const cell of cells) {
    const exec = controller.createNotebookCellExecution(cell);
    exec.start(Date.now());
    // Run the cell content
    const result = evaluate(cell.document.getText());
    exec.replaceOutput([
      new vscode.NotebookCellOutput([
        vscode.NotebookCellOutputItem.text(result)
      ])
    ]);
    exec.end(true);
  }
};

// Create a terminal
const term = vscode.window.createTerminal({
  name: 'My Build',
  cwd: '/path/to/project',
  env: { NODE_ENV: 'test' }
});

term.show();
term.sendText('npm test');

// Terminal link provider
vscode.window.registerTerminalLinkProvider({
  provideTerminalLinks(ctx) {
    // Detect patterns in terminal output
    const match = ctx.line.match(
      /error in (.+):(\d+)/
    );
    if (match) {
      return [{
        startIndex: match.index,
        length: match[0].length,
        file: match[1], line: match[2]
      }];
    }
  },
  handleTerminalLink(link) {
    // Open the file at the error line
  }
});

const scm = vscode.scm.createSourceControl(
  'myScm', 'My SCM'
);

const changes = scm.createResourceGroup(
  'changes', 'Changes'
);

changes.resourceStates = [{
  resourceUri: fileUri,
  decorations: {
    strikeThrough: false,
    tooltip: 'Modified'
  }
}];

scm.quickDiffProvider = {
  provideOriginalResource(uri) {
    // Return URI of the original file
    return toOriginalUri(uri);
  }
};

vsce (Visual Studio Code Extensions) is the CLI tool for packaging and publishing. It bundles your extension into a .vsix file — a zip containing your compiled code, manifest, README, and assets.

# Install vsce
npm install -g @vscode/vsce

# Package into a .vsix
vsce package
# Creates: my-extension-1.0.0.vsix

# Install locally for testing
code --install-extension my-extension-1.0.0.vsix

# Check what will be included
vsce ls

.vscode/**
src/**
node_modules/**
!node_modules/prod-dependency/**
**/*.test.ts
tsconfig.json
.eslintrc.json

// esbuild.mjs
import { build } from 'esbuild';

await build({
  entryPoints: ['src/extension.ts'],
  bundle: true,
  outfile: 'out/extension.js',
  external: ['vscode'],  // provided by VSCode
  format: 'cjs',
  platform: 'node',
  minify: true,
  sourcemap: true,
});

# 1. Create a publisher at:
#    https://marketplace.visualstudio.com/manage

# 2. Create a Personal Access Token (PAT)
#    Azure DevOps → User Settings → PATs
#    Scope: Marketplace (Manage)

# 3. Login with vsce
vsce login <publisher-name>
# Paste your PAT when prompted

# Publish current version
vsce publish

# Bump version and publish
vsce publish minor   # 1.0.0 → 1.1.0
vsce publish patch   # 1.1.0 → 1.1.1

# Pre-release versions
vsce publish --pre-release

{
  "publisher": "myPublisher",
  "displayName": "My Extension",
  "description": "One-line summary",
  "icon": "icon.png",
  "galleryBanner": {
    "color": "#0a0a0f",
    "theme": "dark"
  },
  "categories": [
    "Programming Languages",
    "Formatters",
    "Linters"
  ],
  "keywords": ["python", "linting", "formatter"],
  "repository": {
    "type": "git",
    "url": "https://github.com/me/my-ext"
  },
  "badges": [{
    "url": "https://img.shields.io/...",
    "href": "https://...",
    "description": "Build Status"
  }]
}

name: CI
on: [push, pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20 }
      - run: npm ci
      - run: npm run lint
      - run: npm run compile
      - run: npm test
        env:
          DISPLAY: ':99.0'
      - run: npx @vscode/vsce package
      - uses: actions/upload-artifact@v4
        with:
          name: vsix
          path: '*.vsix'

  publish:
    needs: build
    if: startsWith(github.ref, 'refs/tags/v')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20 }
      - run: npm ci
      - run: npx @vscode/vsce publish
        env:
          VSCE_PAT: ${{ secrets.VSCE_PAT }}