拡張機能のバンドル

Visual Studio Code 拡張機能をバンドルする最初の理由は、VS Code をどのプラットフォームで使用しているユーザーでも確実に動作するようにするためです。バンドルされた拡張機能のみが、github.dev や vscode.dev のような Web 環境の VS Code で使用できます。VS Code がブラウザーで実行されている場合、拡張機能のファイルを1つしか読み込めないため、拡張機能のコードは単一の Web フレンドリーな JavaScript ファイルにバンドルする必要があります。これは ノートブック出力レンダラー にも当てはまります。ここでも VS Code はレンダラー拡張機能のファイルを1つしか読み込みません。

さらに、拡張機能はすぐにサイズと複雑さが増大する可能性があります。複数のソースファイルで作成され、npm のモジュールに依存している場合があります。分解と再利用は開発のベストプラクティスですが、拡張機能のインストールと実行にはコストがかかります。100 個の小さなファイルを読み込むのは、1 つの大きなファイルを読み込むよりもはるかに遅いです。そのため、バンドルすることをお勧めします。バンドルとは、複数の小さなソースファイルを 1 つのファイルに結合するプロセスです。

JavaScript には、さまざまなバンドラーが利用できます。主要なものとして、rollup.js、Parcel、esbuild、および webpack があります。

esbuild の使用

esbuild は、設定が簡単な高速 JavaScript バンドラーです。esbuild を入手するには、ターミナルを開いて次のように入力します。

npm i --save-dev esbuild

esbuild の実行

esbuild はコマンドラインから実行できますが、繰り返しを減らし、問題レポートを有効にするには、ビルドスクリプト esbuild.js を使用すると便利です。

const esbuild = require('esbuild');

const production = process.argv.includes('--production');
const watch = process.argv.includes('--watch');

async function main() {
  const ctx = await esbuild.context({
    entryPoints: ['src/extension.ts'],
    bundle: true,
    format: 'cjs',
    minify: production,
    sourcemap: !production,
    sourcesContent: false,
    platform: 'node',
    outfile: 'dist/extension.js',
    external: ['vscode'],
    logLevel: 'warning',
    plugins: [
      /* add to the end of plugins array */
      esbuildProblemMatcherPlugin
    ]
  });
  if (watch) {
    await ctx.watch();
  } else {
    await ctx.rebuild();
    await ctx.dispose();
  }
}

/**
 * @type {import('esbuild').Plugin}
 */
const esbuildProblemMatcherPlugin = {
  name: 'esbuild-problem-matcher',

  setup(build) {
    build.onStart(() => {
      console.log('[watch] build started');
    });
    build.onEnd(result => {
      result.errors.forEach(({ text, location }) => {
        console.error(`✘ [ERROR] ${text}`);
        if (location == null) return;
        console.error(`    ${location.file}:${location.line}:${location.column}:`);
      });
      console.log('[watch] build finished');
    });
  }
};

main().catch(e => {
  console.error(e);
  process.exit(1);
});

ビルドスクリプトは以下を行います。

• esbuild でビルドコンテキストを作成します。このコンテキストは次のように構成されています。
  • src/extension.ts のコードを dist/extension.js という単一のファイルにバンドルします。
  • --production フラグが渡された場合にコードを圧縮します。
  • --production フラグが渡されない限り、ソースマップを生成します。
  • バンドルから 'vscode' モジュールを除外します (VS Code ランタイムによって提供されるため)。
• バンドラーの完了を妨げたエラーを報告するために、esbuildProblemMatcherPlugin プラグインを使用します。このプラグインは、拡張機能としてインストールする必要がある esbuild 問題マッチャーによって検出される形式でエラーを出力します。
• --watch フラグが渡された場合、ソースファイルの変更を監視し始め、変更が検出されるたびにバンドルを再構築します。

esbuild は TypeScript ファイルを直接扱うことができます。ただし、esbuild は型チェックを行わずにすべての型宣言を単純に削除します。構文エラーのみが報告され、esbuild が失敗する原因となることがあります。

そのため、型をチェックするために TypeScript コンパイラ (tsc) を別途実行しますが、コードは出力しません (--noEmit フラグ)。

package.json の scripts セクションは次のようになります。

