Skip to content

🎥 Make videos programmatically with React

Elements: Accept object in Config.addElementLibrary()

Igor Samokhovetsb608f082683f
diff --git a/packages/cli/src/config/element-libraries.ts b/packages/cli/src/config/element-libraries.ts
index d5ba326cf5..7c8fa03ec0 100644
--- a/packages/cli/src/config/element-libraries.ts
+++ b/packages/cli/src/config/element-libraries.ts
@@ -1,11 +1,27 @@
import type {StudioElementLibrary} from '@remotion/studio-shared';
+export type AddElementLibraryOptions = {
+ readonly url: string;
+ readonly displayName?: string;
+};
+
let elementLibraries: StudioElementLibrary[] = [];
-export const addElementLibrary = (url: string, displayName: string | null) => {
+export const addElementLibrary = (options: AddElementLibraryOptions) => {
+ if (
+ typeof options !== 'object' ||
+ options === null ||
+ Array.isArray(options)
+ ) {
+ throw new Error(
+ `Config.addElementLibrary() expects an object, got ${typeof options}`,
+ );
+ }
+
+ const {url, displayName} = options;
if (typeof url !== 'string') {
throw new Error(
- `Config.addElementLibrary() expects a string, got ${typeof url}`,
+ `Config.addElementLibrary() expects "url" to be a string, got ${typeof url}`,
);
}
@@ -24,7 +40,7 @@ export const addElementLibrary = (url: string, displayName: string | null) => {
);
}
- if (displayName !== null && typeof displayName !== 'string') {
+ if (displayName !== undefined && typeof displayName !== 'string') {
throw new Error(
`Config.addElementLibrary() expects the display name to be a string, got ${typeof displayName}`,
);
diff --git a/packages/cli/src/config/index.ts b/packages/cli/src/config/index.ts
index 0308176fa8..d00464759b 100644
--- a/packages/cli/src/config/index.ts
+++ b/packages/cli/src/config/index.ts
@@ -30,6 +30,7 @@ import {
} from './buffer-state-delay-in-milliseconds';
import type {Concurrency} from './concurrency';
import {getConcurrency} from './concurrency';
+import type {AddElementLibraryOptions} from './element-libraries';
import {
addElementLibrary,
getElementLibraries,
@@ -75,6 +76,7 @@ import {getWebpackCaching} from './webpack-caching';
import {getWebpackPolling} from './webpack-poll';
export type {
+ AddElementLibraryOptions,
BundlerOverrideFn,
Concurrency,
RspackConfiguration,
@@ -624,7 +626,7 @@ type FlatConfig = RemotionConfigObject &
/**
* Add an Element library to the Remotion Studio.
*/
- addElementLibrary: (url: string, displayName?: string) => void;
+ addElementLibrary: (options: AddElementLibraryOptions) => void;
/**
* Set the audio codec to use for the output video.
* See the Encoding guide in the docs for defaults and available options.
@@ -764,9 +766,7 @@ export const Config: FlatConfig = {
'The config format has changed. Change `Config.Puppeteer.*()` calls to `Config.*()` in your config file.',
);
},
- addElementLibrary: (url, displayName) => {
- addElementLibrary(url, displayName ?? null);
- },
+ addElementLibrary,
setMaxTimelineTracks: StudioServerInternals.setMaxTimelineTracks,
setKeyboardShortcutsEnabled: keyboardShortcutsOption.setConfig,
setInteractivityEnabled: interactivityOption.setConfig,
diff --git a/packages/cli/src/test/config-file-change.test.ts b/packages/cli/src/test/config-file-change.test.ts
index addcd6ba27..86bad1e5a9 100644
--- a/packages/cli/src/test/config-file-change.test.ts
+++ b/packages/cli/src/test/config-file-change.test.ts
@@ -42,8 +42,8 @@ test('classifies runtime config changes', () => {
).toBe('runtime');
expect(
classify(
- prepare('Config.addElementLibrary("https://one.example.com");'),
- prepare('Config.addElementLibrary("https://two.example.com");'),
+ prepare('Config.addElementLibrary({url: "https://one.example.com"});'),
+ prepare('Config.addElementLibrary({url: "https://two.example.com"});'),
),
).toBe('runtime');
});
diff --git a/packages/cli/src/test/config-reload.test.ts b/packages/cli/src/test/config-reload.test.ts
index a39c5d7513..34ba9646e2 100644
--- a/packages/cli/src/test/config-reload.test.ts
+++ b/packages/cli/src/test/config-reload.test.ts
@@ -46,7 +46,7 @@ test('an invalid config reload keeps the previous configuration', async () => {
},
];
writeConfig(
- `const {Config} = require('@remotion/cli/config'); Config.setStudioPort(4321); Config.setDefaultEditor('cursor'); Config.setDefaultCodingAgent('codex'); Config.addElementLibrary('https://initial.example.com/elements', 'Initial Elements');`,
+ `const {Config} = require('@remotion/cli/config'); Config.setStudioPort(4321); Config.setDefaultEditor('cursor'); Config.setDefaultCodingAgent('codex'); Config.addElementLibrary({url: 'https://initial.example.com/elements', displayName: 'Initial Elements'});`,
);
await loadConfig(temporaryDirectory);
@@ -62,7 +62,7 @@ test('an invalid config reload keeps the previous configuration', async () => {
}).value,
).toBe('codex');
writeConfig(
- `const {Config} = require('@remotion/cli/config'); Config.setStudioPort(5678); Config.setDefaultEditor('windsurf'); Config.setDefaultCodingAgent('cursor'); Config.addElementLibrary('https://invalid.example.com/elements', 'Invalid Elements'); throw new Error('Invalid config');`,
+ `const {Config} = require('@remotion/cli/config'); Config.setStudioPort(5678); Config.setDefaultEditor('windsurf'); Config.setDefaultCodingAgent('cursor'); Config.addElementLibrary({url: 'https://invalid.example.com/elements', displayName: 'Invalid Elements'}); throw new Error('Invalid config');`,
);
expect((await reloadTestConfig()).type).toBe('error');
expect(ConfigInternals.getStudioPort()).toBe(4321);
@@ -78,7 +78,7 @@ test('an invalid config reload keeps the previous configuration', async () => {
).toBe('codex');
writeConfig(
- `const {Config} = require('@remotion/cli/config'); Config.setStudioPort(5678); Config.setDefaultEditor('windsurf'); Config.setDefaultCodingAgent('cursor'); Config.addElementLibrary('https://snapshot.example.com/elements', 'Snapshot Elements');`,
+ `const {Config} = require('@remotion/cli/config'); Config.setStudioPort(5678); Config.setDefaultEditor('windsurf'); Config.setDefaultCodingAgent('cursor'); Config.addElementLibrary({url: 'https://snapshot.example.com/elements', displayName: 'Snapshot Elements'});`,
);
const snapshotErrorMessage = 'The derived config snapshot was rejected';
expect(
@@ -107,7 +107,7 @@ test('an invalid config reload keeps the previous configuration', async () => {
expect(ConfigInternals.getElementLibraries()).toEqual(initialLibraries);
writeConfig(
- `const {Config} = require('@remotion/cli/config'); Config.setStudioPort(6789); Config.setDefaultEditor({type: 'custom', name: 'Acme Editor', executable: '/opt/acme/editor', arguments: ['--goto', '%TARGET_PATH%:%LINE_NUMBER%:%COLUMN_NUMBER%']}); Config.setDefaultCodingAgent('claude-code'); Config.addElementLibrary('https://reloaded.example.com/library', 'Reloaded Elements');`,
+ `const {Config} = require('@remotion/cli/config'); Config.setStudioPort(6789); Config.setDefaultEditor({type: 'custom', name: 'Acme Editor', executable: '/opt/acme/editor', arguments: ['--goto', '%TARGET_PATH%:%LINE_NUMBER%:%COLUMN_NUMBER%']}); Config.setDefaultCodingAgent('claude-code'); Config.addElementLibrary({url: 'https://reloaded.example.com/library', displayName: 'Reloaded Elements'});`,
);
expect((await reloadTestConfig()).type).toBe('success');
expect(ConfigInternals.getStudioPort()).toBe(6789);
diff --git a/packages/cli/src/test/config-reset.test.ts b/packages/cli/src/test/config-reset.test.ts
index f45eb39742..918ba16920 100644
--- a/packages/cli/src/test/config-reset.test.ts
+++ b/packages/cli/src/test/config-reset.test.ts
@@ -15,25 +15,31 @@ test('Studio render defaults keep the startup log level', () => {
test('Element library configuration must be valid', () => {
ConfigInternals.resetConfigOptions();
- expect(() => Config.addElementLibrary('/elements')).toThrow(
+ expect(() => Config.addElementLibrary({url: '/elements'})).toThrow(
'Config.addElementLibrary() expects an absolute URL',
);
- expect(() => Config.addElementLibrary('file:///tmp/elements')).toThrow(
+ expect(() => Config.addElementLibrary({url: 'file:///tmp/elements'})).toThrow(
'Config.addElementLibrary() only supports HTTP and HTTPS URLs',
);
- expect(() => Config.addElementLibrary(null as unknown as string)).toThrow(
- 'Config.addElementLibrary() expects a string',
- );
expect(() =>
- Config.addElementLibrary(
- 'https://example.com/elements',
- 123 as unknown as string,
- ),
+ Config.addElementLibrary(null as unknown as {url: string}),
+ ).toThrow('Config.addElementLibrary() expects an object');
+ expect(() =>
+ Config.addElementLibrary({url: null as unknown as string}),
+ ).toThrow('Config.addElementLibrary() expects "url" to be a string');
+ expect(() =>
+ Config.addElementLibrary({
+ url: 'https://example.com/elements',
+ displayName: 123 as unknown as string,
+ }),
).toThrow(
'Config.addElementLibrary() expects the display name to be a string',
);
expect(() =>
- Config.addElementLibrary('https://example.com/elements', ' '),
+ Config.addElementLibrary({
+ url: 'https://example.com/elements',
+ displayName: ' ',
+ }),
).toThrow(
'Config.addElementLibrary() expects the display name to not be empty',
);
@@ -62,7 +68,10 @@ test('reset config options restores defaults before reloading config', async ()
Config.setStudioPort(4321);
Config.setMaxTimelineTracks(123);
- Config.addElementLibrary('https://example.com/elements', 'Example Elements');
+ Config.addElementLibrary({
+ url: 'https://example.com/elements',
+ displayName: 'Example Elements',
+ });
Config.setChromiumOpenGlRenderer('angle');
Config.setCrf(12);
Config.setDefaultCodingAgent('codex');
diff --git a/packages/docs/docs/config.mdx b/packages/docs/docs/config.mdx
index fd5f754f6a..0fe83b4a21 100644
--- a/packages/docs/docs/config.mdx
+++ b/packages/docs/docs/config.mdx
@@ -200,10 +200,13 @@ Adds an externally hosted Element library to Remotion Studio.
```ts twoslash title="remotion.config.ts"
import {Config} from '@remotion/cli/config';
// ---cut---
-Config.addElementLibrary('https://example.com/elements', 'Acme Elements');
+Config.addElementLibrary({
+ url: 'https://example.com/elements',
+ displayName: 'Acme Elements',
+});
```
-Call `addElementLibrary()` once for each external library. The second argument sets its display name. If it is omitted, the URL host and path are shown instead.
+Call `addElementLibrary()` once for each external library. The `displayName` property is optional. If it is omitted, the URL host and path are shown instead.
When at least one library is configured, Browse Elements shows a dropdown containing Remotion Elements and every configured library. All libraries open in an embedded Studio modal.
diff --git a/packages/example/e2e/studio-protocol.test.mts b/packages/example/e2e/studio-protocol.test.mts
index 637b4b020d..c6dc6f2ba2 100644
--- a/packages/example/e2e/studio-protocol.test.mts
+++ b/packages/example/e2e/studio-protocol.test.mts
@@ -84,7 +84,7 @@ export const MyComponent = () => {
const configFile = path.join(temporaryProject, 'remotion.config.ts');
fs.appendFileSync(
configFile,
- `\nConfig.addElementLibrary('${externalLibraryUrl}', 'External Elements');\n`,
+ `\nConfig.addElementLibrary({url: '${externalLibraryUrl}', displayName: 'External Elements'});\n`,
);
fs.rmSync(path.join(temporaryProject, 'node_modules'), {
force: true,
@@ -255,7 +255,7 @@ export const MyComponent = () => {
fs.appendFileSync(
configFile,
- `Config.addElementLibrary('${reloadedExternalLibraryUrl}');\n`,
+ `Config.addElementLibrary({url: '${reloadedExternalLibraryUrl}'});\n`,
);
await browseElements.click();
await expect(
diff --git a/packages/example/remotion.config.ts b/packages/example/remotion.config.ts
index 1751343a07..00979089a0 100644
--- a/packages/example/remotion.config.ts
+++ b/packages/example/remotion.config.ts
@@ -10,4 +10,7 @@ Config.overrideBundlerConfig(async (config) => {
return bundlerOverride(config);
});
Config.setEnableCrossSiteIsolation(true);
-Config.addElementLibrary('https://remocn.dev/docs/typography', 'Remocn');
+Config.addElementLibrary({
+ url: 'https://remocn.dev/docs/typography',
+ displayName: 'Remocn',
+});