Visual Studio Code (VSCode) の拡張機能開発において、package.jsonは拡張機能の中核をなすマニフェストファイルです。このファイルには拡張機能の名前やバージョン、動作条件、提供するコマンドや設定情報など、拡張機能の全体設計に関わる重要な情報が記述されます。
この記事では、package.jsonの主要な内容を網羅的に解説し、理解しやすいように表や具体例を交えて説明します。
package.jsonは、拡張機能の「メタ情報」と「機能提供内容」をVSCodeに伝えるための中心ファイルです。
VSCodeはこのファイルをもとに拡張機能の読み込みタイミングやUIの統合、機能呼び出しを管理します。
| フィールド名 | 必須/任意 | 型 | 内容・役割 |
|---|---|---|---|
| name | 必須 | 文字列 | 拡張機能の一意の識別名（全小文字・スペース禁止推奨） |
| displayName | 任意 | 文字列 | マーケットプレイスなどで表示される名称 |
| version | 必須 | 文字列 | セマンティックバージョニングでのバージョン番号（例: 0.1.0） |
| publisher | 必須 | 文字列 | 発行者ID（マーケットプレイス登録名） |
| description | 任意 | 文字列 | 拡張機能の短い説明文 |
| engines | 必須 | オブジェクト | 使用可能なVSCodeのバージョン指定 |
| activationEvents | 必須 | 配列 | 拡張機能の有効化（起動）トリガー |
| main / browser | 任意（どちらか） | 文字列 | 拡張機能のエントリーポイントとなるファイルのパス |
| contributes | 任意 | オブジェクト | 拡張機能がVSCodeに提供するコマンドや設定、UI要素の定義 |
| scripts | 任意 | オブジェクト | NPMスクリプト定義（ビルド、テストなど） |
| dependencies / devDependencies | 任意 | オブジェクト | 拡張機能の動作や開発に必要なnpmモジュールの一覧 |
| categories | 任意 | 配列 | マーケットプレイスでのカテゴリ分類 |
| icon | 任意 | 文字列 | 拡張機能アイコンのパス（128x128px以上推奨） |
| license | 任意 | 文字列 | ライセンス識別子またはファイル |
| repository / bugs / homepage | 任意 | 文字列 | ソースコード管理URL、バグ報告URL、ホームページURL |
このフィールドは拡張機能を「いつ」起動させるかを定義します。パフォーマンス最適化のために重要な設定です。
| activationEventsの種類 | 説明 | 例 |
|---|---|---|
| onCommand:<commandId> | 特定コマンド実行時に有効化 | onCommand:extension.helloWorld |
| onLanguage:<languageId> | 特定言語ファイルを開いたときに有効化 | onLanguage:javascript |
| onView:<viewId> | 特定のビュー表示時に有効化 | onView:myCustomView |
| workspaceContains:<file> | ワークスペースに特定ファイルがある場合に有効化 | workspaceContains:.eslintrc |
| onStartupFinished | VSCode起動完了時に有効化 | onStartupFinished |
contributesは拡張機能がVSCodeに「何を提供するか」を記述する重要な構造体です。
| contributesの種類 | 内容説明 | 具体例 |
|---|---|---|
| commands | 拡張機能が提供するコマンド（コマンドIDと表示名） | コマンドパレットで呼び出せる処理の登録 |
| menus | コマンドを配置するメニュー | エディタ右クリック、タイトルバー、コンテキストメニューなど |
| configuration | 拡張機能のユーザー設定用オプション | settings.jsonに表示される設定項目 |
| languages | 新たに対応する言語定義 | シンタックスハイライトやコード補完の対応言語 |
| snippets | コードスニペット | 登録済みのコードテンプレート |
| keybindings | コマンドに割り当てるショートカットキー | ユーザーが使うキーボードショートカット |
| views / viewsContainers | サイドバーなどの独自ビュー追加 | プロジェクト固有のツリー表示など |
{
"name": "myextension",
"displayName": "My Extension",
"description": "This is a sample VSCode extension",
"version": "0.1.0",
"publisher": "myPublisher",
"engines": {
"vscode": "^1.78.0"
},
"activationEvents": [
"onLanguage:javascript",
"onCommand:myextension.helloWorld"
],
"main": "./out/extension.js",
"contributes": {
"commands": [
{
"command": "myextension.helloWorld",
"title": "Hello World"
}
],
"configuration": {
"type": "object",
"title": "My Extension Settings",
"properties": {
"myextension.enableFeature": {
"type": "boolean",
"default": true,
"description": "Enable the feature"
}
}
}
},
"scripts": {
"compile": "tsc -p ./",
"watch": "tsc -w -p ./"
},
"dependencies": {},
"devDependencies": {
"typescript": "^4.8.0",
"vscode": "^1.78.0"
},
"categories": ["Other"],
"icon": "images/icon.png",
"license": "MIT",
"repository": {
"type": "git",
"url": "https://github.com/myPublisher/myextension.git"
}
}activationEventsは拡張機能のパフォーマンスに直結するため、必要最低限に絞る。contributesでユーザーに提供する機能や設定が明確にわかるように丁寧に定義。engines.vscodeは必ず使うVSCodeの最低バージョンを指定し、互換性を保つ。scriptsはビルドやテストの自動化に有効活用。VSCode拡張機能のpackage.jsonは、単なる設定ファイルにとどまらず、拡張機能の識別・動作・提供機能を司る重要なファイルです。構造や主要フィールドを理解し正しく記述することで、安定した動作と良好なユーザー体験を実現できます。初めての開発でもこの記事の内容を参考に段階的に理解を深めることをおすすめします。
さらに詳細な情報はVSCode公式ドキュメントや最新の開発ガイドが役立ちます。