WSI プラグイン開発ガイド

🚀5分で始める#

最小のプラグインは 2ファイル（plugin.json と main.js）だけで動きます。 ここでは example.com を開くと右下に 👋 ボタンを表示する「Hello World」を作ってみましょう。

Step 1. フォルダを作る

mkdir my-first-plugin
cd my-first-plugin

Step 2. plugin.json を作る

プラグイン定義ファイル。ID・対象ドメイン・エントリースクリプトを指定します。

{
  "id": "my-first-plugin",
  "name": "My First Plugin",
  "version": "1.0.0",
  "description": "初めてのWSIプラグイン",
  "domains": ["example.com"],
  "scripts": { "main": "main.js" }
}

Step 3. main.js を作る

プラグイン本体。WSI オブジェクト経由で拡張機能のAPIにアクセスします。

WSI.addButton({
  text: '👋',
  position: 'bottom-right',
  onClick: () => {
    alert('Hello from WSI!');
  },
});

WSI.log('プラグインが読み込まれました');

Step 4. ZIPにまとめる

2ファイルを ZIP 圧縮します。フォルダを圧縮するのではなく、ファイルを選択して圧縮してください（plugin.json が ZIP のルートに来る必要があります）。

Step 5. WSIにインポート

1. Chrome で chrome://extensions を開き、WSI が読み込まれていることを確認
2. WSI アイコンをクリックしてポップアップを開く
3. 「プラグインを追加」をクリック
4. 作った ZIP ファイルをドラッグ＆ドロップ
5. プレビュー内容を確認して「インポート」
6. https://example.com を開く → 右下に 👋 ボタンが出たら成功 🎉

📦プラグインの構造#

WSI プラグインは以下の最大3ファイルで構成されます。

my-plugin.zip
├── plugin.json    # 必須: プラグイン定義
├── main.js        # 必須: プラグイン本体
└── style.css      # 任意: CSS（複数可）

plugin.json のフィールド

main.js の実行環境

プラグインコードは対象ページの メインワールド（ページ自身のJSと同じ実行コンテキスト）で実行されます。 つまり window, document, localStorage など、ページ側の全APIにアクセス可能です。

ただし chrome.* 拡張機能APIは直接使えません。 これは WSI がセキュリティのため意図的に切っているもので、代わりに必要な機能は WSI.* SDK 経由で提供されます。

🧰SDK リファレンス#

プラグインコードには WSI という引数でSDKオブジェクトが渡されます。以下のAPIが利用可能です。

WSI.addButton({
  text: 'Say Hi',
  icon: '👋',
  position: 'bottom-right',
  onClick: () => alert('Hi!'),
});

const panel = WSI.addPanel({
  title: '設定',
  width: '320px',
  position: 'right',
  content: '<p>ここに内容</p>',
  onClose: () => console.log('panel closed'),
});

// 保存
await WSI.storage.set('userName', '山田太郎');

// 取得
const name = await WSI.storage.get('userName');

// 全件取得（プラグインのストレージ全体）
const all = await WSI.storage.getAll();

// 削除
await WSI.storage.remove('userName');

{
  ok: boolean,         // HTTP 2xx なら true
  status: number,      // HTTPステータスコード
  url: string,         // リダイレクト後の最終URL
  redirected: boolean, // リダイレクトが発生したか
  body: string,        // レスポンスボディ（HEAD時は空文字列）
}

{ error: string, ok: false, status: 0 }

const res = await WSI.fetch(
  'https://jisho.org/api/v1/search/words?keyword=猫',
  { method: 'GET' }
);

if (res.ok) {
  const data = JSON.parse(res.body);
  console.log(data);
} else {
  console.error('fetch error', res.error || res.status);
}

WSI.onPageLoad((url) => {
  WSI.log(`ナビゲーション: ${url}`);
  // 再初期化処理
});

{
  "id": "my-plugin",
  "config": {
    "message": "こんにちは",
    "color": "#4688F1"
  }
}

const config = WSI.getConfig();
console.log(config.message); // "こんにちは"
console.log(config.color);   // "#4688F1"

WSI.log('プラグイン起動');
// コンソール出力: [WSI:my-plugin] プラグイン起動

🎯ドメインマッチング#

domains 配列に書いたパターンのどれかに一致するドメインで、プラグインが実行されます。