"scripts": {
    "compile": "npm run check-types && node esbuild.js",
    "check-types": "tsc --noEmit",
    "watch": "npm-run-all -p watch:*",
    "watch:esbuild": "node esbuild.js --watch",
    "watch:tsc": "tsc --noEmit --watch --project tsconfig.json",
    "vscode:prepublish": "npm run package",
    "package": "npm run check-types && node esbuild.js --production"
}

npm-run-all は、指定されたプレフィックスに一致する名前のスクリプトを並行して実行する Node モジュールです。私たちの場合、watch:esbuild および watch:tsc スクリプトを実行します。package.json の devDependencies セクションに npm-run-all を追加する必要があります。

compile および watch スクリプトは開発用で、ソースマップ付きのバンドルファイルを生成します。package スクリプトは、VS Code のパッケージングおよび公開ツールである vsce によって使用される vscode:prepublish スクリプトによって使用され、拡張機能の公開前に実行されます。esbuild スクリプトに --production フラグを渡すと、コードが圧縮され、小さなバンドルが作成されますが、デバッグが困難になるため、開発中は他のフラグが使用されます。上記のスクリプトを実行するには、ターミナルを開いて npm run watch と入力するか、コマンドパレット (⇧⌘P (Windows、Linux Ctrl+Shift+P)) から **タスク: タスクの実行** を選択します。

.vscode/tasks.json を次のように構成すると、各ウォッチタスクに個別のターミナルが表示されます。

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "watch",
      "dependsOn": ["npm: watch:tsc", "npm: watch:esbuild"],
      "presentation": {
        "reveal": "never"
      },
      "group": {
        "kind": "build",
        "isDefault": true
      }
    },
    {
      "type": "npm",
      "script": "watch:esbuild",
      "group": "build",
      "problemMatcher": "$esbuild-watch",
      "isBackground": true,
      "label": "npm: watch:esbuild",
      "presentation": {
        "group": "watch",
        "reveal": "never"
      }
    },
    {
      "type": "npm",
      "script": "watch:tsc",
      "group": "build",
      "problemMatcher": "$tsc-watch",
      "isBackground": true,
      "label": "npm: watch:tsc",
      "presentation": {
        "group": "watch",
        "reveal": "never"
      }
    }
  ]
}

このウォッチタスクは、問題ビューで問題を報告するためにインストールする必要がある問題マッチング用の拡張機能 connor4312.esbuild-problem-matchers に依存します。この拡張機能は、起動を完了するためにインストールする必要があります。

忘れないように、ワークスペースに .vscode/extensions.json ファイルを追加してください。

{
  "recommendations": ["connor4312.esbuild-problem-matchers"]
}

最後に、コンパイルされたファイルが公開された拡張機能に含まれるように、.vscodeignore ファイルを更新することをお勧めします。詳細については、「公開」セクションを確認してください。

読み続けるには、「テスト」セクションにスキップしてください。

webpack の使用

webpack は、npm から入手できる開発ツールです。webpack とそのコマンドラインインターフェースを入手するには、ターミナルを開いて次のように入力します。

npm i --save-dev webpack webpack-cli

これにより webpack がインストールされ、拡張機能の package.json ファイルが更新され、devDependencies に webpack が含まれるようになります。

webpack は JavaScript バンドラーですが、多くの VS Code 拡張機能は TypeScript で記述されており、JavaScript にコンパイルされるだけです。拡張機能が TypeScript を使用している場合、webpack が TypeScript を理解できるように、ローダー ts-loader を使用できます。ts-loader をインストールするには、次を使用します。

npm i --save-dev ts-loader

すべてのファイルは、webpack-extension サンプルで入手できます。

webpack の構成

すべてのツールがインストールされたら、webpack を構成できます。慣例により、webpack.config.js ファイルには、webpack に拡張機能をバンドルするよう指示する構成が含まれています。以下のサンプル構成は VS Code 拡張機能用であり、良い出発点となるはずです。

//@ts-check

'use strict';

const path = require('path');
const webpack = require('webpack');

