Extension Manifest - package.json | 非公式

全てのVisual Studio Code拡張機能には、拡張機能フォルダのルートにマニフェストファイルpackage.jsonが必要です。

Fields

Name	Required	Type	Details
`name`	Y	`string`	拡張機能の名称です。スペースなしの小文字でなければなりません。
`version`	Y	`string`	SemVerに従います。
`publisher`	Y	`string`	拡張機能の公開者名です。
`engines`	Y	`object`	拡張機能とVS Codeバージョンの互換性です。`vs code`を含む最小バージョンを指定します。`*`を指定することはできません。例: `^0.10.5`を指定したなら`^0.10.5`以降に互換性があることを示します。
`license`		`string`	npm’s documentationを参照してください。ルートに`LICENSE`ファイルを配置した場合は値を`"SEE LICENSE IN <filename>"`にすることを推奨します。
`displayName`		`string`	Marketplaceで使用する拡張機能の表示名です。
`description`		`string`	短くまとめた拡張機能の説明です。
`categories`		`string[]`	拡張機能のカテゴリーを指定します。値は`[Languages, Snippets, Linters, Themes, Debuggers, Formatters, Keymaps, Other, Extension Packs]`を利用可能です。
`keywords`		`array`	検索に役立つKeywordsを指定します。
`galleryBanner`		`object`	アイコンに合うようにMarketplaceのフォーマット(主にバナー)を指定します。詳細は下記を参照してください。
`preview`		`boolean`	MarketplaceのラベルにPreviewフラグを設定します。
`main`		`string`	拡張機能のエントリーポイントを指定します。
`contributes`		`object`	拡張機能のコントリビューションを指定するオブジェクトです。
`activationEvents`		`array`	拡張機能をロードするタイミングを指定します。
`badges`		`array`	Marketplaceのサイドバーに表示するバッジの配列です。例: バッジの画像URLを示す`url`、バッジのリンク先`href`と`description`
`markdown`		`string`	MarketplaceのMarkdownレンタリングエンジンを制御します。`github`(既定)か`standard`のいずれかを指定します。
`dependencies`		`object`	拡張機能に必要なランタイムNode.js依存関係を指定します。npm’s `dependencies`と同じです。
`devDependencies`		`object`	拡張機能に必要なデベロップメントNode.js依存関係を指定します。npm’s `devDependencies`と同じです。
`extensionDependencies`		`array`	拡張機能IDの配列を指定します。VS Code内に指定した拡張機能がなければこれらをインストールします。このIDは常に`${publisher}.${name}`です。例: `vscode.csharp` (編集メモ:Extension Packで主に使用します。
`scripts`		`object`	npm’s `scripts`と同じですがextra VS Code specific fieldsを使用できます。
`icon`		`string`	128x128pxアイコンへのファイルパスを指定します。

またnpm’s package.json referenceを確認してください。

Example

次に完全なpackage.jsonを示します。

{
    "name": "spell",
    "displayName": "Spelling and Grammar Checker",
    "description": "Detect mistakes as you type and suggest fixes - great for Markdown.",
    "icon": "images/spellIcon.svg",
    "version": "0.0.19",
    "publisher": "seanmcbreen",
    "galleryBanner": {
        "color": "#0000FF",
        "theme": "dark"
    },
    "license": "SEE LICENSE IN LICENSE.md",
    "bugs": {
        "url": "https://github.com/Microsoft/vscode-spell-check/issues",
        "email": "smcbreen@microsoft.com"
    },
    "homepage": "https://github.com/Microsoft/vscode-spell-check/blob/master/README.md",
    "repository": {
        "type": "git",
        "url": "https://github.com/Microsoft/vscode-spell-check.git"
    },
    "categories": [
        "Linters", "Languages", "Other"
    ],
    "engines": {
        "vscode": "^1.0.0"
    },
    "main": "./out/extension",
    "activationEvents": [
        "onLanguage:markdown"
    ],
    "contributes": {
        "commands": [
            {
                "command": "Spell.suggestFix",
                "title": "Spell Checker Suggestions"
            }
        ],
        "keybindings": [
            {
                "command": "Spell.suggestFix",
                "key": "Alt+."
            }
        ]
    },
    "badges": [
        {
            "url": "https://david-dm.org/Microsoft/vscode-spell-check.svg",
            "href": "https://david-dm.org/Microsoft/vscode-spell-check",
            "description": "Dependency Status"
        }
    ],
    "scripts": {
        "vscode:prepublish": "tsc -p ./",
        "compile": "tsc -watch -p ./"
    },
    "dependencies": {
        "teacher": "^0.0.1"
    },
    "devDependencies": {
        "vscode": "^1.0.0"
    }
}

Marketplace Presentation Tips

ここではVS Code Marketplaceの見栄えをよくするヒントと推奨事項を説明しています。

常に最新のvsceを使用できるようにnpm install -g vsceを使用してください。

拡張機能のルートフォルダにREADME.mdファイルを置くことで、その内容をMarketplaceの拡張機能ページ本文に含めます。REAMDE.md内では相対パスの画像リンクを使用可能です。

次に例を示します:

適切な表示名と説明を入力します。これはMarketplaceと製品の表示において重要です。これら文字列はVS Codeのテキスト検索にも使用されるため、関連するワードを使用することで多くに役立ちます。

"displayName": "Spelling and Grammar Checker",
"description": "Detect mistakes as you type and suggest fixes - great for Markdown.",

アイコンと対比的なバナーの色は、Marketplaceのヘッダーを綺麗にします。theme属性にはフォントの色darkかlightを指定できます。

"icon": "images/spellIcon.svg",
"galleryBanner": {
    "color": "#5c2d91",
    "theme": "dark"
},

あなたが設定できるオプションリンク(bugs, homepage, repository)があります。これはMarketplaceのResourcesセクション下に表示します。

"license": "SEE LICENSE IN LICENSE.md",
"bugs": {
    "url": "https://github.com/Microsoft/vscode-spell-check/issues"
},
"homepage": "https://github.com/Microsoft/vscode-spell-check/blob/master/README.md",
"repository": {
    "type": "git",
    "url": "https://github.com/Microsoft/vscode-spell-check.git"
}

Marketplace Resources link	package.json attribute
Issues	`bugs:url`
Repository	`repository:url`
Homepage	`homepage`
License	`license`

拡張機能のためにcategoryを指定します。同じcategory内の拡張機能は、Marketplaceで見つけやすいようにタグ分けされます。

Note: あなたの拡張機能にあった値を指定してください。使用できる値は次の通りです。[Languages, Snippets, Linters, Themes, Debuggers, Formatters, Keymaps, Other]

"categories": [
    "Linters", "Languages", "Other"
],

Tip: Extension Manifest Editorを使うと、Marketplaceに公開されたときのREADME.mdとpackage.jsonのメタデータがどのように見えるかをプレビューできます。

Combining Extension Contributions

yo codeジェネレーターを使うとTextMateテーマ、カラライザー、スニペットを簡単にパッケージ化して新しい拡張機能を作成できます。これを実行したとき、ジェネレータはオプションに沿ってそれぞれ完全な独立型の拡張機能パッケージを作成します。しかし、複数のコントリビューションを組み合わせた拡張機能のほうが便利です。たとえば、新しい言語のサポートを追加する場合は、ユーザーにカラライザーとスニペット、さらにはデバッグサポートの両方の言語定義を提供したいと考えると思います。

拡張機能のコントリビューションを結合するには、既存の拡張マニフェストpackage.jsonを編集して、新しいコントリビューションと関連ファイルを追加するだけです。

次は、LaTexの言語定義(言語識別とファイル拡張)、カラライザー(grammar)、スニペットを含む拡張マニフェストです。

{
    "name": "language-latex",
    "description": "LaTex Language Support",
    "version": "0.0.1",
    "publisher": "someone",
    "engines": {
        "vscode": "0.10.x"
    },
    "categories": [
        "Languages",
        "Snippets"
    ],
    "contributes": {
        "languages": [{
            "id": "latex",
            "aliases": ["LaTeX", "latex"],
            "extensions": [".tex"]
        }],
        "grammars": [{
            "language": "latex",
            "scopeName": "text.tex.latex",
            "path": "./syntaxes/latex.tmLanguage"
        }],
        "snippets": [{
            "language": "latex",
            "path": "./snippets/snippets.json"
        }]
    }
}

categories属性がMarketplace上で見つけやすいように、LanguagesとSnippetsの両方を含んでいることに注目してください。

Tip: マージしたコントリビューションが同じ識別子を使用していることを確認してください。上記の例では、言語識別子に”latex”を使用しています。これによりVS Codeは、カラライザー (grammar) とスニペットがLaTeX言語用であり、LaTeXファイルを編集するときにアクティブになることを知ることができます。

Extension Packs

また’Extension Packs’で別の拡張機能を含めることが可能です。Extension Packは、拡張機能を一緒にインストールできるセットのことです。これにより、お気に入りの拡張機能をほかのユーザーと共有したり、PHP開発のような特定シナリオ用の拡張機能セットを作成して、開発の準備を早める手助けできます。

Extension Packは他のコントリビューションを含めることができます。これはpackage.jsonファイル内のextensionDependencies属性を使って表現します。

次の例ではPHP用のExtension Packにデバッガ、言語サービスおよびフォーマッタを含みます:

"extensionDependencies": [
    "felixfbecker.php-debug",
    "felixfbecker.php-intellisense",
    "Kasik96.format-php"
]

これによりExtension Packをインストールすると、VS Codeはその拡張機能の依存関係もインストールするようになりました。

なおExtension PackはExtension Packsのカテゴリーに分類する必要があります。

"categories": [
    "Extension Packs"
],

Extension Packにはyo code Yeoman generatorを使用できます。オプションでVS Codeインスタンスに現在インストールされている拡張機能をパックに含めることも可能です。このように、お気に入りの拡張機能でExtension Packを簡単に作成し、Marketplaceに公開して他のユーザーと共有することができます。

便利なNodeモジュール

VS Code拡張機能の作成に役立つNode.jsモジュールがnpmjsにあります。これらを拡張機能のdependenciesに含めることができます。

vscode-nls - 外部化とローカライズのサポート
vscode-uri - VS Codeとその拡張機能で使用されるURIの実装
jsonc-parser - コメントを無視してJSONを処理する寛容なパーサー
request-light - 軽量のNode.jsリクエストライブラリ（プロキシサポートあり）
vscode-extension-telemetry - VS Code拡張機能のためのテレメトリレポートの統一
vscode-languageclient - language server protocolに準じた言語サーバーを簡単に統合

次のステップ

VS Codeの拡張モデルの詳細については次のトピックを試してください:

Contribution Points - VS Code contribution points reference
Activation Events - VS Code activation events reference
Extension Marketplace - Read more about the VS Code Extension Marketplace