Bundling & Loading Strategy

Strategy Overview

To achieve sub-second interaction times and smooth rendering performance in the Agent Board, we employ a multi-layered bundling and loading strategy. This approach focuses on code splitting heavy dependencies, pre-validating media assets, and leveraging Remotion's lifecycle hooks to ensure all resources are ready before the first frame is painted.

Dynamic Imports & Code Splitting

Heavy libraries such as Three.js, React Three Fiber, or D3.js should not be part of the initial entry bundle if they are only used in specific compositions. Use dynamic import() or React.lazy to ensure these dependencies are only fetched when required.

3D Content Optimization

For 3D compositions, ensure that @remotion/three and related assets are loaded conditionally. This prevents the main dashboard bundle from bloating.

import React, { Suspense } from 'react';

const ThreeContent = React.lazy(() => import('./ThreeContent'));

export const My3DComposition = () => {
  return (
    <Suspense fallback={null}>
      <ThreeContent />
    </Suspense>
  );
};

Asset Loading with `staticFile()`

All local assets (images, videos, audio) must be placed in the public/ folder and referenced using the staticFile() helper. This ensures that assets are correctly resolved regardless of the deployment environment (e.g., GitHub Pages subfolders or S3 buckets).

import { Img, staticFile } from 'remotion';

export const Logo = () => {
  // Returns an encoded URL safe for production environments
  return <Img src={staticFile('branding/logo.png')} />;
};

Render-Blocking Assets

Remotion's native components (<Img>, <Video>, <Audio>) automatically pause the rendering engine until the underlying resource is fully buffered or loaded. This prevents "pop-in" effects and ensures visual consistency across renders.

Pre-render Metadata & Data Fetching

To ensure the composition has all necessary data before the timeline starts, use the calculateMetadata function. This allows you to fetch external API data, determine video dimensions, or calculate duration dynamically.

import { CalculateMetadataFunction } from 'remotion';

export const calculateMetadata: CalculateMetadataFunction<Props> = async ({ props, abortSignal }) => {
  const response = await fetch(`https://api.agentboard.com/data/${props.id}`, { 
    signal: abortSignal 
  });
  const data = await response.json();

  return {
    props: { ...props, initialData: data },
    durationInFrames: data.length * 30, // Dynamic duration
  };
};

Media Pre-validation

Before attempting to load large video files into the browser, use the canDecode strategy (via mediabunny). This allows the application to gracefully handle unsupported codecs or corrupted files before they impact the UI performance.

import { canDecode } from './utils/can-decode';

const checkVideoStatus = async (url: string) => {
  const isSupported = await canDecode(url);
  if (!isSupported) {
    console.warn("Browser cannot decode this video format.");
    // Fallback logic here
  }
};

Font Loading Strategy

Fonts are critical path resources. To prevent Layout Shift (CLS) in your video compositions, follow these rules:

Google Fonts: Use @remotion/google-fonts. These are loaded using the loadFont() helper which returns a fontFamily string and ensures the font is injected into the document before rendering begins.
Local Fonts: Use staticFile() combined with the standard FontFace API.

import { loadFont } from '@remotion/google-fonts/Inter';

// Pre-loading at the module level
const { fontFamily } = loadFont();

export const TextLayer = () => {
  return <div style={{ fontFamily }}>Optimized Text</div>;
};

Conditional Bundling Checklist