How to convert a hardcoded CLI flag into a proper AnyRemotionOption, or add a brand new one.
1. Create the option definition
Create 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;
The type in `AnyRemotionOption<T>` and `type: <value> as T` determines the option's value type. Use `boolean`, `string | null`, `number | null`, etc.
The `id` must be unique and contain only lowercase letters, digits, and hyphens. It determines the `/docs/options/<id>` page and the `<Options id="..." />` value. It usually matches `cliFlag`, but shared flags can have distinct option IDs.
Set `docLink` to `https://www.remotion.dev/docs/options/<id>`.
For negating flags (like `--disable-ask-ai` → `askAIEnabled = false`), handle the inversion in `getValue`.
## 2. Register in options index
**`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.
## 3. Update CLI parsed flags
**`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>;`
## 4. Use the option where needed
Instead of reading `parsedCli['my-flag']` directly, resolve via:
```ts
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.
If the option is consumed by Studio, read ../studio-config-option-lifecycle/SKILL.md completely before wiring it. Classify the option as startup-fixed or reloadable across all Studio consumers; mixed behavior is not allowed. If any consumer requires startup-fixed behavior, pass the startup snapshot to every consumer.
5. Add to Config
packages/cli/src/config/index.ts:
- Add to the destructured
BrowserSafeApis.options - Add the setter signature to the
FlatConfigtype (either in theRemotionConfigObjectglobal interface or theFlatConfigintersection) - Add the implementation to the
Configobject:setMyFlagEnabled: myFlagOption.setConfig
6. Update docs — IMPORTANT, do not skip this step
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
idmust match the option'sidvalue
CLI help metadata: Add the flag to each supported command's option list in packages/cli/src/print-help.ts, packages/lambda/src/cli/help.ts, or packages/cloudrun/src/cli/help.ts. The generated option page uses the help entries' optionIds to list supported commands; ensure shared flags resolve to the correct option ID.
API pages: Document each public parameter under its own heading so the generated page can link to it.
packages/docs/docs/config.mdx:
- Add or update the
## \setMyFlagEnabled()`` section with:<Options id="my-flag" />for the description- A twoslash config example
- A link to
/docs/options/<id>noting that the CLI flag takes precedence
Follow the pattern of nearby entries (e.g., setAskAIEnabled, setEnableCrossSiteIsolation).
Generated option reference: Generate packages/docs/docs/options/<id>.mdx and the options index using the commands below. Edit the option definition and API/config docs rather than the generated MDX. Option pages are added to the sidebar automatically.
7. Build and verify
# From the repository root
bun run build
cd packages/docs
bun run generate-option-docs
bun run render-cards
bun run check-option-docs
Verify /docs/options/<id> includes the description, supported commands, and relevant API/configuration links. Commit the generated page and index, the article catalog (packages/docs/src/data/articles.ts), and the new social preview card.
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