add-cli-option

新しい CLI オプションを追加する

ハードコードされた CLI フラグを適切な AnyRemotionOption に変換する方法、または新しいフラグを追加する方法です。

1. オプション定義を作成する

packages/renderer/src/options/<name>.tsx を作成します。

import type {AnyRemotionOption} from './option';

let myValue = false; // module-level default state

const cliFlag = 'my-flag' as const;

export const myFlagOption = {
  name: 'Human-readable Name',
  cliFlag,
  id: cliFlag,
  description: () => <>Description shown in docs.</>,
  ssrName: null, // or 'myFlag' if used in SSR APIs
  docLink: 'https://www.remotion.dev/docs/options/my-flag',
  type: false as boolean, // TypeScript type witness; defaults are resolved in getValue
  getValue: ({commandLine}) => {
    if (commandLine[cliFlag] !== undefined) {
      return {value: commandLine[cliFlag] as boolean, source: 'cli'};
    }
    return {value: myValue, source: 'config'};
  },
  setConfig(value) {
    myValue = value;
  },
} satisfies AnyRemotionOption<boolean>;

AnyRemotionOption<T> の型と type: <value> as T によって、オプションの値の型が決まります。boolean、string | null、number | null などを使用してください。

id は一意で、英小文字、数字、ハイフンのみを含む必要があります。これによって /docs/options/<id> ページと <Options id="..." /> の値が決まります。通常は cliFlag と一致しますが、共有フラグに異なるオプション ID を設定することもできます。

docLink には https://www.remotion.dev/docs/options/<id> を設定してください。

フラグを否定する場合（--disable-ask-ai → askAIEnabled = false など）は、getValue で反転処理を行ってください。

2. options index に登録する

packages/renderer/src/options/index.tsx：

• インポートを追加します（インポートブロック内でアルファベット順を維持してください）
• allOptions オブジェクトにオプションを追加します

これにより、コードベース全体で BrowserSafeApis.options.myFlagOption として使用できるようになります。

3. CLI の解析済みフラグを更新する

packages/cli/src/parsed-cli.ts：

• ブール値フラグの場合、BooleanFlags 配列に BrowserSafeApis.options.myFlagOption.cliFlag を追加します
• ブール値以外のフラグの場合、ここにエントリーを追加する必要はありません（minimist が文字列または数値として自動的に処理します）

packages/cli/src/parse-command-line.ts：

• BrowserSafeApis.options の分割代入に追加します
• CommandLineOptions 型に次を追加します：[myFlagOption.cliFlag]: TypeOfOption<typeof myFlagOption>;

4. 必要な箇所でオプションを使用する

parsedCli['my-flag'] を直接読み取る代わりに、次のように解決します。

const myFlag = myFlagOption.getValue({commandLine: parsedCli}).value;

Studio オプションの場合、通常は packages/cli/src/studio.ts で行います。レンダーオプションの場合は、該当するレンダーコマンドファイルで行います。

オプションが Studio で使用される場合は、接続する前に ../studio-config-option-lifecycle/SKILL.md を最後まで読んでください。すべての Studio コンシューマーにおいて、オプションを起動時に固定するか、再読み込み可能にするか分類してください。動作を混在させることはできません。いずれかのコンシューマーで起動時に固定する必要がある場合は、すべてのコンシューマーに起動時のスナップショットを渡してください。

5. Config に追加する

packages/cli/src/config/index.ts：

• BrowserSafeApis.options の分割代入に追加します
• FlatConfig 型にセッターのシグネチャを追加します（グローバルインターフェース RemotionConfigObject または FlatConfig の交差型のどちらかに追加します）
• Config オブジェクトに実装を追加します：setMyFlagEnabled: myFlagOption.setConfig

6. ドキュメントを更新する — 重要：この手順を省略しないでください

この手順は必須です。 新しいオプションはすべて、説明がオプション定義から自動的に取得されるように、ドキュメントを更新して <Options id="..." /> を使用してください（信頼できる情報源を一元化します）。既存のハードコードされたフラグを変換する場合は、手書きの説明を <Options> コンポーネントに置き換えてください。

CLI コマンドのページ（該当するものをすべて確認してください — cli/render.mdx、lambda/cli/render.mdx、cloudrun/cli/render.mdx、cli/benchmark.mdx）：

• ### \--my-flag`` セクションを追加または更新する
• 説明本文に <Options id="my-flag" /> を使用する（インポートは不要です。グローバルに利用できます）
• id はオプションの id の値と一致させる

CLI ヘルプのメタデータ：packages/cli/src/print-help.ts、packages/lambda/src/cli/help.ts、または packages/cloudrun/src/cli/help.ts の各サポート対象コマンドのオプション一覧にフラグを追加してください。生成されるオプションページでは、ヘルプ項目の optionIds を使用してサポート対象コマンドが一覧表示されます。共有フラグが正しいオプション ID に解決されることを確認してください。

API ページ：生成されるページからリンクできるように、各公開パラメーターをそれぞれ独自の見出しの下に記載してください。

packages/docs/docs/config.mdx：

• ## \setMyFlagEnabled()`` セクションを追加または更新し、以下を含める：
  • 説明に <Options id="my-flag" />
  • twoslash 設定の例
  • CLI フラグが優先されることを明記した /docs/options/<id> へのリンク

近くの項目（例：setAskAIEnabled、setEnableCrossSiteIsolation）のパターンに従ってください。

生成されるオプションリファレンス：以下のコマンドを使用して、packages/docs/docs/options/<id>.mdx とオプションのインデックスを生成してください。生成された MDX ではなく、オプション定義と API／設定ドキュメントを編集してください。オプションページはサイドバーに自動で追加されます。

7. ビルドと確認

# From the repository root
bun run build
cd packages/docs
bun run generate-option-docs
bun run render-cards
bun run check-option-docs

/docs/options/<id> に説明、サポート対象コマンド、関連する API／設定へのリンクが含まれていることを確認してください。生成されたページとインデックス、記事カタログ（packages/docs/src/data/articles.ts）、新しいソーシャルプレビューカードをコミットしてください。

参考ファイル

• オプションの型定義：packages/renderer/src/options/option.ts
• コピーに適した例：packages/renderer/src/options/ask-ai.tsx（ブール値、studio のみ）
• オプションのインデックス：packages/renderer/src/options/index.tsx
• CLI フラグの登録：packages/cli/src/parsed-cli.ts
• CLI 型定義：packages/cli/src/parse-command-line.ts
• 設定の登録：packages/cli/src/config/index.ts