Add a new CLI option

Add a new CLI option

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<boolean>;

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>.