Skip to main content

Integrating an Element Library with Studio

An Element contains the source code for one component. It also contains the data that Studio needs to insert the component.

Studio writes the source code to an .element.tsx file. Studio installs only the packages in the Element's dependencies list. A component that follows the Element guidelines is usually ready for Studio.

Use this procedure to preview and deliver a component:

Show the component in a <Player>.
2
 Pass the component source code to createElementPayload().
3
 Use the payload to install the Element or drag the Element into Studio.

The website can reuse, combine, or change source code before the website creates the payload. The website can also let users change the source code. Studio receives only the final payload.

Show a Player preview​

Show each component in a <Player>. The preview lets users examine the component before they send it to Studio.

Import the component normally for the preview. The website bundler then compiles the component.

Use the same dimensions and duration in the Player and the Element payload.

Asset handlingv4.0.528​

Images, audio, and video that your preview loads from URLs can be downloaded into the user's public folder when they install the Element, or keep loading from their URLs.

Pass each asset to the component as a prop, such as src, instead of hardcoding its URL. Your preview passes the URL. The installed Element gets either src={staticFile('my-element/logo.png')} or the same URL. The component source doesn't change.

To download an asset, declare it in the payload's assets and replace its URL in the payload's initialProps with staticFileRef(). Studio saves the file and passes it to the component with staticFile(). See the staticFileRef() example.

To keep an asset remote, leave its URL in initialProps.

Reuse component code​

Use the same implementation in the Player preview and the installed Element. Import the component module for the Player. Load the component source as a string for the payload.

For a self-contained .tsx component, both imports can point to the same file. This avoids a separate Element implementation.

Vite​

Vite lets you import file content with ?raw. The following imports load the same .tsx file in two forms. The normal import provides the component and its Element definition. The ?raw import provides the source code string.

LowerThirdGalleryItem.tsx
import {Player} from '@remotion/player';
import {InstallActions} from './InstallActions';
import LowerThirdElement, {
  lowerThirdElementDefinition,
} from './LowerThirdElement';
import lowerThirdSourceCode from './LowerThirdElement.tsx?raw';

export const LowerThirdGalleryItem = () => {
  return (
    <>
      <Player
        component={LowerThirdElement}
        compositionWidth={lowerThirdElementDefinition.dimensions.width}
        compositionHeight={lowerThirdElementDefinition.dimensions.height}
        durationInFrames={lowerThirdElementDefinition.durationInFrames}
        fps={lowerThirdElementDefinition.fps}
      />
      <InstallActions
        definition={lowerThirdElementDefinition}
        sourceCode={lowerThirdSourceCode}
      />
    </>
  );
};

The shape of lowerThirdElementDefinition is specific to the Element Library. The Studio Protocol does not require this object.

Next.js​

Next.js can use Webpack or Turbopack. The method that gets the source code string depends on the selected bundler.

The Studio Protocol does not require a specific method. It requires only that the browser receives the final source code string.

With Webpack, an asset/source rule can provide ?raw imports.

With Turbopack, a script could create a module that exports the same component source as a string.

Add install actions​

Create one payload for both install actions. Run the actions in the browser.

When Studio embeds the library through Browse Elements, use isInsideStudio() to hide actions that are redundant inside the Studio iframe.

Test the integration​

  • Compare the Player preview with the installed Element.
  • Validate each payload with createElementPayload().
  • Test installation and cross-tab drag-and-drop from the production website.
  • Install the Element in a clean Remotion project. Check for unresolved imports and package dependencies.
  • Verify that installed assets appear in the public directory and render or play from local files. Confirm that assets intended to stay remote still use their URLs.
  • Treat the source code as public. The browser receives it, and Studio shows it.
  • Serve the production website through HTTPS. HTTP is supported only on localhost and 127.0.0.1.

See also​