Step-by-Step Guide to Building a VSCode Extension

Photo by Ulvi Safari on Unsplash

Writing a Visual Studio Code (VSCode) extension involves using the VSCode Extension API to add custom functionality to the editor. Here’s a step-by-step guide:

1. Prerequisites

• Node.js: Ensure Node.js is installed. VSCode extensions are written in JavaScript/TypeScript.
• VSCode: Install Visual Studio Code.
• Yeoman and VSCode Extension Generator: Install tools to scaffold an extension.

npm install -g yo generator-code

2. Create a New Extension

1. Run the generator:

yo code

2. Follow the prompts:

• Type of extension: Choose JavaScript or TypeScript.
• Features: Basic hello world or advanced features.
• Extension name: Provide a name for your extension.
• Directory: Choose where to create the project.

This creates a folder structure like:

my-vscode-extension/
│
├── .vscode/              # Debugging configuration
├── src/                  # Source code (for TypeScript projects)
│   └── extension.ts
├── package.json          # Extension metadata and dependencies
├── tsconfig.json         # TypeScript configuration
├── README.md             # Extension description
└── CHANGELOG.md          # Changes between versions

3. Understand Key Files

• package.json: The metadata file defines the extension’s capabilities, such as commands, activation events, and permissions.
• extension.ts: The entry point for your extension logic.
• .vscode/launch.json: Configures debugging for your extension.

4. Write Your Extension Logic

extension.ts Example:

import * as vscode from 'vscode';

export function activate(context: vscode.ExtensionContext) {
  // Register a command
  let disposable = vscode.commands.registerCommand('extension.helloWorld', () => {
    vscode.window.showInformationMessage('Hello, World!');
  });

  context.subscriptions.push(disposable);
}

export function deactivate() {}

• activate: Called when the extension is activated.
• deactivate: Called when the extension is deactivated.

package.json Updates:

Add a command to register in the Command Palette:

{
  "contributes": {
    "commands": [
      {
        "command": "extension.helloWorld",
        "title": "Hello World"
      }
    ]
  }
}

5. Test Your Extension

1. Open your extension project in VSCode.

2. Press F5 to start debugging. This launches a new instance of VSCode with your extension installed.

3. Test your command in the Command Palette (Ctrl+Shift+P or Cmd+Shift+P on macOS).

6. Add Features

Enhance your extension with:

• Commands: Perform actions via the Command Palette.
• Events: Respond to file edits, saves, or other triggers.
• Custom Views: Add sidebars, panels, or tree views.
• Language Features: Provide syntax highlighting, IntelliSense, or snippets.

Explore the VSCode API documentation for details.

7. Publish Your Extension

1. Install the VSCode Extension Manager:

npm install -g vsce

2. Package your extension:

vsce package

This creates a .vsix file.

3. Publish to the VSCode Marketplace:

• Create a publisher account.
• Use vsce login to authenticate.
• Run:

vsce publish

8. Example Features to Try

• Add a Status Bar Item:

let statusBar = vscode.window.createStatusBarItem(vscode.StatusBarAlignment.Right);
statusBar.text = "$(zap) Extension Active";
statusBar.show();
context.subscriptions.push(statusBar);

• Listen to File Save Events:

vscode.workspace.onDidSaveTextDocument((document) => {
  vscode.window.showInformationMessage(`You saved: ${document.fileName}`);
});