Bundle & Loading Strategy
Efficient video rendering requires a delicate balance between minimal bundle sizes and ensuring all assets are fully loaded before a frame is captured. The Agent Board utilizes several strategies to ensure "Vercel-grade" performance, particularly when deploying to serverless environments like Remotion Lambda.
Asset Reference Strategy
To ensure assets are correctly resolved across different deployment environments (local vs. cloud), you must use the staticFile() utility.
The staticFile() Utility
This function should be used for all assets located in the public/ folder. It returns an encoded URL that handles subdirectory nesting and ensures the asset is reachable during the render process.
import { Img, staticFile } from 'remotion';
export const MyComponent = () => {
// Always wrap public paths in staticFile()
return <Img src={staticFile('branding/logo.png')} />;
};
Media Components
Always use the specialized components from @remotion/media (<Audio />, <Video />) and @remotion/animated (<Img />). These components are internally optimized to:
- Block Rendering: They prevent the frame from being "ready" until the source is fully loaded.
- Handle Special Characters: They automatically encode filenames containing
#,?, or&.
Font Loading Strategy
Fonts are a common source of layout shift or "flashing" in generated videos. To prevent this, Agent Board enforces a blocking font strategy.
Google Fonts
Use the @remotion/google-fonts package. It is type-safe and automatically integrates with Remotion’s rendering engine to block frames until the font is loaded.
import { loadFont } from '@remotion/google-fonts/Inter';
// Call outside the component to trigger loading early
const { fontFamily } = loadFont();
export const MyAnimation = () => {
return <div style={{ fontFamily }}>Optimized Text</div>;
};
Local Fonts
For custom brand fonts, use the FontFace API combined with staticFile(). You must manually ensure the font is added to document.fonts before the first frame renders.
Dynamic Metadata & Pre-fetching
To keep bundles slim, avoid hardcoding large data structures. Use the calculateMetadata function in your Composition definition to fetch data or derive video dimensions dynamically before the render starts.
Pre-calculating Dimensions
This prevents the need for client-side resizing and allows for exact-fit rendering.
import { getMediaMetadata } from './utils/metadata';
<Composition
id="DynamicVideo"
component={Main}
calculateMetadata={async ({ props }) => {
const metadata = await getMediaMetadata(props.src);
return {
durationInFrames: Math.floor(metadata.durationInSeconds * 30),
width: metadata.width,
height: metadata.height,
};
}}
/>
Managing Dynamic Imports
Large third-party libraries (like Three.js or D3) should be handled carefully to avoid bloated initial bundles that slow down serverless cold starts.
Conditional Loading
If a component (e.g., a 3D scene) is only used in specific compositions, use React's dynamic import() or lazy() to isolate those dependencies.
Barrel File Optimization
Avoid "Giant Barrel Files" (index files that export everything in a folder). While convenient for development, they often lead to "Tree-shaking failure," where importing a single utility pulls in the entire library.
- Recommendation: Import directly from the specific file path when working with heavy modules.
Resource Validation
Before initiating a heavy render job, use the canDecode strategy to validate that remote assets are compatible with the browser/environment.
import { canDecode } from './utils/validation';
const initRender = async (url: string) => {
const isCompatible = await canDecode(url);
if (!isCompatible) {
throw new Error("Resource format not supported by the rendering engine.");
}
// Proceed with render...
};
Performance Checklist
| Strategy | Benefit |
| :--- | :--- |
| staticFile() | Correct path resolution across environments. |
| calculateMetadata | Offloads logic from the render loop; enables dynamic durations. |
| Google Fonts | Prevents layout shifts and missing text in renders. |
| @remotion/media | Synchronizes media loading with frame capture. |
| canDecode | Prevents "silent failures" where videos don't appear in the final output. |