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. You do not have to publish or install the Element Library in the target project.

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.

Preview installed assetsv4.0.528​

Accept image, audio, and video URLs as component props, rather than hardcoding preview URLs or installed file paths in the source.

Pass normal URL strings to the Player. These may point to assets served by your preview website or, if you prefer, hosted elsewhere. The preview location does not need to match the installed asset path.

For assets that should be copied into the user's project, declare them in the payload's assets. Choose public-relative paths scoped to the component, such as my-element/logo.png, to reduce collisions with other components.

In the payload's initialProps, replace each corresponding URL with staticFileRef(), referencing the declared asset path. Keep these references out of the Player's inputProps: they are installation metadata, not runtime URLs. See the staticFileRef() example for the complete payload and generated code.

Studio saves the assets into the public directory and generates staticFile() expressions on the component invocation. The Element source stays unchanged. This works in both installation modes.

For assets that should remain remote after installation, keep URL strings in initialProps instead of using references. Those assets continue to depend on the remote host.

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​