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

ZIPと設定

管理画面に登録するZIPの構成と、wrangler.jsoncの書き方を説明します。

ZIPの構成​

pnpm buildはdist/plugin.zipを出力します。 ファイルはZIPの最上位に置きます。ZIPの中にdist/の階層は作りません。

plugin.zip
├── wrangler.jsonc   Workerの設定
├── worker.js        バンドル済みのWorker（ESモジュール）
└── assets/          画面を配信する場合の静的ファイル（任意）
    └── index.html   /ext/{組織ID}/index.html として配信される
対象上限
ZIPファイル全体20MB
worker.js10MB
wrangler.jsonc1MB
assets/の1ファイル25MiB
assets/の合計25MiB
assets/のファイル数20,000

次のZIPは登録できません。

  • worker.jsまたはwrangler.jsoncがない
  • /で始まるパス、..を含むパス、バックスラッシュ（\）を含むパスのファイルがある
  • assets/_headersまたはassets/_redirectsがある
備考

Windowsの一部のZIPツールは、パスの区切りにバックスラッシュを使います。 テンプレートのpnpm buildで作成したZIPを登録してください。

wrangler.jsonc​

プラットフォームはZIPに含まれるwrangler.jsoncを読み、Workerをアップロードします。 wrangler.jsoncはJSONC形式で記述でき、コメントと末尾のカンマを使えます。

読み込まれる項目​

項目必須内容
compatibility_date✓互換性の日付。古すぎる日付はCloudflareが拒否します
compatibility_flags互換性フラグ。テンプレートはnodejs_compatを指定しています
durable_objects.bindingsDurable Objectsのバインディング（nameとclass_name）
migrationsDurable Objectsのクラスの追加・改名・削除
r2_buckets組織のR2バケットのバインディング。1つまで宣言でき、bindingだけを読み込みます

durable_objectsとmigrationsの書き方はDurable Objectsを、r2_bucketsの書き方はR2を参照してください。

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "my-plugin",
  "main": "src/index.ts",
  "compatibility_date": "2026-09-01",
  "compatibility_flags": ["nodejs_compat"],

  "durable_objects": {
    "bindings": [{ "name": "ITEM_STORE", "class_name": "ItemStore" }]
  },

  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["ItemStore"] }]
}

name、main、routes、account_id、envなど、上の表にない項目は読み込まれません。 Workerの名前はプラットフォームが決め、エントリーポイントは常にworker.jsです。 環境ごとの設定（env.productionなど）も適用されないため、本番の値は最上位に書いてください。

登録できない項目​

次の項目を宣言したZIPは、登録時に{項目名} is not supported yetのエラーになります。 vars: {}のような空の宣言は、宣言していないものとして扱います。

分類項目
環境変数vars
ストレージd1_databases、kv_namespaces、vectorize、hyperdrive、analytics_engine_datasets
他サービスとの連携services、queues、workflows、pipelines、dispatch_namespaces、send_email、mtls_certificates
その他の機能ai、browser、images、secrets_store_secrets、version_metadata、unsafe、tail_consumers
定期実行triggers（Cron Triggers）
静的ファイルassets.binding

次の宣言も登録できません。

  • durable_objects.bindings[].script_name（他のWorkerのDurable Objectsの参照）
  • 2つ以上のr2_buckets
  • Durable ObjectsとR2で同じバインディング名
警告

これらの項目はpnpm devではエラーになりません。管理画面での登録時に初めてエラーが表示されます。 現在、データの保存に使えるのはDurable ObjectsとR2だけです。 設定値はvarsではなく、コードに定数として書くか、シークレットに登録してください。 定期実行が必要な場合は、Durable ObjectsのAlarmを使ってください。

プラットフォームが注入する値​

アクセストークンの検証に使う値は、登録時にプラットフォームが注入します。 コードからはenvで参照します。

名前内容
PLUGIN_TOKEN_ISSUERトークンの発行者。組織の認証基盤のrealmのURL
PLUGIN_TOKEN_JWKS_URLトークンの署名を検証する公開鍵（JWKS）の取得先
  • wrangler.jsoncには書きません。
  • 値は組織に割り当てられた認証基盤のrealmから作られます。realmが変わった場合は、ZIPを登録し直すまで以前の値のままです。
  • PLUGIN_で始まる名前はプラットフォームが予約しています。バインディングやシークレットの名前に使わないでください。
  • 上の2つのほかに、プラットフォームが内部で使う値も注入されます。コードからは使いません。

wrangler typesはwrangler.jsoncから型を生成するため、注入される値の型は生成されません。 Envの型に手動で追加してください。

src/env.d.ts
declare global {
  interface Env {
    PLUGIN_TOKEN_ISSUER: string
    PLUGIN_TOKEN_JWKS_URL: string
  }
}

export {}

ローカルのpnpm devでは値が注入されません。 .dev.varsに記述するか、--varで指定してください。 .dev.varsはテンプレートの.gitignoreに含まれており、ZIPにも含まれません。

pnpm dev --var PLUGIN_TOKEN_ISSUER:https://... --var PLUGIN_TOKEN_JWKS_URL:https://...

シークレット​

外部APIのキーなどの秘匿情報はwrangler.jsoncやZIPに含めず、管理画面からシークレットとして登録します。 詳しくはシークレットを参照してください。

静的ファイルを配信する​

ZIPのassets/に置いたファイルは、Workers Static Assetsとして配信されます。 独自の画面を提供する場合は、simple-api-with-react-frontendまたはsimple-api-with-vue-frontendテンプレートを使ってください。

配信の設定はプラットフォームが決めます。 wrangler.jsoncのassetsの設定は読み込まれません。 テンプレートのassetsの設定は、ローカルのpnpm devを同じ動作にするためのものです。

設定値動作
html_handlingnone/folderから/folder/への自動リダイレクトなどは行いません
not_found_handlingsingle-page-applicationどのファイルにも一致しないパスにはindex.htmlを返します
run_worker_first["/api/*"]/api/以下へのリクエストだけをWorkerで処理します
警告

assets/を含むZIPを登録すると、Workerに届くのは/api/以下へのリクエストだけになります。 APIのルートはすべて/api/以下に置いてください。 assets/を含まないZIPでは、すべてのパスがWorkerに届きます。

  • 静的ファイルへのリクエストではWorkerが動作しないため、ログは記録されません。
  • 公開URLは/ext/{組織ID}/以下になりますが、ビルド時とWorkerは公開URLを知りません。画面のファイルやAPIは相対パスで参照してください。
  • 画面はmetatell本体と同じオリジンで動作します。localStorageなどのブラウザのストレージはmetatell本体と共有されるため、秘匿情報や個人情報を保存しないでください。

テンプレートは次のように相対パスを使っています。

  • index.htmlが開かれたパスから画面のルートを求め、<base>に設定する
  • Viteのbaseを./にしてビルドする
  • APIをfetch('./api/...')で呼び出す
に最終更新