はじめに

VSCodeでカスタムマクロを作成したいけど、どうやって開発環境を構築すればいいか分からない。そんな悩みを持つ方に向けて、TypeScriptでVSCode拡張機能を開発する環境の構築から、実際にマクロを作成して使えるようにするまでの完全手順を解説します。

本記事では、初心者でも迷わずセットアップできるよう、コマンド一つひとつを丁寧に説明します。

この記事で分かること

• TypeScript拡張機能開発環境の構築手順
• プロジェクト構成とファイル配置
• デバッグ実行からインストールまでの流れ
• TypeScript vs JavaScript の比較
• 効果的な開発ワークフロー
• おすすめキーバインド設定
• トラブルシューティング

なぜTypeScriptなのか？

TypeScriptのメリット

1. IntelliSenseが完璧に機能

editor.document.  // ← すべてのメソッドが補完される

2. エラーを実行前に発見

line.text.toUppercase();  // ← 赤波線で即座にエラー検出
// 正しくは toUpperCase()

3. VSCode APIの型定義が充実

// 引数・戻り値の型が明確
function openFile(filePath: string, readOnly: boolean): Promise

4. リファクタリングが安全

• 関数名変更 → すべての呼び出し箇所も自動更新
• タイポによるバグを防止

JavaScriptとの比較

結論：VSCode拡張機能開発ではTypeScript一択

前提条件

必要な環境

• Windows 10/11（Mac/Linuxでも可）
• Node.js v20以上
• VSCode最新版
• Git（バージョン管理用）

推奨スキル

• 基本的なコマンドライン操作
• TypeScript または JavaScriptの基礎知識
• Gitの基本操作

セットアップ手順（完全版）

Step 1: Node.js環境の確認

# バージョン確認
node --version  # v20.x.x以上
npm --version   # 10.x.x以上

# 未インストールの場合
# https://nodejs.org/ からダウンロード

Step 2: 開発ツールのインストール

# グローバルツールをまとめてインストール
npm install -g yo generator-code @vscode/vsce

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

Step 3: プロジェクトディレクトリの作成

# 作業ディレクトリを作成
mkdir C:\my-local\my-macros
cd C:\my-local\my-macros

# Gitリポジトリ初期化
git init
git branch -M main

Step 4: 拡張機能プロジェクトの生成

yo code

対話式設定項目：

? What type of extension do you want to create?
  → New Extension (TypeScript)

? What's the name of your extension?
  → my-macros

? What's the identifier of your extension?
  → my-macros

? What's the description of your extension?
  → Custom macros for productivity

? Initialize a git repository?
  → No（既に初期化済み）

? Which package manager to use?
  → npm

Step 5: プロジェクト構造の確認

C:\my-local\my-macros\
├── .vscode\              # VSCodeデバッグ設定
│   ├── launch.json
│   └── tasks.json
├── src\
│   ├── extension.ts      # メインエントリーポイント
│   └── test\             # テストコード
├── node_modules\         # 依存パッケージ
├── .gitignore
├── package.json          # 拡張機能設定
├── tsconfig.json         # TypeScript設定
└── README.md

Step 6: マクロディレクトリの作成

mkdir src\macros

Step 7: 依存関係のインストール

npm install --legacy-peer-deps

エラーが出た場合：

# package.jsonの依存関係を最新版に更新してから
npm install --legacy-peer-deps

Step 8: コンパイル確認

npm run compile

# 成功すれば out/ ディレクトリに .js ファイルが生成される

プロジェクト構成の詳細

package.json（拡張機能の設定）

重要なセクション：

{
  "name": "my-macros",
  "displayName": "My Macros",
  "version": "0.0.1",
  "engines": {
    "vscode": "^1.85.0"
  },
  "contributes": {
    "commands": [
      {
        "command": "myMacros.openPath",
        "title": "Open Path Under Cursor",
        "category": "My Macros"
      }
    ],
    "keybindings": [
      {
        "command": "myMacros.openPath",
        "key": "ctrl+shift+f12",
        "when": "editorTextFocus"
      }
    ]
  }
}

カスタマイズポイント：

• commands: コマンドパレットに表示されるコマンド
• keybindings: デフォルトのキーバインド
• when: キーが有効になる条件

extension.ts（メインファイル）

import * as vscode from 'vscode';

