BuilderIO/composition-management

Composition Management

Compositions are the core unit of the animation studio. Each composition is a Remotion component registered in the central registry.

Registry (app/remotion/registry.ts)

The compositions array is the single source of truth. Each entry:

type CompositionEntry = {
  id: string;              // URL slug: "logo-reveal" -> /c/logo-reveal
  title: string;
  description: string;
  component: React.FC<any>;
  durationInFrames: number;
  fps: number;
  width: number;
  height: number;
  defaultProps: Record<string, any>;  // Editable in PropsEditor
  tracks: AnimationTrack[];           // Default track data
};

Important: defaultProps is shown in PropsEditor as editable fields. Do NOT include tracks in defaultProps -- tracks are passed separately.

Adding a New Composition

1. Create app/remotion/compositions/MyComp.tsx
2. Export it from app/remotion/compositions/index.ts
3. Add a CompositionEntry to the compositions array in registry.ts
4. Define tracks with meaningful IDs, labels, frame ranges, and animatedProps

Component Template

import { AbsoluteFill, useCurrentFrame, useVideoConfig } from "remotion";
import type { AnimationTrack } from "@/types";
import { trackProgress, getPropValue, findTrack } from "../trackAnimation";

const FALLBACK_TRACKS: AnimationTrack[] = [
  {
    id: "mc-intro",
    label: "Intro",
    startFrame: 0,
    endFrame: 30,
    easing: "spring",
    animatedProps: [
      { property: "opacity", from: "0", to: "1", unit: "" },
    ],
  },
];

export const MyComp: React.FC<{ tracks?: AnimationTrack[] }> = ({
  tracks = FALLBACK_TRACKS,
}) => {
  const frame = useCurrentFrame();
  const { fps } = useVideoConfig();

  const introTrack = findTrack(tracks, "mc-intro", FALLBACK_TRACKS[0]);
  const p = trackProgress(frame, fps, introTrack);
  const opacity = getPropValue(p, introTrack, "opacity", 0, 1);

  return (
    <AbsoluteFill>
      <div style={{ opacity }}>Content</div>
    </AbsoluteFill>
  );
};

Key Rules

• Every animation MUST be registered as a track -- no hardcoded frame checks
• Always declare FALLBACK_TRACKS in the component file
• Use findTrack() / trackProgress() / getPropValue() -- never hardcode values
• Registry is never mutated at runtime -- overrides go through localStorage
• Run pnpm typecheck after changes

Using the create-composition Script

pnpm action create-composition --id "my-comp" --title "My Composition"

This scaffolds the component file, exports, and registry entry.