Vscode Extension Patterns

VS Code Extension Patterns

Reusable patterns for VS Code extension development. Staleness Watch: See EXTERNAL-API-REGISTRY.md for source URLs and recheck cadence

Last validated: March 2026 (VS Code 1.111+)

Webview Dashboard

const [health, knowledge] = await Promise.all([checkHealth(), getKnowledgeSummary()]);
panel.webview.html = await getWebviewContent(health, knowledge);

TreeDataProvider for Sidebar

class WelcomeViewProvider implements vscode.WebviewViewProvider {
  resolveWebviewView(view: vscode.WebviewView) {
    view.webview.options = { enableScripts: true };
    view.webview.html = this.getHtmlContent();
    view.webview.onDidReceiveMessage(async (msg) => {
      if (msg.command === "refresh") await this.refresh();
    });
  }
}
vscode.window.registerWebviewViewProvider("my.welcomeView", new WelcomeViewProvider());

CSP-Compliant Webview Events

Problem: Inline onclick handlers violate CSP.

Solution: Use data-cmd with delegated listener:

<button data-cmd="play">Play</button>

document.addEventListener("click", (e) => {
  const cmd = e.target.closest("[data-cmd]")?.getAttribute("data-cmd");
  if (cmd === "play") audio.play();
});

CSP header (required when enableScripts: true):

const nonce = crypto.randomUUID();
const csp = `default-src 'none'; script-src 'nonce-${nonce}'; style-src 'unsafe-inline';`;
return `<html><head><meta http-equiv="Content-Security-Policy" content="${csp}"></head>...`;

Agent Hooks (1.111+)

Shell scripts at lifecycle points. Config: .github/hooks.json.

{
  "hooks": {
    "SessionStart": [{ "steps": [{ "hooks": [
      { "type": "command", "command": ".github/muscles/hooks/start.cjs", "timeout": 10 }
    ]}]}]
  }
}

PreToolUse decisions: allow, deny (exit 2), or updatedInput (modify params).

Configuration Patterns

// Safe config access with defaults
function getSetting<T>(key: string, fallback: T): T {
  return vscode.workspace.getConfiguration("myext").get<T>(key, fallback);
}

// Listen for changes
vscode.workspace.onDidChangeConfiguration(e => {
  if (e.affectsConfiguration("myext.feature")) refreshUI();
});

SecretStorage for Tokens

Never store secrets in settings — use context.secrets:

let cachedToken: string | null = null;

export async function initSecrets(ctx: vscode.ExtensionContext) {
  cachedToken = await ctx.secrets.get("myext.token") || null;
  // Migration from settings
  const old = vscode.workspace.getConfiguration("myext").get<string>("token");
  if (old && !cachedToken) {
    await ctx.secrets.store("myext.token", old);
    cachedToken = old;
  }
}

export function getToken(): string | null { return cachedToken; }

Webview Sandbox

Webviews cannot access VS Code APIs directly. Communication via postMessage:

// Extension
webview.postMessage({ type: "update", data });

// Webview
window.addEventListener("message", (e) => {
  if (e.data.type === "update") renderData(e.data.data);
});

// Webview → Extension
vscode.postMessage({ command: "save", payload });

Telemetry Opt-Out

if (vscode.env.isTelemetryEnabled) sendTelemetry(event);

Always check before sending. Respect user settings.

Portability Rules

1. Use vscode.Uri.joinPath() — not string concatenation
2. Use vscode.workspace.fs — not Node fs
3. Use path.posix.join() for URI paths
4. Normalize paths: uri.fsPath for filesystem, uri.toString() for display

Publishing Workflow

1. npm run compile — build
2. npx vsce package --no-dependencies — create VSIX
3. npx vsce publish --packagePath <vsix> — publish

Pre-publish: Verify VSCE_PAT not expired, all tests pass.

Testing: Debug vs Rebuild

Asset Optimization

Problem: Large images inflate extension size.

// Resize to max dimension
const sharp = require('sharp');
await sharp(input).resize(768, 768, { fit: 'inside' }).toFile(output);

the AI assistant extension: 553MB → 33MB (94% reduction).

TDZ in Production Builds

Problem: esbuild minifies + hoists, causing Cannot access 'X' before initialization.

Bad:

const handlers = { click: () => config.value };  // config hoisted below
const config = { value: 42 };

Good:

const config = { value: 42 };  // Define before use
const handlers = { click: () => config.value };

Agent Platform (1.109+)

Agent file (.github/agents/my.agent.md):

---
name: "MyAgent"
description: "Specialized agent"
---
Instructions here.

Chat participant:

vscode.chat.createChatParticipant("myext.agent", async (req, ctx, stream) => {
  stream.markdown("Hello!");
});

Tool registration:

vscode.lm.registerTool("myext-search", {
  async invoke(opts) {
    return new vscode.LanguageModelToolResult([
      new vscode.LanguageModelTextPart(JSON.stringify(results))
    ]);
  }
});

Integration Audit Checklist

Scoring: 45-50 Excellent, 40-44 Good, 35-39 Fair, <35 Needs Work