バージョン 2 からの移行

Miniflare v3 は、オープンソースの Cloudflare Workers ランタイム workerd ↗ を使います。これは Cloudflare のネットワーク上にデプロイされているランタイムと同じです。バグ単位で互換になり、挙動のずれはほぼなくなります。詳細は Miniflare v3 ↗ と Wrangler v3 の発表 ↗ を参照してください。

Miniflare v3 にはスタンドアロン CLI が含まれなくなりました。同じ機能を得るには、Wrangler へ切り替える必要があります。Wrangler v3 はデフォルトで Miniflare v3 を使います。ローカル開発サーバーを起動するには、次を実行します。

$ npx wrangler@3 dev

Miniflare CLI にあった機能を Wrangler でも使いたい場合は、GitHub ↗ で issue を開いてください。

可能な範囲では Miniflare v3 の API を Miniflare v2 に近づけています。ただし、オープンソースの workerd ランタイムへの切り替えに伴い、多くのオプションとメソッドが削除または変更されています。新しい API ドキュメントは Getting Started ガイド を参照してください。

• kvNamespaces/r2Buckets/d1Databases

  • これらのオプションは string[] に加え、バインディング名を名前空間 ID / バケット名 / データベース ID へ対応付ける Record<string, string> も受け付けます。複数の Worker が、同じ名前空間 / バケット / データベースに、異なる名前でバインドできます。

• queueBindings

  • queueProducers に改名されました。バインディング名をキュー名へ対応付ける Record<string, string>、または同じ名前のキューへのバインディング名の string[] を受け付けます。

• queueConsumers

  • キュー名をコンシューマーオプションへ対応付ける Record<string, QueueConsumerOptions>、またはデフォルトオプションで消費するキュー名の string[] を受け付けます。QueueConsumerOptions の型は次のとおりです。

    interface QueueConsumerOptions {
    	// /queues/platform/configuration/#consumer
    	maxBatchSize?: number; // default: 5
    	maxBatchTimeout?: number /* seconds */; // default: 1
    	maxRetries?: number; // default: 2
    	deadLetterQueue?: string; // default: none
    }

• cfFetch

  • cf に改名されました。以前と同様に boolean または string を受け付けるほか、受信リクエストの cf オブジェクトとして使うオブジェクトも受け付けます。

• wranglerConfigPath/wranglerConfigEnv

  • Miniflare は Wrangler の設定を扱わなくなりました。Wrangler 設定に基づいて Worker をプログラムから起動するには、unstable_dev() API を使います。

• packagePath

  • Miniflare は package.json ファイルからスクリプトパスを読み込まなくなりました。代わりに scriptPath オプションでスクリプトを指定します。

• watch

  • Miniflare の API は主にテスト用途向けで、ファイル監視は通常不要です。このオプションは、現在は削除された Miniflare CLI を動かすためのものでした。ファイルを監視する必要がある場合は、fs.watch() ↗ や chokidar ↗ などの別のファイルウォッチャーを使い、変更時に元の設定で setOptions() を呼ぶことを検討してください。

• logUnhandledRejections

  • 未処理の拒否は、Workers では addEventListener("unhandledrejection") ↗ で扱えます。

• globals

  • 任意のグローバルの注入は workerd ↗ ではサポートされません。サービスワーカーを使う場合、bindings はグローバルとして注入されますが、JSON シリアライズ可能である必要があります。

• https/httpsKey(Path)/httpsCert(Path)/httpsPfx(Path)/httpsPassphrase

  • Miniflare はまだ HTTPS サーバーの起動に対応していません。これらのオプションは将来のリリースで戻る可能性があります。

• crons

  • workerd ↗ はまだスケジュールイベントのトリガーに対応していません。このオプションは将来のリリースで戻る可能性があります。

