Skip to content

🎥 Make videos programmatically with React

Studio Protocol: Add isInsideStudio()

Igor Samokhovets6bcadfa40e32
diff --git a/packages/docs/docs/studio-protocol/component-library-integration.mdx b/packages/docs/docs/studio-protocol/component-library-integration.mdx
index 40d968062e..e3086948e0 100644
--- a/packages/docs/docs/studio-protocol/component-library-integration.mdx
+++ b/packages/docs/docs/studio-protocol/component-library-integration.mdx
@@ -85,6 +85,8 @@ Create one payload for both install actions. Run the actions in the browser.
- Let users click an Install in Studio button. Use [`installInStudio()`](/docs/studio-protocol/install-in-studio) for this action.
- Let users drag the component into Studio. Use [`setStudioDragData()`](/docs/studio-protocol/set-studio-drag-data) for this action.
+When Studio embeds the library through Browse Elements, use [`isInsideStudio()`](/docs/studio-protocol/is-inside-studio) to hide actions that are redundant inside the Studio iframe.
+
## Test the integration
- Compare the Player preview with the installed Element.
@@ -102,4 +104,5 @@ Create one payload for both install actions. Run the actions in the browser.
- [`createElementPayload()`](/docs/studio-protocol/create-element-payload)
- [`setStudioDragData()`](/docs/studio-protocol/set-studio-drag-data)
- [`installInStudio()`](/docs/studio-protocol/install-in-studio)
+- [`isInsideStudio()`](/docs/studio-protocol/is-inside-studio)
- [Studio Protocol security](/docs/studio-protocol/security)
diff --git a/packages/docs/docs/studio-protocol/is-inside-studio.mdx b/packages/docs/docs/studio-protocol/is-inside-studio.mdx
new file mode 100644
index 0000000000..84155e332c
--- /dev/null
+++ b/packages/docs/docs/studio-protocol/is-inside-studio.mdx
@@ -0,0 +1,48 @@
+---
+image: /generated/articles-docs-studio-protocol-is-inside-studio.png
+title: 'isInsideStudio()'
+crumb: '@remotion/studio-protocol'
+---
+
+# isInsideStudio()<AvailableFrom v="4.0.518" />
+
+Returns whether the current website is loaded in the Element library modal in Remotion Studio.
+
+Use it to adapt library UI that is redundant inside Studio, such as a "Drag into Studio" handle.
+
+## Example
+
+```tsx twoslash title="ElementActions.tsx"
+import {isInsideStudio} from '@remotion/studio-protocol';
+import {useLayoutEffect, useState} from 'react';
+
+export const ElementActions = () => {
+ const [insideStudio, setInsideStudio] = useState<boolean | null>(null);
+
+ useLayoutEffect(() => {
+ setInsideStudio(isInsideStudio());
+ }, []);
+
+ return insideStudio === false ? <button>Drag into Studio</button> : null;
+};
+```
+
+Starting with `null` prevents the action from briefly appearing before the browser check runs. On a top-level website, the action appears after the check.
+
+## Return value
+
+A boolean. It is `true` when the page has Studio's URL marker or is inside an iframe. The iframe check keeps the result true if client-side navigation removes the URL marker.
+
+It returns `false` outside a browser, including during server-side rendering.
+
+The result is a UI hint, not proof of Studio identity. Do not use it as a security boundary.
+
+## Compatibility
+
+<CompatibilityTable chrome firefox safari nodejs="" bun="" serverlessFunctions="" clientSideRendering={false} serverSideRendering={false} player={false} studio={false} hideServers />
+
+## See also
+
+- [Integrating a component library with Studio](/docs/studio-protocol/component-library-integration)
+- [`setStudioDragData()`](/docs/studio-protocol/set-studio-drag-data)
+- [Studio Protocol security](/docs/studio-protocol/security)
diff --git a/packages/docs/docs/studio-protocol/table-of-contents.tsx b/packages/docs/docs/studio-protocol/table-of-contents.tsx
index d9e60ef5c3..ad1bccf1b0 100644
--- a/packages/docs/docs/studio-protocol/table-of-contents.tsx
+++ b/packages/docs/docs/studio-protocol/table-of-contents.tsx
@@ -17,6 +17,10 @@ export const TableOfContents: React.FC = () => {
<strong>installInStudio()</strong>
<div>Request installation into the active Studio</div>
</TOCItem>
+ <TOCItem link="/docs/studio-protocol/is-inside-studio">
+ <strong>isInsideStudio()</strong>
+ <div>Check whether a library is embedded in Studio</div>
+ </TOCItem>
</Grid>
);
};
diff --git a/packages/docs/sidebars.ts b/packages/docs/sidebars.ts
index 3cc8ba80c2..bce204d435 100644
--- a/packages/docs/sidebars.ts
+++ b/packages/docs/sidebars.ts
@@ -825,6 +825,7 @@ const sidebars: SidebarsConfig = {
'studio-protocol/create-element-payload',
'studio-protocol/set-studio-drag-data',
'studio-protocol/install-in-studio',
+ 'studio-protocol/is-inside-studio',
'studio-protocol/security',
],
},
diff --git a/packages/docs/src/components/Elements/ElementPage.tsx b/packages/docs/src/components/Elements/ElementPage.tsx
index a12f89d538..5046119975 100644
--- a/packages/docs/src/components/Elements/ElementPage.tsx
+++ b/packages/docs/src/components/Elements/ElementPage.tsx
@@ -1,6 +1,7 @@
import Head from '@docusaurus/Head';
import {
installInStudio,
+ isInsideStudio,
setStudioDragData,
StudioProtocolInternals,
} from '@remotion/studio-protocol';
@@ -8,6 +9,7 @@ import React, {
useCallback,
useEffect,
useId,
+ useLayoutEffect,
useMemo,
useRef,
useState,
@@ -52,7 +54,9 @@ export const ElementPage: React.FC<ElementPageProps> = ({
const [isSourceVisible, setIsSourceVisible] = useState(false);
const [isBrowserStudioActionVisible, setIsBrowserStudioActionVisible] =
useState(false);
- const [isEmbeddedInStudio, setIsEmbeddedInStudio] = useState(false);
+ const [isEmbeddedInStudio, setIsEmbeddedInStudio] = useState<boolean | null>(
+ null,
+ );
const posterRef = useRef<HTMLImageElement>(null);
const sourceId = useId();
const {height: previewHeight, width: previewWidth} =
@@ -66,14 +70,11 @@ export const ElementPage: React.FC<ElementPageProps> = ({
return createElementPayloadFromDefinition({definition, sourceCode});
}, [definition, sourceCode]);
- useEffect(() => {
- // Internal navigation may drop the query parameter, but the page remains
- // inside the same Studio iframe.
- setIsEmbeddedInStudio(
- new URLSearchParams(window.location.search).get('remotion-studio') ===
- 'true' || window.parent !== window,
- );
+ useLayoutEffect(() => {
+ setIsEmbeddedInStudio(isInsideStudio());
+ }, []);
+ useEffect(() => {
const onKeyDown = (event: KeyboardEvent) => {
if (
event.repeat ||
@@ -235,7 +236,7 @@ export const ElementPage: React.FC<ElementPageProps> = ({
</PlainButton>
) : null}
</div>
- {isEmbeddedInStudio ? null : (
+ {isEmbeddedInStudio === false ? (
<div
className={styles.dragHandle}
draggable
@@ -255,7 +256,7 @@ export const ElementPage: React.FC<ElementPageProps> = ({
<strong>Drag into Studio</strong>
</span>
</div>
- )}
+ ) : null}
{installStatus.type === 'success' ||
installStatus.type === 'error' ? (
<p
diff --git a/packages/docs/src/data/articles.ts b/packages/docs/src/data/articles.ts
index e064a41a62..955ffb42b9 100644
--- a/packages/docs/src/data/articles.ts
+++ b/packages/docs/src/data/articles.ts
@@ -7039,6 +7039,15 @@ export const articles = [
noAi: false,
slug: 'studio-protocol/install-in-studio',
},
+ {
+ id: 'studio-protocol/is-inside-studio',
+ title: 'isInsideStudio()',
+ relativePath: 'docs/studio-protocol/is-inside-studio.mdx',
+ compId: 'articles-docs-studio-protocol-is-inside-studio',
+ crumb: '@remotion/studio-protocol',
+ noAi: false,
+ slug: 'studio-protocol/is-inside-studio',
+ },
{
id: 'studio-protocol/security',
title: 'Studio Protocol security',
diff --git a/packages/docs/static/generated/articles-docs-studio-protocol-is-inside-studio.png b/packages/docs/static/generated/articles-docs-studio-protocol-is-inside-studio.png
new file mode 100644
index 0000000000..613a6b52a1
Binary files /dev/null and b/packages/docs/static/generated/articles-docs-studio-protocol-is-inside-studio.png differ
diff --git a/packages/example/e2e/studio-protocol.test.mts b/packages/example/e2e/studio-protocol.test.mts
index 3dd04185c7..1f887ec13b 100644
--- a/packages/example/e2e/studio-protocol.test.mts
+++ b/packages/example/e2e/studio-protocol.test.mts
@@ -136,9 +136,11 @@ export const MyComponent = () => {
response.end(`<!doctype html>
<button id="install">Install in Studio</button>
<button id="license">Configure license in Studio</button>
+ <p id="environment"></p>
<p id="status"></p>
<script type="module">
- import {createElementPayload, installInStudio, StudioProtocolInternals} from '/protocol.js';
+ import {createElementPayload, installInStudio, isInsideStudio, StudioProtocolInternals} from '/protocol.js';
+ document.querySelector('#environment').textContent = isInsideStudio() ? 'Inside Remotion Studio' : 'Outside Remotion Studio';
const payload = createElementPayload({
displayName: 'Protocol Element',
slug: 'protocol-element',
@@ -287,6 +289,9 @@ export const MyComponent = () => {
const elementsFrame = studioPage.frameLocator(
`iframe[title="${externalLibraryLabel} library"]`,
);
+ await expect(
+ elementsFrame.getByText('Inside Remotion Studio', {exact: true}),
+ ).toBeVisible();
const installInStudio = elementsFrame.getByRole('button', {
name: 'Install in Studio',
});
@@ -321,6 +326,9 @@ export const MyComponent = () => {
await studioPage.mouse.click(500, 300);
const senderPage = await context.newPage();
await senderPage.goto(senderUrl);
+ await expect(
+ senderPage.getByText('Outside Remotion Studio', {exact: true}),
+ ).toBeVisible();
await senderPage
.getByRole('button', {name: 'Configure license in Studio'})
.click();
diff --git a/packages/studio-protocol/src/index.ts b/packages/studio-protocol/src/index.ts
index 61c407c6cf..c7387afc60 100644
--- a/packages/studio-protocol/src/index.ts
+++ b/packages/studio-protocol/src/index.ts
@@ -70,6 +70,7 @@ export {
type InstallInStudioErrorCode,
type InstallInStudioResult,
} from './install-in-studio';
+export {isInsideStudio} from './is-inside-studio';
export type {SfxDragData} from './sfx-drag-data';
export type {
StudioProtocolDescriptor,
diff --git a/packages/studio-protocol/src/is-inside-studio.ts b/packages/studio-protocol/src/is-inside-studio.ts
new file mode 100644
index 0000000000..18df3bff56
--- /dev/null
+++ b/packages/studio-protocol/src/is-inside-studio.ts
@@ -0,0 +1,16 @@
+export const isInsideStudio = (): boolean => {
+ if (typeof window === 'undefined') {
+ return false;
+ }
+
+ if (
+ new URLSearchParams(window.location.search).get('remotion-studio') ===
+ 'true'
+ ) {
+ return true;
+ }
+
+ // Client-side navigation may drop the query parameter while the library
+ // remains inside the same Studio iframe.
+ return window.parent !== window;
+};