Nullable new params

Nullable new params

Use this skill when a change added a new parameter or type member as optional. In internal Remotion code, new inputs must be required and nullable so every caller makes an explicit choice.

Rule

• Internal contracts: write name: T | null, not name?: T.
• Call sites must pass null explicitly when no value exists.
• Implementation checks should prefer value === null / value !== null when null is the absence sentinel.
• Do not use undefined as the absence sentinel for new internal APIs unless the surrounding local contract already standardizes on undefined.
• The anti-pattern includes redundant shapes such as frozenFrame?: number | null; make it frozenFrame: number | null.

Public APIs are the exception. If the changed signature, props type, or options object is exported from a package public entrypoint or documented in packages/docs/docs, making the new field/argument required is a breaking change. Keep it optional or add a backwards-compatible overload/options path, then document/default it as appropriate.

Workflow

1. Inspect the diff for newly added optional members or parameters:

bun .agents/skills/nullable-new-params/scripts/find-new-optional-params.ts

Useful variants:

bun .agents/skills/nullable-new-params/scripts/find-new-optional-params.ts origin/main...HEAD
bun .agents/skills/nullable-new-params/scripts/find-new-optional-params.ts --cached

2. For each candidate, classify whether it is public:

   • Public: exported from a package entrypoint, included in package exports, or documented in packages/docs/docs.
   • Internal: local helpers, internal component props, cross-file monorepo helpers, test utilities, internal context data, and types not exposed through package entrypoints.
   • If unsure, grep package entrypoints and docs before changing API shape.

3. For internal candidates, refactor the type from optional to required nullable:

type Before = {
  readonly frame?: number;
};