メインコンテンツまでスキップ

はじめに

ワーカープラグインは、組織ごとに1つのサーバー側プログラムをmetatellのプラットフォーム上で動かす仕組みです。 プログラムはCloudflare Workersとして実行されます。 組織管理者が管理画面からZIPファイルを登録すると動作します。

ブラウザで動くプラグインだけでは、データの保存、秘匿情報の保持、外部システムとの連携ができません。 ワーカープラグインを使うと、これらをサーバー側で実装できます。

📦 GitHubリポジトリ（テンプレート・サンプル）: https://github.com/urth-inc/metatell-plugins/tree/develop/worker-plugins

できること​

  • APIを提供し、プラグインや外部のシステムから呼び出す
  • Durable Objectsにデータを、R2にファイルを保存する
  • WebSocketで参加者へ更新をリアルタイムに配信する
  • 外部APIのキーをシークレットとして保持し、外部サービスと連携する
  • HTMLやJavaScriptなどの静的ファイルを配信し、独自の画面を提供する

プラグインとの違い​

項目プラグインワーカープラグイン
実行場所参加者のブラウザCloudflare Workers（サーバー側）
成果物Module Federationのリモートバンドル済みのWorker（worker.js）とwrangler.jsonc
登録先管理画面の「プラグイン一覧」管理画面の「ワーカープラグイン」
登録の単位プラグインごとに登録し、ルームに適用する1組織につき1つ

両者はビルドの方法と登録の手順が異なります。 UIが必要な機能は、プラグインからワーカープラグインのAPIを呼び出す形で実装します。

仕組み​

  • ワーカープラグインは独自のURLを持たず、ディスパッチャ経由でのみ呼び出されます。
  • 公開URLはhttps://{組織ID}.metatell.app/ext/{組織ID}/です。組織のカスタムドメインでも配信されます。
  • ディスパッチャはパスの先頭の/ext/{組織ID}を除いてから転送します。コードは自身がルートを持つ前提で書けます。
  • 1組織につき登録できるワーカープラグインは1つです。複数の機能が必要な場合は、1つのWorkerの中にまとめて実装します。
  • 開発者がCloudflareのアカウントを用意する必要はありません。wrangler deployは使わず、ビルドしたZIPを管理画面から登録します。

前提条件​

  • Node.js 24
  • 組織管理者の権限（ワーカープラグインの登録に必要）

テンプレート​

テンプレート名主な内容使う場面
minimalヘルスチェック用のルート、TypeScriptの設定、ZIPを作るビルド最小の構成から始めたい
simple-api-with-durable-objectsDurable Objectsを使うCRUD APIとカウンター、スキーマの移行データを保存したい
simple-api-with-token-verificationJWKSによるアクセストークンの検証呼び出し元の利用者を確認したい
simple-api-with-react-frontendReactとViteで作った画面の配信と、画面から呼ぶAPI独自の画面をReactで提供したい
simple-api-with-vue-frontendVueで作った画面の配信と、画面から呼ぶAPI独自の画面をVueで提供したい

このガイドの構成​

  1. クイックスタート — テンプレートの複製から登録、動作確認まで
  2. ZIPと設定 — ZIPの構成、wrangler.jsonc、プラットフォームが注入する値、シークレット、静的ファイル
  3. 認証と呼び出し — アクセストークンの検証、プラグインからの呼び出し、WebSocket
  4. Durable Objects — データの保存、スキーマの移行、更新時のデータの扱い
  5. R2 — ファイルの保存、バケットの作成
  6. シークレット — 外部APIのキーなどの秘匿情報の扱い
  7. ログ — ログの出力と確認
  8. 制限事項 — 実行時間の上限、レート制限、応答の扱い、ディスパッチャのエラー

管理画面での操作は、ワーカープラグイン管理を参照してください。

に最終更新