studio-config-option-lifecycle

Studio 設定オプションのライフサイクル

Studio に関連するすべてのオプションについて、再読み込み時の動作を明確にします。設定ファイルは変更されるとリセットされ、再実行されますが、コンシューマーが新しい値を認識するのは、そのコードがオプションを再度読み取った場合に限られます。

オプション全体を分類する

Studio のすべてのコンシューマーを調べ、オプション全体に適用するライフサイクルを割り当てます。

• 起動時に固定： 値を変更するには、サーバー、コンパイラー、ウォッチャー、ディレクトリマッピング、またはその他の初期化済みリソースを再作成する必要があります。
• 再読み込み可能： ブラウザーの再読み込み後、または意図的に設定した別のリクエスト境界で、Studio のすべてのコンシューマーが新しい値を安全に使用できます。

いずれかのコンシューマーで起動時に固定する必要がある場合は、Studio のすべてのコンシューマーでそのオプションを起動時に固定します。ライフサイクルを混在させないでください。

Config.set*() の状態が更新されていることを理由に、再読み込み可能だと判断しないでください。設定の再実行によってモジュールの状態は更新されますが、すでに作成済みのコンシューマーがその変更を認識するとは限りません。

起動時に固定する値を渡す

packages/cli/src/studio.ts で startStudio() を呼び出す前に、オプションを一度だけ解決します。

const fixedValue = option.getValue({commandLine: parsedCli}).value;

await StudioServerInternals.startStudio({
	fixedValue,
});

ゲッターではなく値を startStudio()、startServer()、およびコンシューマーに渡します。新しい内部パラメーターは必須にし、不在が有効な場合は T | null を使用します。

Studio のキュー境界で、起動時に固定するレンダリング設定を StudioRenderJobFixedConfig に格納し、そのオブジェクトをジョブプロセッサーに渡します。Studio の起動後に設定状態が変わっている可能性があるため、プロセッサーから option.getValue() を呼び出さないでください。

起動時に固定する代表的なコンシューマーには、Studio のポート、エントリーポイント、有効なコンパイラーの選択とオーバーライド、ポーリングモード、公開ディレクトリとウォッチャー、ネットワークバインディング、クロスサイト分離ヘッダーがあります。

再読み込み可能な値を渡す

CLI の優先順位を維持するゲッターを通じて、再読み込み可能なオプションを読み取ります。

const getValue = () =>
	option.getValue({commandLine: parsedCli}).value;

await StudioServerInternals.startStudio({
	getValue,
});

ゲッターを必須の内部コールバックとして渡し、設定変更後のブラウザー再読み込みを受けて Studio の HTML を生成する場合など、設定変更を反映させる境界でのみ呼び出します。ゲッターを早い段階で評価し、その結果を後続の処理に渡さないでください。

すでに StudioRuntimeConfig で表現されている値には、既存の getStudioRuntimeConfig() の経路を使用します。このエクスポートされた型を拡張する際は注意してください。必須プロパティを追加すると、公開 API の破壊につながる可能性があります。独立した HTML ブートストラップ値については、専用のゲッターを Studio サーバー内部の各層に渡します。

Studio のすべてのコンシューマーで再読み込みに対応できる場合に限り、このパターンを使用します。代表的な例は、初期化済みリソースの再構築を必要としない UI の動作や HTML ブートストラップのデフォルト値です。

ライフサイクルの競合を解決する

オプションの読み取り箇所をすべて検索し、それぞれを個別に判断します。

rg -n "myOption|setMyOption|my-cli-flag" packages

すべてのコンシューマーが再読み込みに対応していない場合は、Studio の起動時にオプションを一度だけ取得し、すべてのコンシューマーに同じ値を渡します。たとえば、有効なプレビューコンパイラーがバンドラーの変更に対応できない場合、それ以降のレンダリングジョブでも起動時に選択したバンドラーを維持する必要があります。

エイリアスは同じオプションとして扱います。非推奨のセッターが複数の値を更新する場合、影響を受ける Studio のすべてのコンシューマーに、より厳格な起動時固定のライフサイクルを適用します。

リセットとロールバック

変更されたファイルを実行する前に、設定の再読み込みでオプションがリセットされるようにします。セッターを削除したときにデフォルト値に戻るようにしてください。BrowserSafeApis.options を通じて登録され、Config から直接公開されているオプションは、resetBrowserSafeConfigOptions() によってリセットされます。カスタムモジュールの状態については、ConfigInternals.resetConfigOptions() で明示的にリセットを追加します。

トランザクション方式の再読み込み動作を維持してください。無効な設定変更があった場合も、直前の有効な設定をそのまま適用します。

ライフサイクルを検証する

既存のチェックまたは手動のワークフローを使って、分類を検証します。

• 再読み込み可能：初回読み取り後にオプションを変更し、意図した再読み込み／リクエストの境界を越えて、新しい値が反映されることを確認します。
• 起動時に固定：初期値を取得し、設定状態を変更して、初期化済みのコンシューマーが引き続き元の値を受け取ることを確認します。
• コンシューマー間：いずれかのコンシューマーが必要とする場合に、すべての Studio コンシューマーが同じ起動時のスナップショットを受け取ることを確認します。
• リセット：再読み込み時に以前設定したオプションを省略し、デフォルト値に戻ることを確認します。
• null 許容の内部入力：値が存在しない場合に、呼び出し箇所で明示的に null を渡すことを確認します。

影響を受けるパッケージに対して、対象を絞ったビルドとチェックを実行します。

bunx turbo run make lint formatting --filter='@remotion/cli' --filter='@remotion/studio-server'
bun test packages/cli/src/test/config-reload.test.ts packages/cli/src/test/config-reset.test.ts