export function activate(context: vscode.ExtensionContext) {
    console.log('my-macros is now active');

    // コマンド登録
    const disposable = vscode.commands.registerCommand(
        'myMacros.openPath',
        () => {
            vscode.window.showInformationMessage('Hello World!');
        }
    );

    context.subscriptions.push(disposable);
}

export function deactivate() {}

マクロファイルの配置

src\macros\
├── openPath.ts           # パスオープン
├── copyToEmptyLine.ts    # 空行までコピー
├── textCalc.ts           # テキスト電卓
└── getFileDate.ts        # ファイル更新日時取得

各マクロは独立したファイルで管理し、extension.tsでインポートします。

開発からインストールまでの流れ

開発フロー全体像

1. コード編集
   ↓
2. コンパイル
   ↓
3. デバッグ実行
   ↓
4. テスト
   ↓
5. 問題なし？
   ↓ Yes
6. Gitコミット
   ↓
7. パッケージ化
   ↓
8. インストール
   ↓
9. 本番環境で使用

デバッグ実行（開発中のテスト）

手順：

1. VSCodeでC:\my-local\my-macrosを開く
2. F5キーを押す
3. 新しいVSCodeウィンドウが開く（Extension Development Host）
4. この新しいウィンドウでマクロをテスト

テスト例：

1. 新しいウィンドウでtest.txtを作成
2. C:\Windows\System32 と入力
3. その行でCtrl+Shift+F12を押す
4. Explorerが開けば成功！

デバッグのメリット：

• パッケージ化不要
• 即座にテスト可能
• console.logでログ確認

ログの確認方法：

新しいウィンドウで：
Ctrl+Shift+U → "Extension Host" を選択

パッケージ化（本番用）

# 元のVSCode（開発用）のターミナルで
vsce package

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

警告が出る場合：

WARNING: repository field is missing
WARNING: LICENSE not found

→ 個人利用なら無視してOK（yで続行）

インストール

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

VSCode再起動後、全環境で使用可能に！

効果的な開発ワークフロー

watch モードの活用

# ファイル変更を自動検知してコンパイル
npm run watch

別ターミナルで実行しておけば、ファイル保存時に自動コンパイルされます。

バージョン管理

# パッチバージョンアップ（0.0.1 → 0.0.2）
npm version patch

# マイナーバージョンアップ（0.0.2 → 0.1.0）
npm version minor

# メジャーバージョンアップ（0.1.0 → 1.0.0）
npm version major

日常的な更新フロー

# 1. マクロファイル編集
code src/macros/openPath.ts

# 2. 自動コンパイル（watchモード使用時）

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

# 4. 問題なければコミット
git add .
git commit -m "Fix: improve openPath functionality"

# 5. バージョンアップ
npm version patch

# 6. 再パッケージ化
vsce package

# 7. 再インストール
code --install-extension my-macros-0.0.2.vsix

# 8. VSCode再起動

キーバインド設計

設定場所の使い分け

package.json（拡張機能内）：

• 変更頻度が低いデフォルト設定
• 他のユーザーと共有する設定

keybindings.json（ユーザー設定）：

• 個人の好みに合わせたカスタマイズ
• いつでも変更可能

おすすめキー設定

競合しにくいキー：

{
  "keybindings": [
    // Ctrl+Alt+[文字]（比較的空いている）
    {
      "command": "myMacros.copyToEmptyLine",
      "key": "ctrl+alt+e"
    },
    
    // 2段階キー（VSCodeスタイル）
    {
      "command": "myMacros.openPath",
      "key": "ctrl+k ctrl+o"
    },
    
    // Ctrl+Shift+Alt+[文字]（ほぼ確実に空いている）
    {
      "command": "myMacros.textCalc",
      "key": "ctrl+shift+alt+c"
    }
  ]
}

when句による条件分岐

{
  "key": "ctrl+t",
  "command": "myMacros.textCalc",
  "when": "editorTextFocus && !terminalFocus"
}

主なwhen条件：

• editorTextFocus: エディタにフォーカス
• terminalFocus: ターミナルにフォーカス
• !condition: 条件の否定
• condition1 && condition2: AND条件

メリット・デメリット

メリット

1. 型安全な開発

• コンパイル時エラー検出
• IntelliSenseによる補完
• リファクタリングが安全

2. VSCode公式推奨

• サンプルコードがすべてTypeScript
• ドキュメントが充実
• コミュニティが活発

3. 保守性の高さ

• コードの可読性向上
• バグの早期発見
• チーム開発に適している