複数パターンの組み合わせ

{
  "domains": [
    "qiita.com",
    "*.qiita.com",
    "zenn.dev",
    "*.hatena.ne.jp"
  ]
}

⚙️設定 (config)#

plugin.json の config フィールドは任意のJSONオブジェクトです。 プラグイン内から WSI.getConfig() で取得し、振る舞いを変えられる仕組みに使えます。

典型的な使い方

{
  "id": "highlighter",
  "config": {
    "color": "#fff59d",
    "buttonPosition": "bottom-left",
    "maxHighlightsPerPage": 100
  }
}

const config = WSI.getConfig();
const color = config.color || '#fff59d';               // デフォルト値
const buttonPosition = config.buttonPosition || 'bottom-right';
const maxHighlights = config.maxHighlightsPerPage ?? 50;

📦パッケージング#

プラグインは ZIP形式で WSI にインポートします。ZIP の作り方をOS別・方法別にまとめます。

Windows (エクスプローラ)

1. plugin.json, main.js, style.css を選択
2. 右クリック → 「送る」→「圧縮 (zip 形式) フォルダー」
3. できた .zip ファイル名を任意のものに変更

macOS / Linux (コマンドライン)

cd my-plugin
zip ../my-plugin.zip plugin.json main.js style.css

Windows PowerShell

Compress-Archive -Path plugin.json, main.js, style.css -DestinationPath my-plugin.zip

Node.js (jszip) で自動化

開発が加速してくると、スクリプトでZIPを作るのが便利です。WSI リポジトリのサンプル ZIP もこの方式で作っています。

const fs = require('fs');
const JSZip = require('jszip');

const zip = new JSZip();
['plugin.json', 'main.js', 'style.css'].forEach((f) => {
  zip.file(f, fs.readFileSync(f));
});

zip.generateAsync({ type: 'nodebuffer' }).then((buf) => {
  fs.writeFileSync('my-plugin.zip', buf);
  console.log('ZIP built:', buf.length, 'bytes');
});

バージョニングのルール

ZIPを再作成するたびに plugin.json の version をインクリメントしましょう。

🎨サンプルギャラリー#

公式サンプル 6 個は、それぞれ異なる WSI SDK 機能を学べるよう設計されています。 ZIPをインポートすればすぐ動きます。ソースコードは各カードから GitHub で読めます。

📂 GitHub でリポジトリを開く

🔍デバッグ#

プラグインコードのログを見る

対象ページで F12 で DevTools を開き「Console」タブ。 WSI.log() の出力は [WSI:your-plugin-id] プレフィックス付きで表示されます。

ストレージの中身を確認する

1. chrome://extensions を開く
2. WSI の詳細 → 「Service Worker」リンクをクリック → DevTools が開く
3. Console で以下を実行:

// 全ストレージを表示
chrome.storage.local.get(null, console.log);

// 特定プラグインのデータ
chrome.storage.local.get('pluginData_my-plugin', console.log);

// ボタン位置キャッシュ
chrome.storage.local.get('wsiButtonPositions', console.log);

よくあるエラー

✨ベストプラクティス#

DO

• 1プラグイン = 1機能 に絞る（テストしやすく、再利用しやすい）
• 設定値は config へ（色、閾値、セレクタなどはハードコードしない）
• エラーは try-catch で握りつぶさない（WSI.logで見えるようにする）
• CSSクラスにプラグインID等のプレフィックスをつける（.wsi-xxxxx-）。ページ側のCSSと衝突しないよう
• innerHTML に入れる前にエスケープ（XSSを防ぐ）
• storage キーに location.pathname を含める（URL別の状態管理）
• ZIP再作成時に version をバンプ（何が変わったか追跡できる）

DON'T

• chrome.* API を直接呼ぼうとしない（メインワールドからは使えない）
• ページのグローバル変数を書き換えない（window.$ 等との衝突要因）
• 永続化なしの重いDOM計算を onPageLoad で毎回（キャッシュする）
• 外部ライブラリをCDNから動的 <script> 読み込み（Manifest V3 のリモートコード禁止ルールに抵触する可能性。ZIPに同梱すべき）
• signalhigh-frequencyなイベント（scroll/mousemove）にデバウンスなしリスナ（パフォーマンス劣化）