VSCode拡張機能（TypeScript）の開発環境を作って運用に乗せるまで

背景

VSCodeでカスタムマクロを作りたく、TypeScriptで拡張機能を開発する環境を構築しました。セットアップから日常の更新フローまでをまとめます。

1. 環境構築は3つのグローバルツールから

node --version  # v20以上推奨
npm install -g yo generator-code @vscode/vsce

• yo: Yeoman（プロジェクト生成ツール）
• generator-code: VSCode拡張機能テンプレート
• @vscode/vsce: パッケージ化ツール

2. プロジェクト生成は対話式

mkdir C:\my-local\my-macros
cd C:\my-local\my-macros
git init
git branch -M main

yo code

対話式の選択で「New Extension (TypeScript)」を選ぶと、以下の構成が自動生成されます。

my-macros/
├── .vscode/              # デバッグ設定（launch.json / tasks.json）
├── src/
│   ├── extension.ts      # メインエントリーポイント
│   └── test/
├── package.json          # 拡張機能設定
├── tsconfig.json
└── README.md

3. package.jsonのcontributesが肝

コマンドとキーバインドはここで定義します。

{
  "contributes": {
    "commands": [
      { "command": "myMacros.openPath", "title": "Open Path Under Cursor", "category": "My Macros" }
    ],
    "keybindings": [
      { "command": "myMacros.openPath", "key": "ctrl+shift+f12", "when": "editorTextFocus" }
    ]
  }
}

extension.ts側でコマンドを実処理に紐付けます。

import * as vscode from 'vscode';

export function activate(context: vscode.ExtensionContext) {
  const disposable = vscode.commands.registerCommand(
    'myMacros.openPath',
    () => { vscode.window.showInformationMessage('Hello World!'); }
  );
  context.subscriptions.push(disposable);
}

export function deactivate() {}

4. デバッグはF5、パッケージ化はvsce

開発中はパッケージ化不要で、F5で新しいウィンドウ（Extension Development Host）が起動してすぐテストできます。ログは新ウィンドウでCtrl+Shift+U → 「Extension Host」から確認できます。

本番投入はパッケージ化してインストールします。

vsce package
# my-macros-0.0.1.vsix が生成される

code --install-extension my-macros-0.0.1.vsix

vsce package実行時にWARNING: repository field is missingのような警告が出ますが、個人利用なら無視してyで続行して問題ありません。

5. 日常の更新フロー

# 1. マクロ編集
code src/macros/newMacro.ts

# 2. コンパイル（watchモードなら自動）
npm run watch

# 3. F5でデバッグ実行してテスト

# 4. コミット
git add .
git commit -m "Add new macro: newMacro"

# 5. バージョンアップ→再パッケージ化→再インストール
npm version patch
vsce package
code --install-extension my-macros-0.0.2.vsix

トラブルシューティング

症状	対処
Cannot find module 'vscode'	npm install
npm installが依存関係で失敗	npm install --legacy-peer-deps
拡張機能が認識されない	code --uninstall-extension → 再インストール → VSCode完全再起動

まとめ

TypeScript拡張機能開発は初期セットアップこそ必要ですが、IntelliSenseとコンパイル時エラー検出により、複雑なマクロも安全に育てていけます。キーバインド設計の詳細やJavaScriptとの比較はこちらにまとめています。

→ VSCode TypeScriptマクロ開発環境の完全ガイド（ブログ）