4. Git管理

• バージョン履歴を残せる
• 複数PC間で同期
• チーム共有が容易

デメリット

1. 初期セットアップに時間

• 環境構築が必要
• 学習コストがある（ただしJava経験者なら低い）

2. コンパイルが必要

• npm run compileを実行する必要
• ただしwatchモードで自動化可能

3. パッケージ化の手間

• 更新のたびに再パッケージ化
• ただし開発中はF5デバッグで回避可能

総評

デメリットを上回るメリットがある

特に、エディタの補完機能だけで開発効率が10倍変わります。

トラブルシューティング

コンパイルエラー

エラー: Cannot find module 'vscode'

npm install

型エラー: 'lines' has type 'any[]'

// 修正前
const lines = [];

// 修正後
const lines: string[] = [];

インストールエラー

npm install失敗

# 依存関係の競合を回避
npm install --legacy-peer-deps

# または package-lock.json を削除して再実行
rm package-lock.json
npm install --legacy-peer-deps

拡張機能が認識されない

# 拡張機能一覧を確認
code --list-extensions

# 再インストール
code --uninstall-extension your-name.my-macros
code --install-extension my-macros-0.0.1.vsix

# VSCode完全再起動

デバッグ方法

console.logの確認：

export function openPath() {
    console.log('openPath called');
    // ...
}

F5で新しいウィンドウを開く
↓
Ctrl+Shift+U → "Extension Host"
↓
ログが表示される

効果的な使い方

Keyboard Macro Betaとの併用

使い分け：

• 簡単な操作記録 → Keyboard Macro Beta
• 複雑なロジック → TypeScript実装

共存設定：

// keybindings.json
[
    // Keyboard Macro Beta
    {
        "key": "ctrl+alt+r",
        "command": "kb-macro.startRecording"
    },
    
    // TypeScript実装マクロ
    {
        "key": "ctrl+shift+f12",
        "command": "myMacros.openPath"
    }
]

VSCode標準機能との組み合わせ

例：マルチカーソル + カスタムマクロ

1. Alt+クリックで複数カーソル配置
2. カスタムマクロ実行
3. → すべての位置で一括処理

ワークスペース固有の設定

// .vscode/settings.json（プロジェクトごと）
{
    "myMacros.customPath": "${workspaceFolder}/custom"
}

次のステップ

より高度な機能の実装

• ファイル監視
• 外部APIとの連携
• UIコンポーネントの表示
• 設定画面の追加

チーム展開

# リポジトリ公開
git remote add origin https://github.com/YOUR_USERNAME/my-macros.git
git push -u origin main

# チームメンバーは
git clone https://github.com/YOUR_USERNAME/my-macros.git
cd my-macros
npm install --legacy-peer-deps
vsce package
code --install-extension my-macros-0.0.1.vsix

まとめ

VSCode TypeScriptマクロ開発環境の構築は、初期投資こそ必要ですが、一度セットアップすれば：

得られるメリット：

• 型安全な開発環境
• 完璧なIntelliSense
• Git管理による履歴保持
• 柔軟なカスタマイズ

こんな人におすすめ：

• VSCodeのヘビーユーザー
• 効率化マニア
• TypeScript/JavaScript経験者
• Git管理したい

次は実際に作成したマクロの実装例を紹介します！

関連記事

移行の経緯と環境構築

サクラエディタからVSCodeへマクロ移行！快適開発環境の構築記録

はじめに長年愛用してきたサクラエディタのマクロ機能。便利なJavaScript/VBSマクロを多数作成して日常業務で活用してきましたが、最近のAWS開発やブログ執筆でVSCodeを使う機会が増えてきました。「VSCodeでもサクラエディタの...

caymezon.com

2026.01.25

生産性を上げるキー操作

VSCode標準ショートカットキー完全ガイド【日本語解説・おすすめ付き】

はじめにVSCodeを使いこなすには、ショートカットキーの習得が必須です。しかし、VSCodeの標準ショートカット一覧は英語表記で分かりにくいのが難点。本記事では、VSCodeの標準ショートカットキーをカテゴリ別に日本語化し、特に重要なもの...

caymezon.com

2026.01.25

タグ: #VSCode #TypeScript #拡張機能開発 #マクロ #開発環境 #生産性向上

The post VSCode TypeScriptマクロ開発環境の完全ガイド【セットアップから運用まで】 first appeared on CayTech Lab.