add-cli-option

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Add a new CLI option

添加新的CLI选项

How to convert a hardcoded CLI flag into a proper

AnyRemotionOption

, or add a brand new one.

如何将硬编码的CLI标志转换为标准的

AnyRemotionOption

，或者添加一个全新的选项。

1. Create the option definition

1. 创建选项定义

Create

packages/renderer/src/options/<name>.tsx

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,
  description: () => <>Description shown in docs.</>,
  ssrName: null, // or 'myFlag' if used in SSR APIs
  docLink: 'https://www.remotion.dev/docs/config#setmyflagenabled',
  type: false as boolean, // default value, also sets the TypeScript type
  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>;

The type in

AnyRemotionOption<T>

and

type: <default> as T

determines the option's value type. Use

boolean

string | null

number | null

, etc.

For negating flags (like

--disable-ask-ai

→

askAIEnabled = false

), handle the inversion in

getValue

在

packages/renderer/src/options/<name>.tsx

中创建文件：

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,
  description: () => <>Description shown in docs.</>,
  ssrName: null, // or 'myFlag' if used in SSR APIs
  docLink: 'https://www.remotion.dev/docs/config#setmyflagenabled',
  type: false as boolean, // default value, also sets the TypeScript type
  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: <default> as T

决定了选项的值类型。可使用

boolean

、

string | null

、

number | null

等类型。

对于否定式标志（如

--disable-ask-ai

→

askAIEnabled = false

），需在

getValue

中处理反转逻辑。

2. Register in options index

2. 在选项索引中注册

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

Add the import (keep alphabetical within the import block)
Add the option to the
```
allOptions
```
object

This makes it available as

BrowserSafeApis.options.myFlagOption

throughout the codebase.

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

添加导入语句（在导入块内按字母顺序排列）
将选项添加到
```
allOptions
```
对象中

此操作会让该选项在整个代码库中可通过

BrowserSafeApis.options.myFlagOption

访问。

3. Update CLI parsed flags

3. 更新CLI解析标志

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

For boolean flags, add

BrowserSafeApis.options.myFlagOption.cliFlag

to the

BooleanFlags

array

For non-boolean flags, no entry needed here (minimist handles them as strings/numbers automatically)

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

Add to the destructured
```
BrowserSafeApis.options
```

In the

CommandLineOptions

type, add:

[myFlagOption.cliFlag]: TypeOfOption<typeof myFlagOption>;

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

对于布尔型标志，将

BrowserSafeApis.options.myFlagOption.cliFlag

添加到

BooleanFlags

数组中

对于非布尔型标志，无需在此处添加（minimist会自动将其处理为字符串/数字）

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

添加到解构后的
```
BrowserSafeApis.options
```
中

在

CommandLineOptions

类型中添加：

[myFlagOption.cliFlag]: TypeOfOption<typeof myFlagOption>;

4. Use the option where needed

4. 在需要的地方使用选项

Instead of reading

parsedCli['my-flag']

directly, resolve via:

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

For Studio options, this is typically in

packages/cli/src/studio.ts

. For render options, in the relevant render command file.

不要直接读取

parsedCli['my-flag']

，而是通过以下方式获取：

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

对于Studio选项，通常在

packages/cli/src/studio.ts

中使用。对于渲染选项，在对应的渲染命令文件中使用。

5. Add to Config

5. 添加到配置中

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

Add to the destructured
```
BrowserSafeApis.options
```
Add the setter signature to the
```
FlatConfig
```
type (either in the
```
RemotionConfigObject
```
global interface or the
```
FlatConfig
```
intersection)

Add the implementation to the

Config

object:

setMyFlagEnabled: myFlagOption.setConfig

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

添加到解构后的
```
BrowserSafeApis.options
```
中
在
```
FlatConfig
```
类型中添加设置器签名（可在全局接口
```
RemotionConfigObject
```
或
```
FlatConfig
```
交叉类型中添加）

在

Config

对象中添加实现：

setMyFlagEnabled: myFlagOption.setConfig

6. Update docs — IMPORTANT, do not skip this step

6. 更新文档——重要，请勿跳过此步骤

This step is mandatory. Every new option must have its docs updated to use

<Options id="..." />

so the description is pulled from the option definition automatically (single source of truth). If converting an existing hardcoded flag, replace any hand-written description with the

<Options>

component.

CLI command pages (check all that apply —

cli/render.mdx

lambda/cli/render.mdx

cloudrun/cli/render.mdx

cli/benchmark.mdx

Add or update the
```
### \
```
--my-flag`` section
Use
```
<Options id="my-flag" />
```
as the description body (no import needed — it's globally available)
The
```
id
```
must match the option's
```
cliFlag
```
/
```
id
```
value

packages/docs/docs/config.mdx
:

Add or update the
```
## \
```
setMyFlagEnabled()`` section with:
- ```
<Options id="my-flag" />
```
  for the description
- A twoslash config example
- A note that the CLI flag takes precedence

Follow the pattern of nearby entries (e.g.,

setAskAIEnabled

setEnableCrossSiteIsolation

**此步骤为必填项。**每个新选项都必须更新文档，使用

<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
```
必须与选项的
```
cliFlag
```
/
```
id
```
值匹配

packages/docs/docs/config.mdx
:

添加或更新
```
## \
```
setMyFlagEnabled()``章节，包含：
- 使用
```
<Options id="my-flag" />
```
  作为描述
- 一个twoslash配置示例
- 说明CLI标志优先级更高的注释

遵循附近条目的格式（例如

setAskAIEnabled

、

setEnableCrossSiteIsolation

）。

7. Build and verify

7. 构建并验证

cd packages/renderer && bun run make
cd packages/cli && bun run make

cd packages/renderer && bun run make
cd packages/cli && bun run make

Reference files

参考文件

Option type definition:
```
packages/renderer/src/options/option.ts
```
Good example to copy:
```
packages/renderer/src/options/ask-ai.tsx
```
(boolean, studio-only)
Options index:
```
packages/renderer/src/options/index.tsx
```
CLI flag registration:
```
packages/cli/src/parsed-cli.ts
```
CLI type definitions:
```
packages/cli/src/parse-command-line.ts
```
Config registration:
```
packages/cli/src/config/index.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
```