• mounts

  • Miniflare には、親 Worker と子 Worker という概念がなくなりました。代わりに、新しい workers オプションで、すべての Worker を同じレベルで定義できます。次の例は、サービスバインディングを使い、共有 KV 名前空間の値をインクリメントします。

    import { Miniflare, Response } from "miniflare";
    
    const message = "The count is ";
    const mf = new Miniflare({
    	// Options shared between Workers such as HTTP and persistence configuration
    	// should always be defined at the top level.
    	host: "0.0.0.0",
    	port: 8787,
    	kvPersist: true,
    
    	workers: [
    		{
    			name: "worker",
    			kvNamespaces: { COUNTS: "counts" },
    			serviceBindings: {
    				INCREMENTER: "incrementer",
    				// Service bindings can also be defined as custom functions, with access
    				// to anything defined outside Miniflare.
    				async CUSTOM(request) {
    					// `request` is the incoming `Request` object.
    					return new Response(message);
    				},
    			},
    			modules: true,
    			script: `export default {
            async fetch(request, env, ctx) {
              // Get the message defined outside
              const response = await env.CUSTOM.fetch("http://host/");
              const message = await response.text();
    
              // Increment the count 3 times
              await env.INCREMENTER.fetch("http://host/");
              await env.INCREMENTER.fetch("http://host/");
              await env.INCREMENTER.fetch("http://host/");
              const count = await env.COUNTS.get("count");
    
              return new Response(message + count);
            }
          }`,
    		},
    		{
    			name: "incrementer",
    			// Note we're using the same `COUNTS` namespace as before, but binding it
    			// to `NUMBERS` instead.
    			kvNamespaces: { NUMBERS: "counts" },
    			// Worker formats can be mixed-and-matched
    			script: `addEventListener("fetch", (event) => {
            event.respondWith(handleRequest());
          })
          async function handleRequest() {
            const count = parseInt((await NUMBERS.get("count")) ?? "0") + 1;
            await NUMBERS.put("count", count.toString());
            return new Response(count.toString());
          }`,
    		},
    	],
    });
    const res = await mf.dispatchFetch("http://localhost");
    console.log(await res.text()); // "The count is 3"
    await mf.dispose();

• metaProvider

  • cf オブジェクトと X-Forwarded-Proto / X-Real-IP ヘッダーは、代わりに dispatchFetch() 呼び出し時に指定できます。デフォルトの cf オブジェクトは、新しい cf オプションでも指定できます。

• durableObjectAlarms

  • Miniflare は常に Durable Object アラームを有効にします。

• globalAsyncIO/globalTimers/globalRandom

  • workerd ↗ は、根本的な変更なしではこれらのオプションをサポートできません。

• actualTime

  • Miniflare は常に現在時刻を返します。

• inaccurateCpu

  • inspectorPort: 9229 オプションを設定して V8 inspector を有効にします。Google Chrome で chrome://inspect を開き、DevTools を開いて CPU プロファイリングを行います。

• setOptions()
  • Miniflare v3 では、部分的なパッチではなく、完全な設定オブジェクトを渡す必要があります。

• reload()
  • 元の設定オブジェクトで setOptions() を呼び、Miniflare を再読み込みします。
• createServer()/startServer()
  • Miniflare は常に、設定した host と port で待ち受ける workerd ↗ サーバーを起動するため、これらのメソッドは不要です。
• dispatchScheduled()/startScheduled()
  • dispatchScheduled の機能は、現在は getWorker() で行えます。詳細は スケジュールイベントのドキュメント を参照してください。
• dispatchQueue()
  • 代わりに、サービスバインディング または キュープロデューサーバインディング の queue() メソッドを使います。
• getGlobalScope()/getBindings()/getModuleExports()
  • これらのメソッドは、Workers サンドボックス内のオブジェクトを返していました。Miniflare は現在 workerd ↗ を使い、別プロセスで動くため、これらのメソッドはサポートできません。
• addEventListener()/removeEventListener()
  • Miniflare は reload イベントを発行しなくなりました。Miniflare はファイルを監視しなくなったため、再読み込みは初期化または setOptions() 呼び出しでのみ発生します。これらの場合、再読み込みはそれぞれ await mf.ready または await mf.setOptions() で待てます。
• Response#waitUntil()
  • workerd ↗ は、waitUntil() したすべての Promise を待つ機能にはまだ対応していません。

• @miniflare/*
  • Miniflare は、単一の miniflare パッケージにまとめられました。