/**@type {import('webpack').Configuration}*/
const config = {
  target: 'webworker', // vscode extensions run in webworker context for VS Code web 📖 -> https://webpack.dokyumento.jp/configuration/target/#target

  entry: './src/extension.ts', // the entry point of this extension, 📖 -> https://webpack.dokyumento.jp/configuration/entry-context/
  output: {
    // the bundle is stored in the 'dist' folder (check package.json), 📖 -> https://webpack.dokyumento.jp/configuration/output/
    path: path.resolve(__dirname, 'dist'),
    filename: 'extension.js',
    libraryTarget: 'commonjs2',
    devtoolModuleFilenameTemplate: '../[resource-path]'
  },
  devtool: 'source-map',
  externals: {
    vscode: 'commonjs vscode' // the vscode-module is created on-the-fly and must be excluded. Add other modules that cannot be webpack'ed, 📖 -> https://webpack.dokyumento.jp/configuration/externals/
  },
  resolve: {
    // support reading TypeScript and JavaScript files, 📖 -> https://github.com/TypeStrong/ts-loader
    mainFields: ['browser', 'module', 'main'], // look for `browser` entry point in imported node modules
    extensions: ['.ts', '.js'],
    alias: {
      // provides alternate implementation for node module and source files
    },
    fallback: {
      // Webpack 5 no longer polyfills Node.js core modules automatically.
      // see https://webpack.dokyumento.jp/configuration/resolve/#resolvefallback
      // for the list of Node.js core module polyfills.
    }
  },
  module: {
    rules: [
      {
        test: /\.ts$/,
        exclude: /node_modules/,
        use: [
          {
            loader: 'ts-loader'
          }
        ]
      }
    ]
  }
};
module.exports = config;

このファイルは、webpack-extension サンプルの一部として入手可能です。webpack 構成ファイルは、構成オブジェクトをエクスポートする必要がある通常の JavaScript モジュールです。

上記のサンプルでは、以下が定義されています。

• target は、拡張機能が実行されるコンテキストを示します。VS Code for Web と VS Code デスクトップバージョンの両方で拡張機能が動作するように、webworker の使用をお勧めします。
• webpack が使用するエントリポイント。これは package.json の main プロパティに似ていますが、"出力" エントリポイントではなく、通常 src/extension.ts のような "ソース" エントリポイントを webpack に提供する点が異なります。webpack バンドラーは TypeScript を理解するため、個別の TypeScript コンパイルステップは不要です。
• output 構成は、生成されたバンドルファイルをどこに配置するかを webpack に指示します。慣例により、それは dist フォルダーです。このサンプルでは、webpack は dist/extension.js ファイルを生成します。
• resolve と module/rules の構成は、TypeScript および JavaScript の入力ファイルをサポートするためにあります。
• externals 構成は、除外を宣言するために使用されます。たとえば、バンドルに含めるべきではないファイルやモジュールなどです。vscode モジュールはディスク上に存在せず、必要に応じて VS Code によってその場で作成されるため、バンドルすべきではありません。拡張機能が使用する Node モジュールによっては、より多くの除外が必要になる場合があります。

最後に、コンパイルされたファイルが公開された拡張機能に含まれるように、.vscodeignore ファイルを更新することをお勧めします。詳細については、「公開」セクションを確認してください。

webpack の実行

webpack.config.js ファイルが作成されたら、webpack を呼び出すことができます。webpack はコマンドラインから実行できますが、繰り返しを減らすには npm スクリプトを使用すると便利です。

これらのエントリを package.json の scripts セクションにマージします。

"scripts": {
    "compile": "webpack --mode development",
    "watch": "webpack --mode development --watch",
    "vscode:prepublish": "npm run package",
    "package": "webpack --mode production --devtool hidden-source-map",
},

compile および watch スクリプトは開発用で、バンドルファイルを生成します。vscode:prepublish は、VS Code のパッケージングおよび公開ツールである vsce によって使用され、拡張機能の公開前に実行されます。違いは モード にあり、これは最適化のレベルを制御します。production を使用すると最小のバンドルが得られますが、時間もかかります。それ以外の場合は development が使用されます。上記のスクリプトを実行するには、ターミナルを開いて npm run compile と入力するか、コマンドパレット (⇧⌘P (Windows、Linux Ctrl+Shift+P)) から **タスク: タスクの実行** を選択します。

拡張機能の実行

拡張機能を実行する前に、package.json の main プロパティがバンドルを指すようにする必要があります。上記の構成では、これは "./dist/extension" です。この変更により、拡張機能を実行およびテストできるようになります。

テスト

拡張機能の作成者は、拡張機能のソースコードの単体テストを記述することがよくあります。拡張機能のソースコードがテストに依存しない適切なアーキテクチャレイヤーがあれば、webpack および esbuild によって生成されたバンドルにテストコードが含まれるべきではありません。単体テストを実行するには、簡単なコンパイルのみが必要です。

これらのエントリを package.json の scripts セクションにマージします。

"scripts": {
    "compile-tests": "tsc -p . --outDir out",
    "pretest": "npm run compile-tests",
    "test": "vscode-test"
}

compile-tests スクリプトは、TypeScript コンパイラを使用して拡張機能を out フォルダーにコンパイルします。その中間 JavaScript が利用可能になれば、launch.json の以下のスニペットでテストを実行するのに十分です。

{
  "name": "Extension Tests",
  "type": "extensionHost",
  "request": "launch",
  "runtimeExecutable": "${execPath}",
  "args": [
    "--extensionDevelopmentPath=${workspaceFolder}",
    "--extensionTestsPath=${workspaceFolder}/out/test"
  ],
  "outFiles": ["${workspaceFolder}/out/test/**/*.js"],
  "preLaunchTask": "npm: compile-tests"
}

このテスト実行構成は、バンドルされていない拡張機能と同じです。単体テストは拡張機能の公開部分ではないため、バンドルする理由はありません。

公開

公開する前に、.vscodeignore ファイルを更新する必要があります。現在 dist/extension.js ファイルにバンドルされているものはすべて除外できます。通常は out フォルダー (まだ削除していない場合) と、最も重要な node_modules フォルダーです。

一般的な .vscodeignore ファイルは次のようになります。

.vscode
node_modules
out/
src/
tsconfig.json
webpack.config.js
esbuild.js

既存の拡張機能の移行

既存の拡張機能を esbuild または webpack を使用するように移行するのは簡単で、上記の入門ガイドと似ています。webpack を採用した実際の例は、この プルリクエスト を通じた VS Code の参照ビューです。

そこでは、以下を確認できます。

• esbuild あるいは webpack、webpack-cli、および ts-loader を devDependencies として追加します。
• 上記のようにバンドラーを使用するように npm スクリプトを更新します。
• タスク構成の tasks.json ファイルを更新します。
• esbuild.js または webpack.config.js ビルドファイルを追加および調整します。
• .vscodeignore を更新して node_modules および中間出力ファイルを除外します。
• はるかに高速にインストールおよび読み込みができる拡張機能をお楽しみください！

トラブルシューティング

ミニファイ

production モードでのバンドルは、コードのミニファイも実行します。ミニファイは、空白やコメントを削除し、変数名や関数名を短く、しかし読みにくいものに変更することで、ソースコードをコンパクトにします。Function.prototype.name を使用するソースコードは異なる動作をするため、ミニファイを無効にする必要がある場合があります。

webpack のクリティカルな依存関係

webpack を実行すると、**Critical dependencies: the request of a dependency is an expression** のような警告が表示されることがあります。このような警告は真剣に受け止めるべきであり、バンドルが機能しない可能性があります。このメッセージは、webpack が一部の依存関係をどのようにバンドルするかを静的に判断できないことを意味します。これは通常、動的な require ステートメント (例: require(someDynamicVariable)) によって引き起こされます。

この警告に対処するには、次のいずれかを実行する必要があります。

• バンドルできるように、依存関係を静的にしてみてください。
• externals 構成を介してその依存関係を除外します。また、.vscodeignore で否定の glob パターン を使用して、これらの JavaScript ファイルがパッケージ化された拡張機能から除外されないようにしてください (例: !node_modules/mySpecialModule)。

次のステップ

• 拡張機能マーケットプレイス - VS Code の公開拡張機能マーケットプレイスの詳細をご覧ください。
• 拡張機能のテスト - 高品質を確保するために、拡張機能プロジェクトにテストを追加します。
• 継続的インテグレーション - Azure Pipelines で拡張機能の CI ビルドを実行する方法について学びます。