Skip to content

🎥 Make videos programmatically with React

@remotion/browser-bundler: Add state-preserving Player Fast Refresh

Jonny Burger24e5dbc08b14
diff --git a/bun.lock b/bun.lock
index b901055630..124a1c3cdb 100644
--- a/bun.lock
+++ b/bun.lock
@@ -154,12 +154,14 @@
"version": "4.0.526",
"dependencies": {
"@rspack/browser": "2.1.1",
+ "react-refresh": "0.18.0",
"remotion": "workspace:*",
},
"devDependencies": {
"@happy-dom/global-registrator": "14.5.1",
"@remotion/eslint-config-internal": "workspace:*",
"@remotion/player": "workspace:*",
+ "@rspack/plugin-react-refresh": "1.6.1",
"@testing-library/react": "16.1.0",
"@types/react": "catalog:",
"@types/react-dom": "catalog:",
@@ -193,7 +195,6 @@
"@remotion/eslint-config-internal": "workspace:*",
"@remotion/studio": "workspace:*",
"@rspack/core": "1.7.11",
- "@rspack/plugin-react-refresh": "1.6.1",
"@types/react": "catalog:",
"@types/react-dom": "catalog:",
"@typescript/native-preview": "catalog:",
@@ -1476,6 +1477,7 @@
"next": "catalog:",
"react": "catalog:",
"react-dom": "catalog:",
+ "react-refresh": "0.18.0",
"remotion": "workspace:*",
},
"devDependencies": {
diff --git a/packages/browser-bundler/bundle.ts b/packages/browser-bundler/bundle.ts
index 1537d79f56..d742748dc6 100644
--- a/packages/browser-bundler/bundle.ts
+++ b/packages/browser-bundler/bundle.ts
@@ -1,3 +1,4 @@
+import {readFileSync} from 'node:fs';
import path from 'node:path';
import {fileURLToPath} from 'node:url';
import {build} from 'bun';
@@ -8,7 +9,23 @@ if (process.env.NODE_ENV !== 'production') {
throw new Error('This script must be run using NODE_ENV=production');
}
+const refreshRuntimePath = fileURLToPath(
+ import.meta.resolve('@rspack/plugin-react-refresh/react-refresh'),
+);
const define = {
+ __BROWSER_BUNDLER_REACT_REFRESH_FILES__: JSON.stringify({
+ entry: readFileSync(
+ new URL(
+ import.meta.resolve('@rspack/plugin-react-refresh/react-refresh-entry'),
+ ),
+ 'utf-8',
+ ),
+ runtime: readFileSync(refreshRuntimePath, 'utf-8'),
+ utils: readFileSync(
+ path.join(path.dirname(refreshRuntimePath), 'refreshUtils.js'),
+ 'utf-8',
+ ),
+ }),
__BROWSER_BUNDLER_DEPENDENCY_VERSIONS__: JSON.stringify({
react: rootPackage.workspaces.catalog.react,
'react-dom': rootPackage.workspaces.catalog['react-dom'],
@@ -29,6 +46,7 @@ const output = await build({
'react-dom/client',
'react/jsx-runtime',
'react/jsx-dev-runtime',
+ 'react-refresh/runtime',
'remotion',
'remotion/no-react',
'remotion/version',
diff --git a/packages/browser-bundler/package.json b/packages/browser-bundler/package.json
index f9a084e128..8c0c65b4b1 100644
--- a/packages/browser-bundler/package.json
+++ b/packages/browser-bundler/package.json
@@ -25,6 +25,7 @@
},
"dependencies": {
"@rspack/browser": "2.1.1",
+ "react-refresh": "0.18.0",
"remotion": "workspace:*"
},
"peerDependencies": {
@@ -50,6 +51,7 @@
"./package.json": "./package.json"
},
"devDependencies": {
+ "@rspack/plugin-react-refresh": "1.6.1",
"@happy-dom/global-registrator": "14.5.1",
"@remotion/eslint-config-internal": "workspace:*",
"@remotion/player": "workspace:*",
diff --git a/packages/browser-bundler/src/browser-bundler-worker.ts b/packages/browser-bundler/src/browser-bundler-worker.ts
index 9bbfef1c3c..0580a7051b 100644
--- a/packages/browser-bundler/src/browser-bundler-worker.ts
+++ b/packages/browser-bundler/src/browser-bundler-worker.ts
@@ -5,7 +5,16 @@ import {
} from './create-browser-compiler';
import {createBrowserDependencyPlugin} from './dependency-resolution';
import {BrowserBundlerError, serializeCompilerError} from './errors';
+import {
+ browserBundleHmrBridgeName,
+ browserBundleHotUpdateName,
+} from './fast-refresh-bridge';
+import {
+ createBrowserHmrRuntimePlugin,
+ createBrowserReactRefreshPlugin,
+} from './hmr-plugins';
import {makeBrowserHttpClient} from './http-client';
+import {getBrowserReactRefreshVirtualFiles} from './refresh-virtual-files';
import type {
BrowserBundlerWorkerRequest,
BrowserBundlerWorkerResponse,
@@ -27,8 +36,17 @@ const sharedModules = [
let compiler: BrowserCompiler | null = null;
let previousProject: BrowserCompilerProject | null = null;
+let previousHash: string | null = null;
+let sessionId: string | null = null;
let queue: Promise<void> = Promise.resolve();
+const refreshPaths = {
+ entry: '/__remotion_browser_bundler__/refresh-entry.js',
+ runtime: '/__remotion_browser_bundler__/refresh-runtime.js',
+ utils: '/__remotion_browser_bundler__/refreshUtils.js',
+};
+const hotEntry = '/__remotion_browser_bundler__/hot-entry.js';
+
const postResponse = (response: BrowserBundlerWorkerResponse) => {
self.postMessage(response);
};
@@ -43,6 +61,8 @@ self.addEventListener(
...request.project,
rootDir: '/',
};
+ const {enableFastRefresh} = request;
+ const entryPoint = normalizeVirtualPath(project.entryPoint);
if (
compiler &&
(previousProject?.rootDir !== project.rootDir ||
@@ -52,9 +72,30 @@ self.addEventListener(
compiler = null;
}
+ if (compiler === null) {
+ previousHash = null;
+ sessionId = crypto.randomUUID();
+ }
+
compiler ??= await createBrowserCompiler({
project,
- virtualFiles: {},
+ virtualFiles: enableFastRefresh
+ ? {
+ ...getBrowserReactRefreshVirtualFiles(refreshPaths),
+ [hotEntry]: `
+globalThis[${JSON.stringify(browserBundleHmrBridgeName)}].setHotRuntime({
+ check: () => module.hot.check(false),
+ apply: () => module.hot.apply(),
+ getHash: () => __webpack_hash__,
+ status: () => module.hot.status(),
+});
+require(${JSON.stringify(entryPoint)});
+module.hot.accept(${JSON.stringify(entryPoint)}, () => {
+ require(${JSON.stringify(entryPoint)});
+});
+`,
+ }
+ : {},
onProgress: (progress) =>
postResponse({type: 'progress', ...progress}),
configure: (rspack) => ({
@@ -64,7 +105,9 @@ self.addEventListener(
entry: {
bundle: {
asyncChunks: false,
- import: [normalizeVirtualPath(project.entryPoint)],
+ import: enableFastRefresh
+ ? [refreshPaths.entry, hotEntry]
+ : [entryPoint],
},
},
experiments: {
@@ -75,11 +118,26 @@ self.addEventListener(
},
},
externals: Object.fromEntries(
- sharedModules.map((name) => [name, `commonjs ${name}`]),
+ [
+ ...sharedModules,
+ ...(enableFastRefresh ? ['react-refresh/runtime'] : []),
+ ].map((name) => [name, `commonjs ${name}`]),
),
module: {
rules: [
{parser: {worker: false}, test: /\.[cm]?[jt]sx?$/},
+ ...(enableFastRefresh
+ ? [
+ {
+ exclude: [
+ /node_modules/,
+ /__remotion_browser_bundler__/,
+ ],
+ test: /\.[jt]sx?$/,
+ use: [{loader: 'builtin:react-refresh-loader'}],
+ },
+ ]
+ : []),
{
test: /\.[jt]sx?$/,
use: [
@@ -91,8 +149,8 @@ self.addEventListener(
parser: {syntax: 'typescript', tsx: true},
transform: {
react: {
- // jsxDEV is unavailable in production React.
- development: false,
+ development: enableFastRefresh,
+ refresh: enableFastRefresh,
runtime: 'automatic',
},
},
@@ -103,19 +161,48 @@ self.addEventListener(
},
],
},
- optimization: {runtimeChunk: false, splitChunks: false},
+ optimization: {
+ emitOnErrors: !enableFastRefresh,
+ runtimeChunk: false,
+ splitChunks: false,
+ },
output: {
+ chunkFilename: '[name].js',
+ chunkFormat: 'array-push',
+ chunkLoading: 'jsonp',
filename: 'bundle.js',
path: '/dist',
publicPath: '',
hashFunction: 'xxhash64',
uniqueName: 'remotion-browser-bundler',
+ ...(enableFastRefresh
+ ? {hotUpdateGlobal: browserBundleHotUpdateName}
+ : {}),
},
plugins: [
+ ...(enableFastRefresh
+ ? [
+ createBrowserReactRefreshPlugin({
+ rspack,
+ refreshRuntime: refreshPaths.runtime,
+ refreshUtils: refreshPaths.utils,
+ }),
+ new rspack.HotModuleReplacementPlugin(),
+ createBrowserHmrRuntimePlugin({
+ rspack,
+ bridgeName: browserBundleHmrBridgeName,
+ }),
+ ]
+ : []),
createBrowserDependencyPlugin({
rspack,
- development: false,
- external: ['react', 'react-dom', 'remotion'],
+ development: enableFastRefresh,
+ external: [
+ 'react',
+ 'react-dom',
+ 'remotion',
+ ...(enableFastRefresh ? ['react-refresh'] : []),
+ ],
resolvedUrls: {},
resolvedVersions: {
...__BROWSER_BUNDLER_DEPENDENCY_VERSIONS__,
@@ -137,11 +224,30 @@ self.addEventListener(
);
}
+ if (enableFastRefresh && (!result.hash || sessionId === null)) {
+ throw new Error('Rspack did not return a Fast Refresh build hash.');
+ }
+
postResponse({
type: 'bundle',
id: request.id,
- bundle: {code: result.bundle, warnings: result.warnings},
+ bundle: {
+ code: result.bundle,
+ warnings: result.warnings,
+ fastRefresh:
+ enableFastRefresh && result.hash && sessionId !== null
+ ? {
+ sessionId,
+ hash: result.hash,
+ previousHash,
+ assets: result.assets.filter((asset) =>
+ asset.name.includes('.hot-update.'),
+ ),
+ }
+ : null,
+ },
});
+ previousHash = result.hash ?? null;
} catch (error) {
postResponse({
type: 'error',
diff --git a/packages/browser-bundler/src/browser-module-scope.ts b/packages/browser-bundler/src/browser-module-scope.ts
new file mode 100644
index 0000000000..6bc3d56ba0
--- /dev/null
+++ b/packages/browser-bundler/src/browser-module-scope.ts
@@ -0,0 +1,88 @@
+import * as React from 'react';
+import * as ReactDOM from 'react-dom';
+import * as ReactDOMClient from 'react-dom/client';
+import * as JSXDevRuntime from 'react/jsx-dev-runtime';
+import * as JSXRuntime from 'react/jsx-runtime';
+import * as Remotion from 'remotion';
+import * as RemotionNoReact from 'remotion/no-react';
+import * as RemotionVersion from 'remotion/version';
+
+export const createBrowserModuleScope = (
+ additionalModules: ReadonlyMap<string, unknown> | null,
+) => {
+ let root: React.FC | null = null;
+ let registrations = 0;
+ const registerRoot = (component: React.FC) => {
+ if (
+ !component ||
+ React.isValidElement(component) ||
+ (typeof component !== 'function' &&
+ (typeof component !== 'object' || !('$$typeof' in component)))
+ ) {
+ throw new Error('registerRoot() must receive a React component.');
+ }
+
+ if (registrations > 0) {
+ throw new Error('registerRoot() was called more than once.');
+ }
+
+ registrations++;
+ root = component;
+ };
+
+ const sharedModules = new Map<string, unknown>([
+ ['react', React],
+ ['react-dom', ReactDOM],
+ ['react-dom/client', ReactDOMClient],
+ ['react/jsx-runtime', JSXRuntime],
+ ['react/jsx-dev-runtime', JSXDevRuntime],
+ ['remotion', {...Remotion, registerRoot}],
+ ['remotion/no-react', RemotionNoReact],
+ ['remotion/version', RemotionVersion],
+ ...(additionalModules ?? []),
+ ]);
+
+ const resolveModule = (id: string) => {
+ if (!sharedModules.has(id)) {
+ throw new Error(
+ `The browser bundle requested an unavailable shared module: "${id}".`,
+ );
+ }
+
+ return sharedModules.get(id);
+ };
+
+ return {
+ resolveModule,
+ beginUpdate: () => {
+ registrations = 0;
+ },
+ getRoot: (): React.FC => {
+ if (root === null) {
+ throw new Error(
+ 'The browser bundle did not call registerRoot(). Use a normal Remotion project entry point.',
+ );
+ }
+
+ return root;
+ },
+ evaluate: (code: string) => {
+ registrations = 0;
+ try {
+ // eslint-disable-next-line no-new-func
+ const evaluate = new Function(
+ 'require',
+ `${code}\n//# sourceURL=remotion-browser-bundle.js`,
+ );
+ evaluate(resolveModule);
+ } catch (error) {
+ throw new Error(
+ `Could not evaluate the browser bundle: ${
+ error instanceof Error ? error.message : String(error)
+ }`,
+ {cause: error},
+ );
+ }
+ },
+ };
+};
diff --git a/packages/browser-bundler/src/compiler.ts b/packages/browser-bundler/src/compiler.ts
index 31b26881f1..220ad57727 100644
--- a/packages/browser-bundler/src/compiler.ts
+++ b/packages/browser-bundler/src/compiler.ts
@@ -5,7 +5,17 @@ export {
type BrowserCompilerResult,
} from './create-browser-compiler';
export {createBrowserDependencyPlugin} from './dependency-resolution';
+export {
+ createBrowserHmrAssetManager,
+ type BrowserHmrAsset,
+ type BrowserHmrBridge,
+} from './hmr-assets';
+export {
+ createBrowserHmrRuntimePlugin,
+ createBrowserReactRefreshPlugin,
+} from './hmr-plugins';
export {makeBrowserHttpClient} from './http-client';
+export {getBrowserReactRefreshVirtualFiles} from './refresh-virtual-files';
export {
getVirtualProjectChanges,
getVirtualProjectFiles,
diff --git a/packages/browser-bundler/src/create-browser-bundle-runtime.ts b/packages/browser-bundler/src/create-browser-bundle-runtime.ts
new file mode 100644
index 0000000000..991252219c
--- /dev/null
+++ b/packages/browser-bundler/src/create-browser-bundle-runtime.ts
@@ -0,0 +1,235 @@
+import type {FC} from 'react';
+import {Internals} from 'remotion';
+import {createBrowserModuleScope} from './browser-module-scope';
+import {
+ browserBundleHmrBridgeName,
+ browserBundleHotUpdateName,
+ type BrowserBundleHotRuntime,
+} from './fast-refresh-bridge';
+import {createBrowserHmrAssetManager} from './hmr-assets';
+import type {BrowserBundle} from './types';
+
+export type BrowserBundleRuntime = {
+ applyBundle: (bundle: BrowserBundle) => Promise<FC>;
+ dispose: () => void;
+};
+
+export const createBrowserBundleRuntime = (): BrowserBundleRuntime => {
+ if (typeof document === 'undefined' || !document.body) {
+ throw new Error(
+ 'createBrowserBundleRuntime() must be called in a browser.',
+ );
+ }
+
+ if (Object.hasOwn(globalThis, browserBundleHmrBridgeName)) {
+ throw new Error(
+ 'Only one Fast Refresh runtime can use a preview document.',
+ );
+ }
+
+ const assets = createBrowserHmrAssetManager({
+ createObjectUrl: (blob) => URL.createObjectURL(blob),
+ revokeObjectUrl: (url) => URL.revokeObjectURL(url),
+ });
+ let hotRuntime: BrowserBundleHotRuntime | null = null;
+ let scope: ReturnType<typeof createBrowserModuleScope> | null = null;
+ let sessionId: string | null = null;
+ let disposed = false;
+ let ownsComponentIdentityResolver = false;
+ let queue: Promise<void> = Promise.resolve();
+ const previousRequire = Object.getOwnPropertyDescriptor(
+ globalThis,
+ 'require',
+ );
+ const previousHotUpdate = Object.getOwnPropertyDescriptor(
+ globalThis,
+ browserBundleHotUpdateName,
+ );
+ const bridge = {
+ ...assets.bridge,
+ setHotRuntime: (runtime: BrowserBundleHotRuntime) => {
+ hotRuntime = runtime;
+ },
+ };
+ Object.defineProperty(globalThis, browserBundleHmrBridgeName, {
+ configurable: true,
+ value: bridge,
+ });
+
+ const getHotRuntime = (): BrowserBundleHotRuntime => {
+ if (hotRuntime === null) {
+ throw new Error('The browser bundle did not initialize its HMR runtime.');
+ }
+
+ return hotRuntime;
+ };
+
+ return {
+ applyBundle: (bundle) => {
+ const run = queue.then(async () => {
+ if (disposed) {
+ throw new Error('The browser bundle runtime was disposed.');
+ }
+
+ const update = bundle.fastRefresh;
+ if (!update) {
+ throw new Error(
+ 'Create the bundler with enableFastRefresh: true before applying bundles.',
+ );
+ }
+
+ if (sessionId !== null && sessionId !== update.sessionId) {
+ throw new Error(
+ 'The compiler session changed. Create a new preview runtime for the new project.',
+ );
+ }
+
+ // Keep React Refresh out of production hosts using the one-shot loader.
+ const {default: refresh} = await import('react-refresh/runtime');
+ if (disposed) {
+ throw new Error('The browser bundle runtime was disposed.');
+ }
+
+ if (typeof refresh.performReactRefresh !== 'function') {
+ throw new Error(
+ 'Fast Refresh requires a development React renderer in the preview document.',
+ );
+ }
+
+ if (scope === null) {
+ const hook: unknown = Reflect.get(
+ globalThis,
+ '__REACT_DEVTOOLS_GLOBAL_HOOK__',
+ );
+ if (
+ hook === null ||
+ typeof hook !== 'object' ||
+ !('renderers' in hook) ||
+ !(hook.renderers instanceof Map) ||
+ ('isDisabled' in hook && hook.isDisabled)
+ ) {
+ throw new Error(
+ 'Inject the React Refresh hook before importing the development preview renderer.',
+ );
+ }
+
+ // Refresh's own hook tracks renderers privately. Its public map
+ // is populated only when React DevTools supplies the hook.
+ const renderers: unknown[] = [...hook.renderers.values()];
+ if (
+ renderers.length > 0 &&
+ !renderers.some(
+ (renderer) =>
+ renderer !== null &&
+ typeof renderer === 'object' &&
+ 'scheduleRefresh' in renderer &&
+ typeof renderer.scheduleRefresh === 'function' &&
+ 'setRefreshHandler' in renderer &&
+ typeof renderer.setRefreshHandler === 'function',
+ )
+ ) {
+ throw new Error(
+ 'Fast Refresh requires development React DOM. Inject the React Refresh hook before importing the preview renderer.',
+ );
+ }
+
+ const initialScope = createBrowserModuleScope(
+ new Map([['react-refresh/runtime', refresh]]),
+ );
+ Internals.setComponentIdentityResolver(
+ (component) => refresh.getFamilyByType(component) ?? component,
+ );
+ ownsComponentIdentityResolver = true;
+ Object.defineProperty(globalThis, 'require', {
+ configurable: true,
+ value: initialScope.resolveModule,
+ });
+ initialScope.evaluate(bundle.code);
+ initialScope.getRoot();
+ scope = initialScope;
+ sessionId = update.sessionId;
+ } else {
+ const hot = getHotRuntime();
+ if (hot.getHash() === update.hash) {
+ return scope.getRoot();
+ }
+
+ if (hot.getHash() !== update.previousHash) {
+ throw new Error(
+ 'Fast Refresh bundles must be applied in compilation order. A compiled update was skipped.',
+ );
+ }
+
+ if (hot.status() !== 'idle') {
+ throw new Error(
+ `Cannot apply a Fast Refresh update while HMR is "${hot.status()}".`,
+ );
+ }
+
+ assets.updateAssets(update.assets);
+ scope.beginUpdate();
+ const changedModules = await hot.check();
+ if (disposed) {
+ throw new Error('The browser bundle runtime was disposed.');
+ }
+
+ if (changedModules === null) {
+ throw new Error('Rspack could not find the Fast Refresh update.');
+ }
+
+ await hot.apply();
+ if (disposed) {
+ throw new Error('The browser bundle runtime was disposed.');
+ }
+
+ refresh.performReactRefresh();
+ }
+
+ if (disposed) {
+ throw new Error('The browser bundle runtime was disposed.');
+ }
+
+ if (getHotRuntime().getHash() !== update.hash) {
+ throw new Error(
+ 'Rspack did not apply the expected Fast Refresh update.',
+ );
+ }
+
+ return scope.getRoot();
+ });
+ queue = run.then(
+ () => undefined,
+ () => undefined,
+ );
+ return run;
+ },
+ dispose: () => {
+ if (disposed) {
+ return;
+ }
+
+ disposed = true;
+ if (ownsComponentIdentityResolver) {
+ Internals.setComponentIdentityResolver(null);
+ }
+
+ assets.dispose();
+ Reflect.deleteProperty(globalThis, browserBundleHmrBridgeName);
+ if (previousRequire) {
+ Object.defineProperty(globalThis, 'require', previousRequire);
+ } else {
+ Reflect.deleteProperty(globalThis, 'require');
+ }
+
+ if (previousHotUpdate) {
+ Object.defineProperty(
+ globalThis,
+ browserBundleHotUpdateName,
+ previousHotUpdate,
+ );
+ } else {
+ Reflect.deleteProperty(globalThis, browserBundleHotUpdateName);
+ }
+ },
+ };
+};
diff --git a/packages/browser-bundler/src/create-browser-bundler.ts b/packages/browser-bundler/src/create-browser-bundler.ts
index dca18101c5..2e8baa107c 100644
--- a/packages/browser-bundler/src/create-browser-bundler.ts
+++ b/packages/browser-bundler/src/create-browser-bundler.ts
@@ -26,6 +26,7 @@ export const createBrowserBundler = (
type: 'module',
});
const dependencyVersions = {...options.dependencyVersions};
+ const enableFastRefresh = options.enableFastRefresh ?? false;
const pending = new Map<
number,
{
@@ -97,6 +98,7 @@ export const createBrowserBundler = (
id,
project,
dependencyVersions,
+ enableFastRefresh,
} satisfies BrowserBundlerWorkerRequest);
} catch (error) {
pending.delete(id);
diff --git a/packages/browser-bundler/src/create-browser-composition-observer.tsx b/packages/browser-bundler/src/create-browser-composition-observer.tsx
new file mode 100644
index 0000000000..d2cea13720
--- /dev/null
+++ b/packages/browser-bundler/src/create-browser-composition-observer.tsx
@@ -0,0 +1,318 @@
+import React, {Suspense, useEffect, useMemo, useState} from 'react';
+import {createRoot} from 'react-dom/client';
+import type {AnyComposition} from 'remotion';
+import {Internals} from 'remotion';
+import type {BrowserComposition} from './get-browser-composition';
+
+export type BrowserCompositionSelection = {
+ readonly root: React.FC;
+ readonly compositionId: string;
+ readonly inputProps: Record<string, unknown>;
+};
+
+export type BrowserCompositionObserver = {
+ update: (selection: BrowserCompositionSelection) => void;
+ dispose: () => void;
+};
+
+const environment: React.ContextType<
+ typeof Internals.RemotionEnvironmentContext
+> = {
+ isClientSideRendering: false,
+ isPlayer: false,
+ isReadOnlyStudio: false,
+ isRendering: false,
+ isStudio: false,
+};
+
+type RegistrationProps = {
+ readonly children: React.ReactNode;
+ readonly revision: number;
+ readonly onError: (error: unknown, revision: number) => void;
+};
+
+class RegistrationErrorBoundary extends React.Component<
+ RegistrationProps,
+ {failed: boolean; revision: number}
+> {
+ state = {failed: false, revision: this.props.revision};
+
+ static getDerivedStateFromProps(
+ props: RegistrationProps,
+ state: {failed: boolean; revision: number},
+ ) {
+ return props.revision === state.revision
+ ? null
+ : {failed: false, revision: props.revision};
+ }
+
+ static getDerivedStateFromError() {
+ return {failed: true};
+ }
+
+ componentDidCatch(error: Error) {
+ this.props.onError(error, this.props.revision);
+ }
+
+ render() {
+ return this.state.failed ? null : this.props.children;
+ }
+}
+
+const RegistrationCommitted: React.FC<{
+ readonly revision: number;
+ readonly onCommit: (revision: number) => void;
+}> = ({revision, onCommit}) => {
+ useEffect(() => onCommit(revision), [onCommit, revision]);
+ return null;
+};
+
+const ObserveMetadata: React.FC<{
+ readonly composition: AnyComposition | null;
+ readonly compositionId: string;
+ readonly inputProps: Record<string, unknown>;
+ readonly revision: number;
+ readonly registeredRevision: number | null;
+ readonly onChange: (
+ composition: BrowserComposition,
+ revision: number,
+ ) => void;
+ readonly onError: (error: unknown, revision: number) => void;
+}> = ({
+ composition,
+ compositionId,
+ inputProps,
+ revision,
+ registeredRevision,
+ onChange,
+ onError,
+}) => {
+ useEffect(() => {
+ if (registeredRevision !== revision) {
+ return;
+ }
+
+ if (!composition) {
+ onError(
+ new Error(`No composition with ID "${compositionId}" is registered.`),
+ revision,
+ );
+ return;
+ }
+
+ const controller = new AbortController();
+ const defaultProps = composition.defaultProps ?? {};
+ try {
+ const config = Internals.resolveVideoConfig({
+ compositionId,
+ compositionWidth: composition.width ?? null,
+ compositionHeight: composition.height ?? null,
+ compositionFps: composition.fps ?? null,
+ compositionDurationInFrames: composition.durationInFrames ?? null,
+ calculateMetadata: composition.calculateMetadata,
+ defaultProps,
+ inputProps: {...defaultProps, ...inputProps},
+ signal: controller.signal,
+ });
+ Promise.resolve(config).then(
+ (videoConfig) => {
+ if (!controller.signal.aborted) {
+ onChange(
+ {...videoConfig, component: composition.component},
+ revision,
+ );
+ }
+ },
+ (error: unknown) => {
+ if (!controller.signal.aborted) {
+ onError(error, revision);
+ }
+ },
+ );
+ } catch (error) {
+ onError(error, revision);
+ }
+
+ return () => controller.abort();
+ }, [
+ composition,
+ compositionId,
+ inputProps,
+ onChange,
+ onError,
+ registeredRevision,
+ revision,
+ ]);
+
+ return null;
+};
+
+const ObserveComposition: React.FC<
+ BrowserCompositionSelection & {
+ readonly revision: number;
+ readonly onChange: (
+ composition: BrowserComposition,
+ revision: number,
+ ) => void;
+ readonly onError: (error: unknown, revision: number) => void;
+ }
+> = ({
+ root: RegisteredRoot,
+ compositionId,
+ inputProps,
+ revision,
+ onChange,
+ onError,
+}) => {
+ const [registeredRevision, setRegisteredRevision] = useState<number | null>(
+ null,
+ );
+ const [compositions, setCompositions] = useState<AnyComposition[]>([]);
+ const setters = useMemo<
+ React.ContextType<typeof Internals.CompositionSetters>
+ >(
+ () => ({
+ registerComposition: (composition) => {
+ setCompositions((current) => {
+ if (current.some(({id}) => id === composition.id)) {
+ throw new Error(
+ `A composition with ID "${composition.id}" was registered more than once.`,
+ );
+ }
+
+ return [...current, composition as AnyComposition];
+ });
+ },
+ unregisterComposition: (id) => {
+ setCompositions((current) =>
+ current.filter((composition) => composition.id !== id),
+ );
+ },
+ registerFolder: () => undefined,
+ unregisterFolder: () => undefined,
+ setCanvasContent: () => undefined,
+ setCurrentAssetMetadata: () => undefined,
+ onlyRenderComposition: null,
+ }),
+ [],
+ );
+ // Registry changes must not rerender Root and trigger another registration.
+ const registration = useMemo(
+ () => (
+ <Suspense fallback={null}>
+ <RegisteredRoot />
+ <RegistrationCommitted
+ revision={revision}
+ onCommit={setRegisteredRevision}
+ />
+ </Suspense>
+ ),
+ [RegisteredRoot, revision],
+ );
+
+ return (
+ <Internals.RemotionEnvironmentContext.Provider value={environment}>
+ <Internals.CompositionSetters.Provider value={setters}>
+ {registration}
+ <ObserveMetadata
+ composition={
+ compositions.find(({id}) => id === compositionId) ?? null
+ }
+ compositionId={compositionId}
+ inputProps={inputProps}
+ revision={revision}
+ registeredRevision={registeredRevision}
+ onChange={onChange}
+ onError={onError}
+ />
+ </Internals.CompositionSetters.Provider>
+ </Internals.RemotionEnvironmentContext.Provider>
+ );
+};
+
+export const createBrowserCompositionObserver = ({
+ onChange,
+ onError,
+}: {
+ onChange: (composition: BrowserComposition) => void;
+ onError: (error: Error) => void;
+}): BrowserCompositionObserver => {
+ if (typeof document === 'undefined' || !document.body) {
+ throw new Error('Composition observation requires a browser document.');
+ }
+
+ const container = document.createElement('div');
+ container.hidden = true;
+ document.body.appendChild(container);
+ let disposed = false;
+ let revision = 0;
+ let lastError: {error: unknown; revision: number} | null = null;
+ const reportError = (error: unknown, errorRevision: number) => {
+ if (!disposed && errorRevision === revision) {
+ if (
+ lastError !== null &&
+ lastError.error === error &&
+ lastError.revision === errorRevision
+ ) {
+ return;
+ }
+
+ lastError = {error, revision: errorRevision};
+ onError(error instanceof Error ? error : new Error(String(error)));
+ }
+ };
+
+ const onComposition = (
+ composition: BrowserComposition,
+ resolvedRevision: number,
+ ) => {
+ if (disposed || resolvedRevision !== revision) {
+ return;
+ }
+
+ try {
+ onChange(composition);
+ } catch (error) {
+ reportError(error, resolvedRevision);
+ }
+ };
+
+ const root = createRoot(container, {
+ onCaughtError: (error) => reportError(error, revision),
+ onUncaughtError: (error) => reportError(error, revision),
+ });
+
+ return {
+ update: (selection) => {
+ if (disposed) {
+ throw new Error('The composition observer was disposed.');
+ }
+
+ revision++;
+ // Composition owns the stable wrapper used by the Player. Unmounting
+ // registration between updates would also reset the video's state.
+ root.render(
+ <RegistrationErrorBoundary revision={revision} onError={reportError}>
+ <ObserveComposition
+ {...selection}
+ revision={revision}
+ onChange={onComposition}
+ onError={reportError}
+ />
+ </RegistrationErrorBoundary>,
+ );
+ },
+ dispose: () => {
+ if (disposed) {
+ return;
+ }
+
+ disposed = true;
+ try {
+ root.unmount();
+ } finally {
+ container.remove();
+ }
+ },
+ };
+};
diff --git a/packages/browser-bundler/src/fast-refresh-bridge.ts b/packages/browser-bundler/src/fast-refresh-bridge.ts
new file mode 100644
index 0000000000..c78e2dcedc
--- /dev/null
+++ b/packages/browser-bundler/src/fast-refresh-bridge.ts
@@ -0,0 +1,9 @@
+export const browserBundleHmrBridgeName = 'remotion_browserBundlerHmr';
+export const browserBundleHotUpdateName = 'remotion_browserBundlerHotUpdate';
+
+export type BrowserBundleHotRuntime = {
+ check: () => Promise<(string | number)[] | null>;
+ apply: () => Promise<(string | number)[]>;
+ getHash: () => string;
+ status: () => string;
+};
diff --git a/packages/browser-bundler/src/hmr-assets.ts b/packages/browser-bundler/src/hmr-assets.ts
new file mode 100644
index 0000000000..1faf2ecae7
--- /dev/null
+++ b/packages/browser-bundler/src/hmr-assets.ts
@@ -0,0 +1,88 @@
+export type BrowserHmrAsset = {
+ name: string;
+ content: string;
+};
+
+export type BrowserHmrBridge = {
+ getManifest: (name: string) => Promise<object | undefined>;
+ resolveScriptUrl: (name: string) => string;
+};
+
+const getAssetName = (nameOrUrl: string) => {
+ const url = new URL(nameOrUrl, 'https://remotion.invalid');
+ return url.pathname.split('/').at(-1) ?? '';
+};
+
+export const createBrowserHmrAssetManager = ({
+ createObjectUrl,
+ revokeObjectUrl,
+}: {
+ createObjectUrl: (blob: Blob) => string;
+ revokeObjectUrl: (url: string) => void;
+}) => {
+ const assets = new Map<string, {content: string; objectUrl: string | null}>();
+
+ const updateAssets = (newAssets: BrowserHmrAsset[]) => {
+ const nextAssetNames = new Set(
+ newAssets.map((asset) => getAssetName(asset.name)),
+ );
+ for (const [name, asset] of assets) {
+ if (nextAssetNames.has(name)) {
+ continue;
+ }
+
+ if (asset.objectUrl) {
+ revokeObjectUrl(asset.objectUrl);
+ }
+
+ assets.delete(name);
+ }
+
+ for (const asset of newAssets) {
+ const name = getAssetName(asset.name);
+ const previous = assets.get(name);
+ if (previous?.objectUrl) {
+ revokeObjectUrl(previous.objectUrl);
+ }
+
+ assets.set(name, {content: asset.content, objectUrl: null});
+ }
+ };
+
+ const bridge: BrowserHmrBridge = {
+ getManifest: (name) => {
+ const asset = assets.get(getAssetName(name));
+ if (!asset) {
+ return Promise.resolve(undefined);
+ }
+
+ return Promise.resolve(JSON.parse(asset.content) as object);
+ },
+ resolveScriptUrl: (name) => {
+ const assetName = getAssetName(name);
+ const asset = assets.get(assetName);
+ if (!asset) {
+ throw new Error(`Missing browser HMR asset: ${assetName}`);
+ }
+
+ asset.objectUrl ??= createObjectUrl(
+ new Blob([asset.content], {type: 'text/javascript'}),
+ );
+ return asset.objectUrl;
+ },
+ };
+
+ return {
+ bridge,
+ dispose: () => {
+ for (const asset of assets.values()) {
+ if (asset.objectUrl) {
+ revokeObjectUrl(asset.objectUrl);
+ }
+ }
+
+ assets.clear();
+ },
+ updateAssets,
+ };
+};
diff --git a/packages/browser-bundler/src/hmr-plugins.ts b/packages/browser-bundler/src/hmr-plugins.ts
new file mode 100644
index 0000000000..8a776c1459
--- /dev/null
+++ b/packages/browser-bundler/src/hmr-plugins.ts
@@ -0,0 +1,88 @@
+import type * as RspackBrowser from '@rspack/browser';
+
+export const createBrowserReactRefreshPlugin = ({
+ rspack,
+ refreshRuntime,
+ refreshUtils,
+}: {
+ rspack: typeof RspackBrowser;
+ refreshRuntime: string;
+ refreshUtils: string;
+}): RspackBrowser.RspackPluginInstance => ({
+ name: 'remotion-browser-react-refresh',
+ apply: (compiler) => {
+ new rspack.ProvidePlugin({
+ $ReactRefreshRuntime$: refreshRuntime,
+ __react_refresh_utils__: refreshUtils,
+ }).apply(compiler);
+ new rspack.DefinePlugin({
+ __react_refresh_error_overlay__: false,
+ __react_refresh_library__: JSON.stringify('remotion-browser'),
+ __react_refresh_socket__: false,
+ __reload_on_runtime_errors__: false,
+ }).apply(compiler);
+
+ compiler.hooks.compilation.tap(
+ 'remotion-browser-react-refresh',
+ (compilation) => {
+ compilation.hooks.additionalTreeRuntimeRequirements.tap(
+ 'remotion-browser-react-refresh',
+ (_chunk, runtimeRequirements) => {
+ runtimeRequirements.add(rspack.RuntimeGlobals.moduleCache);
+ },
+ );
+ },
+ );
+ },
+});
+
+export const createBrowserHmrRuntimePlugin = ({
+ rspack,
+ bridgeName,
+}: {
+ rspack: typeof RspackBrowser;
+ bridgeName: string;
+}): RspackBrowser.RspackPluginInstance => {
+ const bridge = `globalThis[${JSON.stringify(bridgeName)}]`;
+ class BrowserHmrManifestRuntimeModule extends rspack.RuntimeModule {
+ constructor() {
+ super(
+ 'remotion browser hmr manifest',
+ rspack.RuntimeModule.STAGE_TRIGGER,
+ );
+ }
+
+ generate() {
+ return `${rspack.RuntimeGlobals.hmrDownloadManifest} = function() {
+ return ${bridge}.getManifest(${rspack.RuntimeGlobals.getUpdateManifestFilename}());
+};`;
+ }
+ }
+
+ return {
+ name: 'remotion-browser-hmr-runtime',
+ apply: (compiler) => {
+ compiler.hooks.compilation.tap(
+ 'remotion-browser-hmr-runtime',
+ (compilation) => {
+ compilation.hooks.runtimeRequirementInTree
+ .for(rspack.RuntimeGlobals.hmrDownloadManifest)
+ .tap('remotion-browser-hmr-runtime', (chunk) => {
+ compilation.addRuntimeModule(
+ chunk,
+ new BrowserHmrManifestRuntimeModule(),
+ );
+ });
+
+ rspack.RuntimePlugin.getCompilationHooks(
+ compilation,
+ ).createScript.tap(
+ 'remotion-browser-hmr-runtime',
+ (code) =>
+ `${code}\nscript.src = ${bridge}.resolveScriptUrl(script.src);`,
+ );
+ },
+ );
+ },
+ };
+};
diff --git a/packages/browser-bundler/src/load-browser-bundle.ts b/packages/browser-bundler/src/load-browser-bundle.ts
index 94bbe60823..09f88d5fe7 100644
--- a/packages/browser-bundler/src/load-browser-bundle.ts
+++ b/packages/browser-bundler/src/load-browser-bundle.ts
@@ -1,11 +1,5 @@
-import * as React from 'react';
-import * as ReactDOM from 'react-dom';
-import * as ReactDOMClient from 'react-dom/client';
-import * as JSXDevRuntime from 'react/jsx-dev-runtime';
-import * as JSXRuntime from 'react/jsx-runtime';
-import * as Remotion from 'remotion';
-import * as RemotionNoReact from 'remotion/no-react';
-import * as RemotionVersion from 'remotion/version';
+import type {FC} from 'react';
+import {createBrowserModuleScope} from './browser-module-scope';
import type {BrowserBundle} from './types.js';
/**
@@ -13,69 +7,14 @@ import type {BrowserBundle} from './types.js';
* Only execute code you trust: this uses Function(), not a sandbox, and the
* bundle has access to the page. React and Remotion are shared with the host.
*/
-export const loadBrowserBundle = ({
- bundle,
-}: {
- bundle: BrowserBundle;
-}): React.FC => {
- let root: React.FC | null = null;
- const registerRoot = (component: React.FC) => {
- if (
- !component ||
- React.isValidElement(component) ||
- (typeof component !== 'function' &&
- (typeof component !== 'object' || !('$$typeof' in component)))
- ) {
- throw new Error('registerRoot() must receive a React component.');
- }
-
- if (root !== null) {
- throw new Error('registerRoot() was called more than once.');
- }
-
- root = component;
- };
-
- const sharedModules = new Map<string, unknown>([
- ['react', React],
- ['react-dom', ReactDOM],
- ['react-dom/client', ReactDOMClient],
- ['react/jsx-runtime', JSXRuntime],
- ['react/jsx-dev-runtime', JSXDevRuntime],
- ['remotion', {...Remotion, registerRoot}],
- ['remotion/no-react', RemotionNoReact],
- ['remotion/version', RemotionVersion],
- ]);
-
- try {
- // eslint-disable-next-line no-new-func
- const evaluate = new Function(
- 'require',
- `${bundle.code}\n//# sourceURL=remotion-browser-bundle.js`,
- );
- evaluate((id: string) => {
- if (!sharedModules.has(id)) {
- throw new Error(
- `The browser bundle requested an unavailable shared module: "${id}".`,
- );
- }
-
- return sharedModules.get(id);
- });
- } catch (error) {
- throw new Error(
- `Could not evaluate the browser bundle: ${
- error instanceof Error ? error.message : String(error)
- }`,
- {cause: error},
- );
- }
-
- if (root === null) {
+export const loadBrowserBundle = ({bundle}: {bundle: BrowserBundle}): FC => {
+ if (bundle.fastRefresh) {
throw new Error(
- 'The browser bundle did not call registerRoot(). Use a normal Remotion project entry point.',
+ 'Use createBrowserBundleRuntime() to load a Fast Refresh bundle.',
);
}
- return root;
+ const scope = createBrowserModuleScope(null);
+ scope.evaluate(bundle.code);
+ return scope.getRoot();
};
diff --git a/packages/browser-bundler/src/react-refresh-runtime.d.ts b/packages/browser-bundler/src/react-refresh-runtime.d.ts
new file mode 100644
index 0000000000..583db4bd85
--- /dev/null
+++ b/packages/browser-bundler/src/react-refresh-runtime.d.ts
@@ -0,0 +1,12 @@
+declare module 'react-refresh/runtime' {
+ type ReactRefreshRuntime = {
+ createSignatureFunctionForTransform: (...args: unknown[]) => unknown;
+ getFamilyByType: (type: unknown) => unknown;
+ injectIntoGlobalHook: (globalObject: typeof globalThis) => void;
+ performReactRefresh: () => unknown;
+ register: (type: unknown, id: string) => void;
+ };
+
+ const runtime: ReactRefreshRuntime;
+ export = runtime;
+}
diff --git a/packages/browser-bundler/src/refresh-virtual-files.ts b/packages/browser-bundler/src/refresh-virtual-files.ts
new file mode 100644
index 0000000000..13356feea1
--- /dev/null
+++ b/packages/browser-bundler/src/refresh-virtual-files.ts
@@ -0,0 +1,25 @@
+declare const __BROWSER_BUNDLER_REACT_REFRESH_FILES__: {
+ entry: string;
+ runtime: string;
+ utils: string;
+};
+
+export const getBrowserReactRefreshVirtualFiles = ({
+ entry,
+ runtime,
+ utils,
+}: {
+ entry: string;
+ runtime: string;
+ utils: string;
+}): Record<string, string> => {
+ if (typeof __BROWSER_BUNDLER_REACT_REFRESH_FILES__ === 'undefined') {
+ throw new Error('Browser bundler React Refresh files were not injected.');
+ }
+
+ return {
+ [entry]: __BROWSER_BUNDLER_REACT_REFRESH_FILES__.entry,
+ [runtime]: __BROWSER_BUNDLER_REACT_REFRESH_FILES__.runtime,
+ [utils]: __BROWSER_BUNDLER_REACT_REFRESH_FILES__.utils,
+ };
+};
diff --git a/packages/browser-bundler/src/runtime.ts b/packages/browser-bundler/src/runtime.ts
index 44b159bbe8..41cd7a9638 100644
--- a/packages/browser-bundler/src/runtime.ts
+++ b/packages/browser-bundler/src/runtime.ts
@@ -1,3 +1,12 @@
+export {
+ createBrowserBundleRuntime,
+ type BrowserBundleRuntime,
+} from './create-browser-bundle-runtime';
+export {
+ createBrowserCompositionObserver,
+ type BrowserCompositionObserver,
+ type BrowserCompositionSelection,
+} from './create-browser-composition-observer';
export {getBrowserComposition} from './get-browser-composition.js';
export type {BrowserComposition} from './get-browser-composition.js';
export {loadBrowserBundle} from './load-browser-bundle.js';
diff --git a/packages/browser-bundler/src/test/runtime.test.tsx b/packages/browser-bundler/src/test/runtime.test.tsx
index df6399b3e7..bdb2bb1072 100644
--- a/packages/browser-bundler/src/test/runtime.test.tsx
+++ b/packages/browser-bundler/src/test/runtime.test.tsx
@@ -3,10 +3,19 @@
import './runtime-dom.js';
import {afterEach, expect, test} from 'bun:test';
import {Player, type PlayerRef} from '@remotion/player';
-import {act, cleanup, render, screen} from '@testing-library/react';
-import React, {createRef, useEffect} from 'react';
-import {Composition, Internals} from 'remotion';
import {
+ act,
+ cleanup,
+ fireEvent,
+ render,
+ screen,
+ waitFor,
+} from '@testing-library/react';
+import React, {createRef, useEffect, useState} from 'react';
+import {Composition, Internals, useCurrentFrame} from 'remotion';
+import {
+ createBrowserBundleRuntime,
+ createBrowserCompositionObserver,
getBrowserComposition,
loadBrowserBundle,
type BrowserComposition,
@@ -16,8 +25,215 @@ afterEach(() => {
cleanup();
});
+test('a persistent composition observer updates metadata without resetting the Player or video state', async () => {
+ const Video: React.FC<{readonly title: string}> = ({title}) => {
+ const [count, setCount] = useState(0);
+ const frame = useCurrentFrame();
+ return (
+ <button type="button" onClick={() => setCount((value) => value + 1)}>
+ {title} / clicks {count} / frame {frame}
+ </button>
+ );
+ };
+
+ const Root: React.FC = () => (
+ <Composition
+ id="Observed"
+ component={Video}
+ width={320}
+ height={180}
+ fps={30}
+ durationInFrames={90}
+ defaultProps={{title: 'Default'}}
+ calculateMetadata={({props}) => ({props, durationInFrames: 120})}
+ />
+ );
+ const configurations: BrowserComposition[] = [];
+ const errors: Error[] = [];
+ const observer = createBrowserCompositionObserver({
+ onChange: (composition) => configurations.push(composition),
+ onError: (error) => errors.push(error),
+ });
+ const playerRef = createRef<PlayerRef>();
+ const renderPlayer = (composition: BrowserComposition) => (
+ <Player
+ ref={playerRef}
+ component={composition.component}
+ inputProps={composition.props}
+ compositionWidth={composition.width}
+ compositionHeight={composition.height}
+ durationInFrames={composition.durationInFrames}
+ fps={composition.fps}
+ initialFrame={7}
+ numberOfSharedAudioTags={0}
+ acknowledgeRemotionLicense
+ />
+ );
+
+ try {
+ await act(() => {
+ observer.update({
+ root: Root,
+ compositionId: 'Observed',
+ inputProps: {title: 'First'},
+ });
+ });
+ await waitFor(() =>
+ expect(configurations.at(-1)?.props.title).toBe('First'),
+ );
+ const first = configurations.at(-1);
+ if (!first) {
+ throw new Error('The observer did not resolve the first composition.');
+ }
+
+ expect(first.durationInFrames).toBe(120);
+ const player = render(renderPlayer(first));
+ fireEvent.click(
+ await screen.findByRole('button', {
+ name: 'First / clicks 0 / frame 7',
+ }),
+ );
+ act(() => playerRef.current?.seekTo(12));
+
+ await act(() => {
+ observer.update({
+ root: Root,
+ compositionId: 'Observed',
+ inputProps: {title: 'Updated'},
+ });
+ });
+ await waitFor(() =>
+ expect(configurations.at(-1)?.props.title).toBe('Updated'),
+ );
+ const updated = configurations.at(-1);
+ if (!updated) {
+ throw new Error('The observer did not resolve the updated composition.');
+ }
+
+ expect(updated.component).toBe(first.component);
+ player.rerender(renderPlayer(updated));
+ await screen.findByRole('button', {
+ name: 'Updated / clicks 1 / frame 12',
+ });
+ expect(errors).toEqual([]);
+ } finally {
+ act(() => observer.dispose());
+ }
+
+ expect(() =>
+ observer.update({root: Root, compositionId: 'Observed', inputProps: {}}),
+ ).toThrow('was disposed');
+});
+
+test('composition observation discards stale metadata and recovers after runtime errors', async () => {
+ const hostCompositions = Internals.compositionsRef.current;
+ const configurations: BrowserComposition[] = [];
+ const errors: Error[] = [];
+ const pending: {
+ resolve: (result: {durationInFrames: number}) => void;
+ signal: AbortSignal;
+ }[] = [];
+ const Root: React.FC = () => (
+ <Composition
+ id="Observed"
+ component={() => null}
+ width={320}
+ height={180}
+ fps={30}
+ durationInFrames={90}
+ defaultProps={{phase: 'ready'}}
+ calculateMetadata={({props, abortSignal}) => {
+ if (props.phase === 'slow') {
+ return new Promise((resolve) => {
+ pending.push({resolve, signal: abortSignal});
+ });
+ }
+
+ if (props.phase === 'error') {
+ throw new Error('Metadata could not be resolved');
+ }
+
+ return {durationInFrames: 120};
+ }}
+ />
+ );
+ const InvalidRoot = () => {
+ throw new Error('Registration could not be rendered');
+ };
+
+ const containers = document.body.childElementCount;
+ const observer = createBrowserCompositionObserver({
+ onChange: (composition) => configurations.push(composition),
+ onError: (error) => errors.push(error),
+ });
+ const select = async (phase: string) => {
+ await act(() => {
+ observer.update({
+ root: Root,
+ compositionId: 'Observed',
+ inputProps: {phase},
+ });
+ });
+ };
+
+ try {
+ await select('slow');
+ expect(Internals.compositionsRef.current).toBe(hostCompositions);
+ expect(pending.some(({signal}) => !signal.aborted)).toBe(true);
+ const superseded = [...pending];
+ await select('ready');
+ await waitFor(() =>
+ expect(configurations.at(-1)?.durationInFrames).toBe(120),
+ );
+ expect(superseded.every(({signal}) => signal.aborted)).toBe(true);
+ const resolvedCount = configurations.length;
+ await act(() => {
+ for (const {resolve} of superseded) {
+ resolve({durationInFrames: 300});
+ }
+ });
+ expect(configurations).toHaveLength(resolvedCount);
+
+ await select('error');
+ await waitFor(() =>
+ expect(errors.at(-1)?.message).toBe('Metadata could not be resolved'),
+ );
+ await act(() => {
+ observer.update({
+ root: InvalidRoot,
+ compositionId: 'Observed',
+ inputProps: {},
+ });
+ });
+ await waitFor(() =>
+ expect(errors.at(-1)?.message).toBe('Registration could not be rendered'),
+ );
+ await select('recovered');
+ await waitFor(() =>
+ expect(configurations.at(-1)?.props.phase).toBe('recovered'),
+ );
+
+ await select('slow');
+ expect(pending.some(({signal}) => !signal.aborted)).toBe(true);
+ const finalCount = configurations.length;
+ act(() => observer.dispose());
+ expect(pending.every(({signal}) => signal.aborted)).toBe(true);
+ await act(() => {
+ for (const {resolve} of pending) {
+ resolve({durationInFrames: 300});
+ }
+ });
+ expect(configurations).toHaveLength(finalCount);
+ expect(document.body.childElementCount).toBe(containers);
+ expect(Internals.compositionsRef.current).toBe(hostCompositions);
+ } finally {
+ act(() => observer.dispose());
+ }
+});
+
const bundle = {
warnings: [],
+ fastRefresh: null,
code: `
const React = require('react');
const {jsx, jsxs} = require('react/jsx-runtime');
@@ -172,12 +388,51 @@ registerRoot(() => null);`,
},
])('rejects $name without registering a global root', ({code, error}) => {
const hostRoot = Internals.getRoot();
- expect(() => loadBrowserBundle({bundle: {code, warnings: []}})).toThrow(
- error,
- );
+ expect(() =>
+ loadBrowserBundle({bundle: {code, warnings: [], fastRefresh: null}}),
+ ).toThrow(error);
expect(Internals.getRoot()).toBe(hostRoot);
});
+test('Fast Refresh runtime owns its preview document and reports mode and disposal errors', async () => {
+ const originalRequire = Object.getOwnPropertyDescriptor(
+ globalThis,
+ 'require',
+ );
+ const runtime = createBrowserBundleRuntime();
+ try {
+ expect(() => createBrowserBundleRuntime()).toThrow(
+ 'Only one Fast Refresh runtime',
+ );
+ await expect(runtime.applyBundle(bundle)).rejects.toThrow(
+ 'enableFastRefresh: true',
+ );
+ expect(() =>
+ loadBrowserBundle({
+ bundle: {
+ ...bundle,
+ fastRefresh: {
+ sessionId: 'test',
+ hash: 'initial',
+ previousHash: null,
+ assets: [],
+ },
+ },
+ }),
+ ).toThrow('Use createBrowserBundleRuntime()');
+ } finally {
+ runtime.dispose();
+ }
+
+ await expect(runtime.applyBundle(bundle)).rejects.toThrow('was disposed');
+ runtime.dispose();
+ expect(Object.getOwnPropertyDescriptor(globalThis, 'require')).toEqual(
+ originalRequire,
+ );
+ const replacement = createBrowserBundleRuntime();
+ replacement.dispose();
+});
+
const compositionProps = {
id: 'Demo',
component: () => null,
diff --git a/packages/browser-bundler/src/types.ts b/packages/browser-bundler/src/types.ts
index 671cff8884..b05d269829 100644
--- a/packages/browser-bundler/src/types.ts
+++ b/packages/browser-bundler/src/types.ts
@@ -1,3 +1,5 @@
+import type {BrowserHmrAsset} from './hmr-assets';
+
export type VirtualProject = {
entryPoint: string;
files: Record<string, string>;
@@ -13,6 +15,12 @@ export type VirtualFileSystem = {
export type BrowserBundle = {
code: string;
warnings: string[];
+ fastRefresh: {
+ sessionId: string;
+ hash: string;
+ previousHash: string | null;
+ assets: BrowserHmrAsset[];
+ } | null;
};
export type BrowserBundlerProgress = {
@@ -23,6 +31,7 @@ export type BrowserBundlerProgress = {
export type BrowserBundlerOptions = {
dependencyVersions?: Record<string, string>;
+ enableFastRefresh?: boolean;
onProgress?: (progress: BrowserBundlerProgress) => void;
workerUrl?: string | URL;
};
@@ -36,6 +45,7 @@ export type BrowserBundlerWorkerRequest = {
id: number;
project: VirtualProject;
dependencyVersions: Record<string, string>;
+ enableFastRefresh: boolean;
};
export type SerializedCompilerError = {
diff --git a/packages/browser-studio/bundle.ts b/packages/browser-studio/bundle.ts
index f51317a456..14530320c7 100644
--- a/packages/browser-studio/bundle.ts
+++ b/packages/browser-studio/bundle.ts
@@ -2,7 +2,6 @@ import path from 'path';
import {fileURLToPath} from 'url';
import {build} from 'bun';
import {getBrowserStudioDependencyVersionsForBuild} from './src/dev/get-dependency-versions-for-build';
-import {getBrowserStudioReactRefreshFilesForBuild} from './src/dev/get-react-refresh-files-for-build';
import {getBrowserStudioSetupEnvironmentForBuild} from './src/dev/get-setup-environment-for-build';
import {getBrowserStudioWorkspacePackageExportsForBuild} from './src/dev/get-workspace-package-exports-for-build';
import {studioRenderEntryExternal} from './src/dev/studio-render-entry-external';
@@ -13,7 +12,6 @@ if (process.env.NODE_ENV !== 'production') {
console.time('Generated.');
const dependencyVersions = getBrowserStudioDependencyVersionsForBuild();
-const reactRefreshFiles = getBrowserStudioReactRefreshFilesForBuild();
const setupEnvironment = getBrowserStudioSetupEnvironmentForBuild();
const workspacePackageExports =
getBrowserStudioWorkspacePackageExportsForBuild();
@@ -75,7 +73,6 @@ const output = await build({
define: {
__BROWSER_STUDIO_ASSET_SIZES__: JSON.stringify(browserStudioAssetSizes),
__BROWSER_STUDIO_DEPENDENCY_VERSIONS__: JSON.stringify(dependencyVersions),
- __BROWSER_STUDIO_REACT_REFRESH_FILES__: JSON.stringify(reactRefreshFiles),
__BROWSER_STUDIO_SETUP_ENVIRONMENT__: JSON.stringify(setupEnvironment),
__BROWSER_STUDIO_WORKSPACE_PACKAGE_EXPORTS__: JSON.stringify(
workspacePackageExports,
diff --git a/packages/browser-studio/package.json b/packages/browser-studio/package.json
index e4b89d12f6..223b4c4e29 100644
--- a/packages/browser-studio/package.json
+++ b/packages/browser-studio/package.json
@@ -54,7 +54,6 @@
"@huggingface/transformers": "catalog:",
"@playwright/test": "1.55.1",
"@rspack/core": "1.7.11",
- "@rspack/plugin-react-refresh": "1.6.1",
"@remotion/studio": "workspace:*",
"@remotion/eslint-config-internal": "workspace:*",
"@types/react": "catalog:",
diff --git a/packages/browser-studio/src/browser-studio-hmr-assets.ts b/packages/browser-studio/src/browser-studio-hmr-assets.ts
index d6d547677f..c57c7ace41 100644
--- a/packages/browser-studio/src/browser-studio-hmr-assets.ts
+++ b/packages/browser-studio/src/browser-studio-hmr-assets.ts
@@ -1,88 +1,4 @@
-import type {BrowserStudioHmrAsset} from './types';
-
-export type BrowserStudioHmrBridge = {
- getManifest: (name: string) => Promise<object | undefined>;
- resolveScriptUrl: (name: string) => string;
-};
-
-const getAssetName = (nameOrUrl: string) => {
- const url = new URL(nameOrUrl, 'https://remotion.invalid');
- return url.pathname.split('/').at(-1) ?? '';
-};
-
-export const createBrowserStudioHmrAssetManager = ({
- createObjectUrl,
- revokeObjectUrl,
-}: {
- createObjectUrl: (blob: Blob) => string;
- revokeObjectUrl: (url: string) => void;
-}) => {
- const assets = new Map<string, {content: string; objectUrl: string | null}>();
-
- const updateAssets = (newAssets: BrowserStudioHmrAsset[]) => {
- const nextAssetNames = new Set(
- newAssets.map((asset) => getAssetName(asset.name)),
- );
- for (const [name, asset] of assets) {
- if (nextAssetNames.has(name)) {
- continue;
- }
-
- if (asset.objectUrl) {
- revokeObjectUrl(asset.objectUrl);
- }
-
- assets.delete(name);
- }
-
- for (const asset of newAssets) {
- const name = getAssetName(asset.name);
- const previous = assets.get(name);
- if (previous?.objectUrl) {
- revokeObjectUrl(previous.objectUrl);
- }
-
- assets.set(name, {content: asset.content, objectUrl: null});
- }
- };
-
- const bridge: BrowserStudioHmrBridge = {
- getManifest: (name) => {
- const asset = assets.get(getAssetName(name));
- if (!asset) {
- return Promise.resolve(undefined);
- }
-
- return Promise.resolve(JSON.parse(asset.content) as object);
- },
- resolveScriptUrl: (name) => {
- const assetName = getAssetName(name);
- const asset = assets.get(assetName);
- if (!asset) {
- throw new Error(`Missing Browser Studio HMR asset: ${assetName}`);
- }
-
- if (!asset.objectUrl) {
- asset.objectUrl = createObjectUrl(
- new Blob([asset.content], {type: 'text/javascript'}),
- );
- }
-
- return asset.objectUrl;
- },
- };
-
- return {
- bridge,
- dispose: () => {
- for (const asset of assets.values()) {
- if (asset.objectUrl) {
- revokeObjectUrl(asset.objectUrl);
- }
- }
-
- assets.clear();
- },
- updateAssets,
- };
-};
+export {
+ createBrowserHmrAssetManager as createBrowserStudioHmrAssetManager,
+ type BrowserHmrBridge as BrowserStudioHmrBridge,
+} from '@remotion/browser-bundler/compiler';
diff --git a/packages/browser-studio/src/browser-studio-worker.ts b/packages/browser-studio/src/browser-studio-worker.ts
index fba7daa031..0985c36c97 100644
--- a/packages/browser-studio/src/browser-studio-worker.ts
+++ b/packages/browser-studio/src/browser-studio-worker.ts
@@ -1,6 +1,8 @@
import {
createBrowserCompiler,
createBrowserDependencyPlugin,
+ createBrowserHmrRuntimePlugin,
+ createBrowserReactRefreshPlugin,
getVirtualProjectChanges,
getVirtualProjectFiles,
makeBrowserHttpClient,
@@ -10,7 +12,6 @@ import {
} from '@remotion/browser-bundler/compiler';
import type {HotMiddlewareMessage} from '@remotion/studio-shared';
import {getStudioEntryPoints} from '@remotion/studio-shared/studio-entry-points';
-import type * as RspackBrowser from '@rspack/browser';
import {BROWSER_STUDIO_TRANSFORMERS_PACKAGE} from './browser-studio-import-map';
import {browserStudioDependencyVersions} from './dependency-versions';
import {studioRenderEntryExternal} from './dev/studio-render-entry-external';
@@ -108,80 +109,6 @@ const applyDependencyResolution = ({
}
};
-const getReactRefreshPlugin = (
- rspackBrowser: typeof RspackBrowser,
-): RspackBrowser.RspackPluginInstance => ({
- name: 'browser-studio-react-refresh',
- apply: (compiler) => {
- new rspackBrowser.ProvidePlugin({
- $ReactRefreshRuntime$: browserStudioVirtualFilePaths.reactRefreshRuntime,
- __react_refresh_utils__: browserStudioVirtualFilePaths.reactRefreshUtils,
- }).apply(compiler);
- new rspackBrowser.DefinePlugin({
- __react_refresh_error_overlay__: false,
- __react_refresh_library__: JSON.stringify('browser-studio'),
- __react_refresh_socket__: false,
- __reload_on_runtime_errors__: false,
- }).apply(compiler);
-
- compiler.hooks.compilation.tap(
- 'browser-studio-react-refresh',
- (compilation) => {
- compilation.hooks.additionalTreeRuntimeRequirements.tap(
- 'browser-studio-react-refresh',
- (_chunk, runtimeRequirements) => {
- runtimeRequirements.add(rspackBrowser.RuntimeGlobals.moduleCache);
- },
- );
- },
- );
- },
-});
-
-const getBrowserStudioHmrRuntimePlugin = (
- rspackBrowser: typeof RspackBrowser,
-): RspackBrowser.RspackPluginInstance => {
- class BrowserStudioManifestRuntimeModule extends rspackBrowser.RuntimeModule {
- constructor() {
- super(
- 'browser studio hmr manifest',
- rspackBrowser.RuntimeModule.STAGE_TRIGGER,
- );
- }
-
- generate() {
- return `${rspackBrowser.RuntimeGlobals.hmrDownloadManifest} = function() {
- return window.remotion_browserStudioHmr.getManifest(${rspackBrowser.RuntimeGlobals.getUpdateManifestFilename}());
-};`;
- }
- }
-
- return {
- name: 'browser-studio-hmr-runtime',
- apply: (compiler) => {
- compiler.hooks.compilation.tap(
- 'browser-studio-hmr-runtime',
- (compilation) => {
- compilation.hooks.runtimeRequirementInTree
- .for(rspackBrowser.RuntimeGlobals.hmrDownloadManifest)
- .tap('browser-studio-hmr-runtime', (chunk) => {
- compilation.addRuntimeModule(
- chunk,
- new BrowserStudioManifestRuntimeModule(),
- );
- });
-
- rspackBrowser.RuntimePlugin.getCompilationHooks(
- compilation,
- ).createScript.tap('browser-studio-hmr-runtime', (code) => {
- return `${code}\nscript.src = window.remotion_browserStudioHmr.resolveScriptUrl(script.src);`;
- });
- },
- );
- },
- };
-};
-
const createCompiler = async ({
dependencyResolutions,
project,
@@ -328,7 +255,11 @@ const createCompiler = async ({
publicPath: '/__remotion_browser_studio_hmr__/',
},
plugins: [
- getReactRefreshPlugin(rspackBrowser),
+ createBrowserReactRefreshPlugin({
+ rspack: rspackBrowser,
+ refreshRuntime: browserStudioVirtualFilePaths.reactRefreshRuntime,
+ refreshUtils: browserStudioVirtualFilePaths.reactRefreshUtils,
+ }),
createBrowserDependencyPlugin({
rspack: rspackBrowser,
development: true,
@@ -343,7 +274,10 @@ const createCompiler = async ({
}),
}),
new rspackBrowser.HotModuleReplacementPlugin(),
- getBrowserStudioHmrRuntimePlugin(rspackBrowser),
+ createBrowserHmrRuntimePlugin({
+ rspack: rspackBrowser,
+ bridgeName: 'remotion_browserStudioHmr',
+ }),
new rspackBrowser.optimize.LimitChunkCountPlugin({maxChunks: 1}),
],
resolve: {extensions: ['.tsx', '.ts', '.jsx', '.js', '.json']},
diff --git a/packages/browser-studio/src/dev/get-react-refresh-files-for-build.ts b/packages/browser-studio/src/dev/get-react-refresh-files-for-build.ts
deleted file mode 100644
index 0bb609be1c..0000000000
--- a/packages/browser-studio/src/dev/get-react-refresh-files-for-build.ts
+++ /dev/null
@@ -1,19 +0,0 @@
-import {readFileSync} from 'node:fs';
-import {dirname, join} from 'node:path';
-import {fileURLToPath} from 'node:url';
-
-export const getBrowserStudioReactRefreshFilesForBuild = () => {
- const entry = fileURLToPath(
- import.meta.resolve('@rspack/plugin-react-refresh/react-refresh-entry'),
- );
- const runtime = fileURLToPath(
- import.meta.resolve('@rspack/plugin-react-refresh/react-refresh'),
- );
- const refreshUtils = join(dirname(runtime), 'refreshUtils.js');
-
- return {
- entry: readFileSync(entry, 'utf-8'),
- runtime: readFileSync(runtime, 'utf-8'),
- utils: readFileSync(refreshUtils, 'utf-8'),
- };
-};
diff --git a/packages/browser-studio/src/dev/server.ts b/packages/browser-studio/src/dev/server.ts
index e56b70eca4..89cd13a579 100644
--- a/packages/browser-studio/src/dev/server.ts
+++ b/packages/browser-studio/src/dev/server.ts
@@ -3,7 +3,6 @@ import {fileURLToPath} from 'url';
import {build} from 'bun';
import {browserStudioPackageJsonArtifactFilename} from '../workspace-package-exports';
import {getBrowserStudioDependencyVersionsForBuild} from './get-dependency-versions-for-build';
-import {getBrowserStudioReactRefreshFilesForBuild} from './get-react-refresh-files-for-build';
import {getBrowserStudioSetupEnvironmentForBuild} from './get-setup-environment-for-build';
import {getBrowserStudioWorkspacePackageExportsForBuild} from './get-workspace-package-exports-for-build';
import {studioRenderEntryExternal} from './studio-render-entry-external';
@@ -71,7 +70,6 @@ const frameHtml = `<!DOCTYPE html>
const buildDevAssets = async () => {
const dependencyVersions = getBrowserStudioDependencyVersionsForBuild();
- const reactRefreshFiles = getBrowserStudioReactRefreshFilesForBuild();
const setupEnvironment = getBrowserStudioSetupEnvironmentForBuild();
const workspacePackageExports =
getBrowserStudioWorkspacePackageExportsForBuild();
@@ -128,7 +126,6 @@ const buildDevAssets = async () => {
__BROWSER_STUDIO_ASSET_SIZES__: JSON.stringify(browserStudioAssetSizes),
__BROWSER_STUDIO_DEPENDENCY_VERSIONS__:
JSON.stringify(dependencyVersions),
- __BROWSER_STUDIO_REACT_REFRESH_FILES__: JSON.stringify(reactRefreshFiles),
__BROWSER_STUDIO_SETUP_ENVIRONMENT__: JSON.stringify(setupEnvironment),
__BROWSER_STUDIO_WORKSPACE_PACKAGE_EXPORTS__: JSON.stringify(
workspacePackageExports,
diff --git a/packages/browser-studio/src/test/browser-studio-hmr-assets.test.ts b/packages/browser-studio/src/test/browser-studio-hmr-assets.test.ts
index 7af5317ffa..bae637b30a 100644
--- a/packages/browser-studio/src/test/browser-studio-hmr-assets.test.ts
+++ b/packages/browser-studio/src/test/browser-studio-hmr-assets.test.ts
@@ -61,5 +61,5 @@ test('fails clearly when Rspack asks for a missing HMR script', () => {
expect(() =>
manager.bridge.resolveScriptUrl('missing.hot-update.js'),
- ).toThrow('Missing Browser Studio HMR asset: missing.hot-update.js');
+ ).toThrow('Missing browser HMR asset: missing.hot-update.js');
});
diff --git a/packages/browser-studio/src/virtual-files.ts b/packages/browser-studio/src/virtual-files.ts
index fe1d9a5faa..61d8d32ca7 100644
--- a/packages/browser-studio/src/virtual-files.ts
+++ b/packages/browser-studio/src/virtual-files.ts
@@ -1,3 +1,4 @@
+import {getBrowserReactRefreshVirtualFiles} from '@remotion/browser-bundler/compiler';
import {REACT_REFRESH_FINISHED_EVENT} from '@remotion/studio-shared';
export const browserStudioVirtualFilePaths = {
@@ -16,13 +17,6 @@ export const browserStudioVirtualFilePaths = {
};
declare const __BROWSER_STUDIO_SETUP_ENVIRONMENT__: string | undefined;
-declare const __BROWSER_STUDIO_REACT_REFRESH_FILES__:
- | {
- entry: string;
- runtime: string;
- utils: string;
- }
- | undefined;
const getInjectedSetupEnvironment = () => {
if (typeof __BROWSER_STUDIO_SETUP_ENVIRONMENT__ === 'undefined') {
@@ -32,14 +26,6 @@ const getInjectedSetupEnvironment = () => {
return __BROWSER_STUDIO_SETUP_ENVIRONMENT__;
};
-const getInjectedReactRefreshFiles = () => {
- if (typeof __BROWSER_STUDIO_REACT_REFRESH_FILES__ === 'undefined') {
- throw new Error('Browser Studio React Refresh files were not injected');
- }
-
- return __BROWSER_STUDIO_REACT_REFRESH_FILES__;
-};
-
const notifyOnRefresh = `const RemotionRefreshRuntime = require('react-refresh/runtime');
RemotionRefreshRuntime.__remotionReactRefreshWrapped ??= null;
@@ -182,14 +168,16 @@ void globalThis.remotion_browserStudioVendor.startStudio();
`;
export const getBrowserStudioVirtualFiles = (): Record<string, string> => {
- const reactRefreshFiles = getInjectedReactRefreshFiles();
+ const reactRefreshFiles = getBrowserReactRefreshVirtualFiles({
+ entry: browserStudioVirtualFilePaths.reactRefreshEntry,
+ runtime: browserStudioVirtualFilePaths.reactRefreshRuntime,
+ utils: browserStudioVirtualFilePaths.reactRefreshUtils,
+ });
return {
+ ...reactRefreshFiles,
[browserStudioVirtualFilePaths.browserRequireShim]: browserRequireShim,
- [browserStudioVirtualFilePaths.reactRefreshEntry]: `${reactRefreshFiles.entry}\n${notifyOnRefresh}`,
- [browserStudioVirtualFilePaths.reactRefreshRuntime]:
- reactRefreshFiles.runtime,
- [browserStudioVirtualFilePaths.reactRefreshUtils]: reactRefreshFiles.utils,
+ [browserStudioVirtualFilePaths.reactRefreshEntry]: `${reactRefreshFiles[browserStudioVirtualFilePaths.reactRefreshEntry]}\n${notifyOnRefresh}`,
[browserStudioVirtualFilePaths.setupEnvironment]:
getInjectedSetupEnvironment(),
[browserStudioVirtualFilePaths.setupSequenceStackTraces]:
diff --git a/packages/docs/build-browser-studio-standalone.ts b/packages/docs/build-browser-studio-standalone.ts
index 79f90c2453..5aa892ed41 100644
--- a/packages/docs/build-browser-studio-standalone.ts
+++ b/packages/docs/build-browser-studio-standalone.ts
@@ -2,7 +2,6 @@ import {copyFileSync, cpSync, mkdirSync} from 'node:fs';
import path from 'node:path';
import {build} from 'bun';
import {getBrowserStudioDependencyVersionsForBuild} from '../browser-studio/src/dev/get-dependency-versions-for-build';
-import {getBrowserStudioReactRefreshFilesForBuild} from '../browser-studio/src/dev/get-react-refresh-files-for-build';
import {getBrowserStudioSetupEnvironmentForBuild} from '../browser-studio/src/dev/get-setup-environment-for-build';
import {getBrowserStudioWorkspacePackageExportsForBuild} from '../browser-studio/src/dev/get-workspace-package-exports-for-build';
import {getBrowserStudioWorkspaceCommit} from './get-browser-studio-workspace-commit';
@@ -18,7 +17,6 @@ const outputDir = path.join(
);
const publicAssetPath = `/assets/experimental-new/${commit}`;
const dependencyVersions = getBrowserStudioDependencyVersionsForBuild();
-const reactRefreshFiles = getBrowserStudioReactRefreshFilesForBuild();
const setupEnvironment = getBrowserStudioSetupEnvironmentForBuild();
const workspacePackageExports =
getBrowserStudioWorkspacePackageExportsForBuild();
@@ -46,7 +44,6 @@ copyFileSync(
const output = await build({
define: {
__BROWSER_STUDIO_DEPENDENCY_VERSIONS__: JSON.stringify(dependencyVersions),
- __BROWSER_STUDIO_REACT_REFRESH_FILES__: JSON.stringify(reactRefreshFiles),
__BROWSER_STUDIO_SETUP_ENVIRONMENT__: JSON.stringify(setupEnvironment),
__BROWSER_STUDIO_WORKSPACE_COMMIT__: JSON.stringify(commit),
__BROWSER_STUDIO_WORKSPACE_PACKAGE_EXPORTS__: JSON.stringify(
diff --git a/packages/docs/components/TableOfContents/api.tsx b/packages/docs/components/TableOfContents/api.tsx
index 4412d98035..03cfc9adcd 100644
--- a/packages/docs/components/TableOfContents/api.tsx
+++ b/packages/docs/components/TableOfContents/api.tsx
@@ -1,7 +1,6 @@
import React from 'react';
import {TableOfContents as AnimatedEmojiTableOfContents} from '../../docs/animated-emoji/TableOfContents';
import {TableOfContents as AnimationUtilsTableOfContents} from '../../docs/animation-utils/table-of-contents';
-import {TableOfContents as BrowserBundlerTableOfContents} from '../../docs/browser-bundler/table-of-contents';
import {TableOfContents as BundlerTableOfContents} from '../../docs/bundler/table-of-contents';
import {TableOfContents as CaptionsTableOfContents} from '../../docs/captions/TableOfContents';
import {TableOfContents as CloudrunTableOfContents} from '../../docs/cloudrun/table-of-contents';
@@ -78,9 +77,6 @@ export const TableOfContents: React.FC = () => {
<h2>@remotion/animation-utils</h2>
<p>Obtain info about video and audio.</p>
<AnimationUtilsTableOfContents />
- <h2>@remotion/browser-bundler</h2>
- <p>Compile virtual Remotion projects in the browser.</p>
- <BrowserBundlerTableOfContents />
<h2>@remotion/bundler</h2>
<p>Create a Webpack bundle from Node.JS </p>
<BundlerTableOfContents />
diff --git a/packages/docs/docs/browser-bundler/create-browser-bundle-runtime.mdx b/packages/docs/docs/browser-bundler/create-browser-bundle-runtime.mdx
new file mode 100644
index 0000000000..f072218146
--- /dev/null
+++ b/packages/docs/docs/browser-bundler/create-browser-bundle-runtime.mdx
@@ -0,0 +1,109 @@
+---
+image: /generated/articles-docs-browser-bundler-create-browser-bundle-runtime.png
+title: createBrowserBundleRuntime()
+crumb: '@remotion/browser-bundler'
+---
+
+# createBrowserBundleRuntime()<AvailableFrom v="4.0.527" />
+
+Load a virtual Remotion project once and apply later edits through Rspack hot updates and React Fast Refresh. Import it from `@remotion/browser-bundler/runtime`.
+
+:::warning
+
+*Draft API*: This API is not yet stable. We are in the experimental phase of this package and reserve to change it at any time.
+
+:::
+
+This API executes trusted code only. Neither the runtime nor a same-origin preview iframe is a security sandbox.
+
+## Preview setup
+
+React Fast Refresh requires development builds of React and React DOM. Keep this renderer in an isolated preview iframe when the surrounding editor uses production React.
+
+Install `[email protected]` as a direct dependency of the preview app. Serve the iframe with the same [cross-origin isolation headers](/docs/browser-bundler#browser-setup) as the editor.
+
+Bundle the preview separately with `process.env.NODE_ENV` fixed to `'development'`, including its React, React DOM, Remotion, and Player dependencies. Initialize React Refresh before importing code that loads React DOM:
+
+```js title="preview-entry.js"
+import RefreshRuntime from 'react-refresh/runtime';
+
+RefreshRuntime.injectIntoGlobalHook(globalThis);
+
+import('./preview.js');
+```
+
+Keep the iframe, its React root, and its Player mounted across edits. Recreating the document or giving the Player a new `key` on each compilation loses the state that Fast Refresh preserves.
+
+Create the compiler with [`enableFastRefresh: true`](/docs/browser-bundler/create-browser-bundler#enablefastrefresh), and pass its bundles to the preview runtime:
+
+```ts twoslash title="Applying bundles in preview.ts"
+// @moduleResolution: bundler
+import type {BrowserBundle} from '@remotion/browser-bundler';
+import type {BrowserComposition} from '@remotion/browser-bundler/runtime';
+declare const bundle: BrowserBundle;
+declare const updatePlayer: (composition: BrowserComposition) => void;
+declare const showError: (error: Error) => void;
+// ---cut---
+import {
+ createBrowserBundleRuntime,
+ createBrowserCompositionObserver,
+} from '@remotion/browser-bundler/runtime';
+
+const runtime = createBrowserBundleRuntime();
+const observer = createBrowserCompositionObserver({
+ onChange: updatePlayer,
+ onError: showError,
+});
+
+export const applyBundle = async (bundle: BrowserBundle) => {
+ const root = await runtime.applyBundle(bundle);
+ observer.update({
+ root,
+ compositionId: 'HelloWorld',
+ inputProps: {},
+ });
+};
+
+await applyBundle(bundle);
+```
+
+The returned root registers compositions; it is not the video component for the Player. [`createBrowserCompositionObserver()`](/docs/browser-bundler/create-browser-composition-observer) keeps the registration tree mounted and supplies the selected component and metadata to your Player.
+
+Calling [`getBrowserComposition()`](/docs/browser-bundler/get-browser-composition) again for every edit creates fresh component wrappers and does not preserve that tree.
+
+## Return value
+
+A `BrowserBundleRuntime` with the following methods. Use one runtime per preview document.
+
+### applyBundle()
+
+Accepts a complete [`BrowserBundle`](/docs/browser-bundler/create-browser-bundler#browserbundle) and returns a `Promise<React.FC>` containing its registered root.
+
+The first call evaluates the full bundle. Later calls apply Rspack's hot-update assets to the existing module graph and run React Fast Refresh. Compatible component edits preserve React state; changing hook signatures or component types can reset the affected component.
+
+Calls are serialized. Apply every successfully compiled bundle in order, even when newer edits are pending. Skipping compiled updates breaks the hot-update chain and rejects the promise.
+
+Compilation errors do not produce a bundle to apply. Keep the previous preview visible while showing diagnostics, then apply the next successful build.
+
+### dispose()
+
+Release the runtime's hot-update assets and document-level bindings. Further `applyBundle()` calls reject. Unmount the preview's React roots and dispose its compiler separately.
+
+Disposal does not undo arbitrary side effects from evaluated project code. Use a new preview document when replacing an entire compiler session or project.
+
+## Errors
+
+Rejects if Fast Refresh was not enabled, the preview renderer does not support it, an update is missing or out of order, the compiler session changes, or evaluation or hot application fails.
+
+## Compatibility
+
+<CompatibilityTable chrome firefox="Not tested" safari="Not tested" nodejs="" bun="" serverlessFunctions="" clientSideRendering="" serverSideRendering={false} player studio="" hideServers />
+
+The experimental workflow has only been tested in Chrome.
+
+## See also
+
+- [Browser bundler overview](/docs/browser-bundler)
+- [`createBrowserBundler()`](/docs/browser-bundler/create-browser-bundler)
+- [`createBrowserCompositionObserver()`](/docs/browser-bundler/create-browser-composition-observer)
+- [`loadBrowserBundle()`](/docs/browser-bundler/load-browser-bundle)
diff --git a/packages/docs/docs/browser-bundler/create-browser-bundler.mdx b/packages/docs/docs/browser-bundler/create-browser-bundler.mdx
index 6f83c25f81..6024293904 100644
--- a/packages/docs/docs/browser-bundler/create-browser-bundler.mdx
+++ b/packages/docs/docs/browser-bundler/create-browser-bundler.mdx
@@ -71,6 +71,14 @@ const bundler = createBrowserBundler({
});
```
+### enableFastRefresh?
+
+Enable Rspack hot updates and React Fast Refresh. Default: `false`.
+
+Apply these bundles with [`createBrowserBundleRuntime()`](/docs/browser-bundler/create-browser-bundle-runtime), not [`loadBrowserBundle()`](/docs/browser-bundler/load-browser-bundle). The preview must use development React and React DOM with the React Refresh hook installed before the renderer loads. An isolated preview iframe can provide that environment even when the editor itself is a production app.
+
+Apply every successful bundle in compilation order. You may coalesce pending source edits before calling `bundle()`, but must not discard already compiled hot updates.
+
### onProgress?
Called with download progress while loading the compiler's WebAssembly asset. By default, no progress callback is called. This is download progress, not compilation progress.
@@ -145,6 +153,26 @@ The compiled JavaScript as a `string`. Pass the complete `BrowserBundle` to [`lo
An array of compiler warning strings. An empty array means no compiler warnings were reported.
+### fastRefresh
+
+Hot-update data when `enableFastRefresh` is enabled, otherwise `null`. Pass the complete bundle to the preview runtime without modifying this data.
+
+#### sessionId
+
+Identifies the compiler session. Create a new preview runtime if the session changes.
+
+#### hash
+
+Identifies the compiled version of the project.
+
+#### previousHash
+
+The preceding successful compilation's hash, or `null` for the first build.
+
+#### assets
+
+The hot-update scripts and manifests emitted by Rspack. Each asset has a `name` and its text `content`.
+
## Errors
Compilation failures reject with `BrowserBundlerError`, exported from `@remotion/browser-bundler`. Display its `message` and diagnostics in your own error UI.
diff --git a/packages/docs/docs/browser-bundler/create-browser-composition-observer.mdx b/packages/docs/docs/browser-bundler/create-browser-composition-observer.mdx
new file mode 100644
index 0000000000..919c7aacee
--- /dev/null
+++ b/packages/docs/docs/browser-bundler/create-browser-composition-observer.mdx
@@ -0,0 +1,123 @@
+---
+image: /generated/articles-docs-browser-bundler-create-browser-composition-observer.png
+title: createBrowserCompositionObserver()
+crumb: '@remotion/browser-bundler'
+---
+
+# createBrowserCompositionObserver()<AvailableFrom v="4.0.527" />
+
+Keep a registered Remotion root mounted and observe a selected composition's component, props, and video configuration. Import it from `@remotion/browser-bundler/runtime`.
+
+:::warning
+
+*Draft API*: This API is not yet stable. We are in the experimental phase of this package and reserve to change it at any time.
+
+:::
+
+Use this with [`createBrowserBundleRuntime()`](/docs/browser-bundler/create-browser-bundle-runtime) for state-preserving edits. Unlike [`getBrowserComposition()`](/docs/browser-bundler/get-browser-composition), the observer retains the registration tree between updates.
+
+Registrations are local to the observer and do not replace the host's composition registry.
+
+This API executes trusted project code. It is not a sandbox.
+
+## Usage
+
+Create one observer and one Player root for the lifetime of the preview:
+
+```tsx twoslash title="preview.tsx"
+// @moduleResolution: bundler
+import type {FC} from 'react';
+declare const root: FC;
+declare const container: HTMLDivElement;
+// ---cut---
+import {createBrowserCompositionObserver} from '@remotion/browser-bundler/runtime';
+import {Player} from '@remotion/player';
+import {createRoot} from 'react-dom/client';
+
+const preview = createRoot(container);
+const observer = createBrowserCompositionObserver({
+ onChange: (composition) => {
+ preview.render(
+ <Player
+ component={composition.component}
+ inputProps={composition.props}
+ compositionWidth={composition.width}
+ compositionHeight={composition.height}
+ fps={composition.fps}
+ durationInFrames={composition.durationInFrames}
+ controls
+ />,
+ );
+ },
+ onError: (error) => console.error('Could not resolve composition:', error),
+});
+
+observer.update({
+ root,
+ compositionId: 'HelloWorld',
+ inputProps: {message: 'Hello from the browser!'},
+});
+
+export const dispose = () => {
+ preview.unmount();
+ observer.dispose();
+};
+```
+
+After each successful hot update, call `update()` with the root returned by [`applyBundle()`](/docs/browser-bundler/create-browser-bundle-runtime#applybundle). Keep the Player mounted without a changing `key`.
+
+## Options
+
+### onChange
+
+Receives a [`BrowserComposition`](/docs/browser-bundler/get-browser-composition#return-value) after registration and metadata resolution. It can run again when the selected composition or its input props change, including during Fast Refresh.
+
+The result contains the registered video component, merged and calculated props, dimensions, frame rate, and duration. The component wrapper remains stable while its registration stays mounted. Replacing the registration tree or selecting a different composition can reset video state.
+
+### onError
+
+Receives an `Error` for registration failures, a missing composition, or failed or invalid [`calculateMetadata()`](/docs/calculate-metadata) results. A later `update()` can recover from these errors.
+
+Keep the previous Player visible while displaying the error. The observer does not render an error UI.
+
+## Return value
+
+A `BrowserCompositionObserver` with the following methods.
+
+### update()
+
+Selects a composition and starts asynchronous registration and metadata resolution. Returns `void`; results arrive through `onChange` or `onError`.
+
+Pass a `BrowserCompositionSelection` object with these fields:
+
+#### root
+
+The registered `React.FC` returned by [`applyBundle()`](/docs/browser-bundler/create-browser-bundle-runtime#applybundle) or [`loadBrowserBundle()`](/docs/browser-bundler/load-browser-bundle).
+
+#### compositionId
+
+The exact `id` of the registered [`<Composition>`](/docs/composition).
+
+#### inputProps
+
+A required `Record<string, unknown>`. Pass `{}` to use the composition's defaults. Input props override default props before [`calculateMetadata()`](/docs/calculate-metadata) runs.
+
+Changing the selection cancels superseded metadata work and ignores its eventual result. This does not permit skipping compiled Fast Refresh bundles: apply those in compilation order.
+
+### dispose()
+
+Unmounts the registration tree, cancels pending metadata work, and removes the observer's hidden container. Further `update()` calls throw.
+
+Dispose the Player, bundle runtime, and compiler separately. Providers around `<Composition>` are used for registration only; providers needed during playback belong inside the video component or around the Player.
+
+## Compatibility
+
+<CompatibilityTable chrome firefox="Not tested" safari="Not tested" nodejs="" bun="" serverlessFunctions="" clientSideRendering="" serverSideRendering={false} player studio="" hideServers />
+
+The experimental workflow has only been tested in Chrome. Call this in a browser document, not during server rendering.
+
+## See also
+
+- [`createBrowserBundleRuntime()`](/docs/browser-bundler/create-browser-bundle-runtime)
+- [`getBrowserComposition()`](/docs/browser-bundler/get-browser-composition)
+- [`<Player>`](/docs/player/player)
diff --git a/packages/docs/docs/browser-bundler/get-browser-composition.mdx b/packages/docs/docs/browser-bundler/get-browser-composition.mdx
index bfe2e20794..cdf4d04aad 100644
--- a/packages/docs/docs/browser-bundler/get-browser-composition.mdx
+++ b/packages/docs/docs/browser-bundler/get-browser-composition.mdx
@@ -171,6 +171,8 @@ The promise rejects for a missing composition ID, invalid or duplicate registrat
This function runs again on every call. Resolving a new bundle does not automatically update a Player; you decide when to replace its component, props, and configuration.
+For Fast Refresh, use [`createBrowserCompositionObserver()`](/docs/browser-bundler/create-browser-composition-observer) instead. It keeps the registration tree mounted between edits, preserving the component wrapper passed to the Player.
+
## Compatibility
<CompatibilityTable chrome firefox="Not tested" safari="Not tested" nodejs="" bun="" serverlessFunctions="" clientSideRendering="" serverSideRendering={false} player studio="" hideServers />
@@ -181,6 +183,7 @@ The experimental workflow has only been tested in Chrome. Call this in a browser
- [Overview and complete Player example](/docs/browser-bundler)
- [`loadBrowserBundle()`](/docs/browser-bundler/load-browser-bundle)
+- [`createBrowserCompositionObserver()`](/docs/browser-bundler/create-browser-composition-observer)
- [`<Composition>`](/docs/composition)
- [`calculateMetadata()`](/docs/calculate-metadata)
- [`<Player>`](/docs/player/player)
diff --git a/packages/docs/docs/browser-bundler/index.mdx b/packages/docs/docs/browser-bundler/index.mdx
index d9353a5e8e..9032173857 100644
--- a/packages/docs/docs/browser-bundler/index.mdx
+++ b/packages/docs/docs/browser-bundler/index.mdx
@@ -232,7 +232,7 @@ export const BrowserBundlerPreview = () => {
Pass the returned `component` to [`<Player>`](/docs/player/player), not the registered root or `<Composition>` itself. Pass `props` and the resolved dimensions, frame rate, and duration alongside it. [`getBrowserComposition()`](/docs/browser-bundler/get-browser-composition) merges default and input props and runs [`calculateMetadata()`](/docs/calculate-metadata) when provided.
-This example compiles once and disposes its worker. For editing, keep the bundler alive and submit a new complete snapshot when the source changes. Load and resolve the new bundle before updating your Player. Keep the last successful preview visible while compiling, and discard results superseded by newer edits.
+This example compiles once and disposes its worker. For editing, keep the bundler alive and submit a new complete snapshot when the source changes. Keep the last successful preview visible while compiling.
## Scope and limitations
@@ -252,7 +252,11 @@ The virtual project has no `public/` asset mapping or public-file persistence. [
### Updating the preview
-Compiling does not automatically replace an existing Player component. You own recompilation triggers, loading and resolving the new bundle, handling stale results and errors, and updating playback. There is no automatic hot module replacement for the host Player.
+Compiling does not automatically replace an existing Player component. You own recompilation triggers, loading and resolving the new bundle, handling stale results and errors, and updating playback.
+
+For state-preserving edits, enable [`enableFastRefresh`](/docs/browser-bundler/create-browser-bundler#enablefastrefresh) and apply bundles with [`createBrowserBundleRuntime()`](/docs/browser-bundler/create-browser-bundle-runtime). Use an isolated preview with development React and [`createBrowserCompositionObserver()`](/docs/browser-bundler/create-browser-composition-observer) to keep the composition registration tree mounted alongside the Player. This uses Rspack hot updates and React Fast Refresh rather than evaluating and remounting a fresh Player on each edit.
+
+Coalesce pending source edits before compilation, but apply every successfully compiled Fast Refresh bundle in order. Discarding compiled updates breaks the hot-update chain.
This package does not export a video file. See [client-side rendering](/docs/client-side-rendering) for video export APIs and their separate requirements.
diff --git a/packages/docs/docs/browser-bundler/load-browser-bundle.mdx b/packages/docs/docs/browser-bundler/load-browser-bundle.mdx
index 78d7ac3e9a..f60184678e 100644
--- a/packages/docs/docs/browser-bundler/load-browser-bundle.mdx
+++ b/packages/docs/docs/browser-bundler/load-browser-bundle.mdx
@@ -16,6 +16,8 @@ Executes a [`BrowserBundle`](/docs/browser-bundler/create-browser-bundler#browse
This API executes trusted code only. It is not a sandbox.
+Each call evaluates a fresh bundle. For state-preserving edits, use [`createBrowserBundleRuntime()`](/docs/browser-bundler/create-browser-bundle-runtime) with `enableFastRefresh: true` instead.
+
After compiling a project with [`createBrowserBundler()`](/docs/browser-bundler/create-browser-bundler):
```ts twoslash title="load-composition.ts"
@@ -42,6 +44,8 @@ const composition = await getBrowserComposition({
The complete `BrowserBundle` returned by a bundler's `bundle()` method. Its entry point must synchronously call [`registerRoot()`](/docs/register-root) exactly once with a root component. Registering after an awaited operation or in a timer is not supported.
+Fast Refresh bundles are not accepted by this one-shot loader.
+
Exporting a video component without registering a root is not sufficient. Use the [normal Remotion project structure](/docs/browser-bundler#minimal-example).
## Return value
diff --git a/packages/docs/docs/browser-bundler/table-of-contents.tsx b/packages/docs/docs/browser-bundler/table-of-contents.tsx
index 551e5ec08d..24ec932c10 100644
--- a/packages/docs/docs/browser-bundler/table-of-contents.tsx
+++ b/packages/docs/docs/browser-bundler/table-of-contents.tsx
@@ -14,10 +14,18 @@ export const TableOfContents: React.FC = () => {
<strong>loadBrowserBundle()</strong>
<div>Execute a trusted bundle and capture its registered root</div>
</TOCItem>
+ <TOCItem link="/docs/browser-bundler/create-browser-bundle-runtime">
+ <strong>createBrowserBundleRuntime()</strong>
+ <div>Apply live edits with Rspack and React Fast Refresh</div>
+ </TOCItem>
<TOCItem link="/docs/browser-bundler/get-browser-composition">
<strong>getBrowserComposition()</strong>
<div>Resolve a registered composition for playback</div>
</TOCItem>
+ <TOCItem link="/docs/browser-bundler/create-browser-composition-observer">
+ <strong>createBrowserCompositionObserver()</strong>
+ <div>Keep composition registration mounted across live edits</div>
+ </TOCItem>
</Grid>
</div>
);
diff --git a/packages/docs/sidebars.ts b/packages/docs/sidebars.ts
index 1dcd30d4f9..a4911d80ad 100644
--- a/packages/docs/sidebars.ts
+++ b/packages/docs/sidebars.ts
@@ -214,19 +214,6 @@ const sidebars: SidebarsConfig = {
'animation-utils/interpolate-styles',
],
},
- {
- type: 'category',
- label: '@remotion/browser-bundler',
- link: {
- type: 'doc',
- id: 'browser-bundler/index',
- },
- items: [
- 'browser-bundler/create-browser-bundler',
- 'browser-bundler/load-browser-bundle',
- 'browser-bundler/get-browser-composition',
- ],
- },
{
type: 'category',
label: '@remotion/bundler',
@@ -2025,6 +2012,23 @@ const sidebars: SidebarsConfig = {
items: ['canvas-capture/installation'],
},
],
+ browserBundlerSidebar: [
+ {
+ type: 'category',
+ label: '@remotion/browser-bundler',
+ link: {
+ type: 'doc',
+ id: 'browser-bundler/index',
+ },
+ items: [
+ 'browser-bundler/create-browser-bundler',
+ 'browser-bundler/load-browser-bundle',
+ 'browser-bundler/create-browser-bundle-runtime',
+ 'browser-bundler/get-browser-composition',
+ 'browser-bundler/create-browser-composition-observer',
+ ],
+ },
+ ],
};
export default sidebars;
diff --git a/packages/docs/src/data/articles.ts b/packages/docs/src/data/articles.ts
index 50f65bce94..ef28edd267 100644
--- a/packages/docs/src/data/articles.ts
+++ b/packages/docs/src/data/articles.ts
@@ -521,6 +521,15 @@ export const articles = [
noAi: false,
slug: 'brownfield',
},
+ {
+ id: 'browser-bundler/create-browser-bundle-runtime',
+ title: 'createBrowserBundleRuntime()',
+ relativePath: 'docs/browser-bundler/create-browser-bundle-runtime.mdx',
+ compId: 'articles-docs-browser-bundler-create-browser-bundle-runtime',
+ crumb: '@remotion/browser-bundler',
+ noAi: false,
+ slug: 'browser-bundler/create-browser-bundle-runtime',
+ },
{
id: 'browser-bundler/create-browser-bundler',
title: 'createBrowserBundler()',
@@ -530,6 +539,16 @@ export const articles = [
noAi: false,
slug: 'browser-bundler/create-browser-bundler',
},
+ {
+ id: 'browser-bundler/create-browser-composition-observer',
+ title: 'createBrowserCompositionObserver()',
+ relativePath:
+ 'docs/browser-bundler/create-browser-composition-observer.mdx',
+ compId: 'articles-docs-browser-bundler-create-browser-composition-observer',
+ crumb: '@remotion/browser-bundler',
+ noAi: false,
+ slug: 'browser-bundler/create-browser-composition-observer',
+ },
{
id: 'browser-bundler/get-browser-composition',
title: 'getBrowserComposition()',
diff --git a/packages/docs/static/generated/articles-docs-browser-bundler-create-browser-bundle-runtime.png b/packages/docs/static/generated/articles-docs-browser-bundler-create-browser-bundle-runtime.png
new file mode 100644
index 0000000000..a4d59718a0
Binary files /dev/null and b/packages/docs/static/generated/articles-docs-browser-bundler-create-browser-bundle-runtime.png differ
diff --git a/packages/docs/static/generated/articles-docs-browser-bundler-create-browser-composition-observer.png b/packages/docs/static/generated/articles-docs-browser-bundler-create-browser-composition-observer.png
new file mode 100644
index 0000000000..3cffcf5c06
Binary files /dev/null and b/packages/docs/static/generated/articles-docs-browser-bundler-create-browser-composition-observer.png differ
diff --git a/packages/player-example/.gitignore b/packages/player-example/.gitignore
index acce189ecf..c0851df4a9 100644
--- a/packages/player-example/.gitignore
+++ b/packages/player-example/.gitignore
@@ -10,6 +10,7 @@
# production
/build
+/public/browser-bundler-preview.js
# misc
.DS_Store
diff --git a/packages/player-example/README.md b/packages/player-example/README.md
index c361763962..d2ac8dec2d 100644
--- a/packages/player-example/README.md
+++ b/packages/player-example/README.md
@@ -2,4 +2,36 @@
## Usage
-This is an internal package and has no documentation.
+This is the internal Player testbed. Run `bun run dev` and choose an example.
+
+## Browser-compiled Player
+
+The `/browser-bundler` example compiles a conventional virtual project with
+`createBrowserBundler({enableFastRefresh: true})`. The host owns the source editor,
+compiler queue, progress, and diagnostics. Every successfully compiled bundle is
+applied in order, even when newer edits are waiting.
+
+The same-origin preview iframe has a separate, prebundled **development** React,
+React DOM, Remotion, and Player. Its bootstrap installs React Refresh before loading
+React DOM, so Fast Refresh also works when the Next.js host is a production build.
+The iframe calls `createBrowserBundleRuntime().applyBundle()` and keeps both its
+composition registration tree and Player mounted. Registered metadata is resolved
+reactively; compatible edits preserve video state, the paused frame, and playback.
+Hook-signature changes are left to React Refresh to reset.
+
+`createBrowserCompositionObserver()` from `@remotion/browser-bundler/runtime`
+isolates registration and metadata from the Player UI. Its controller accepts
+`update({root, compositionId, inputProps})`,
+reports resolved compositions through `onChange` and failures through `onError`,
+and owns cleanup through `dispose()`. Root changes, prop changes, and registration
+updates resolve metadata without rebuilding the registration tree.
+
+Run `bun run make` to generate the ignored `public/browser-bundler-preview.js`
+artifact. The `dev`, `build-site`, and `testnextjs` scripts do this automatically.
+From the repository root, `bunx turbo make --filter="@remotion/player-example"`
+also builds the workspace dependencies. `bun run testbrowserbundler` exercises the
+live-editing workflow against a production Next.js host on port 3137.
+
+The iframe is renderer isolation, **not a security sandbox**. Only run trusted
+source. The iframe bridge and preview UI belong to this example; consumers of the
+headless bundler/runtime can build their own UI without depending on Studio.
diff --git a/packages/player-example/build-browser-bundler-preview.ts b/packages/player-example/build-browser-bundler-preview.ts
new file mode 100644
index 0000000000..0c273780ee
--- /dev/null
+++ b/packages/player-example/build-browser-bundler-preview.ts
@@ -0,0 +1,15 @@
+import {build} from 'bun';
+
+const result = await build({
+ entrypoints: ['src/browser-bundler-preview/entry.ts'],
+ define: {'process.env.NODE_ENV': JSON.stringify('development')},
+ format: 'iife',
+ target: 'browser',
+ minify: true,
+ naming: 'browser-bundler-preview.js',
+ outdir: 'public',
+});
+
+if (!result.success) {
+ throw new AggregateError(result.logs, 'Could not build the Player preview.');
+}
diff --git a/packages/player-example/e2e/browser-bundler.test.ts b/packages/player-example/e2e/browser-bundler.test.ts
index f9cf42ee15..6ba30fe960 100644
--- a/packages/player-example/e2e/browser-bundler.test.ts
+++ b/packages/player-example/e2e/browser-bundler.test.ts
@@ -1,7 +1,6 @@
import {expect, test} from '@playwright/test';
-import {VERSION} from 'remotion/version';
-test('compiles conventional source paths, plays its composition and automatically recompiles edits', async ({
+test('Fast Refresh preserves an isolated Player, video state and editor focus through live edits', async ({
page,
}) => {
const pageErrors: string[] = [];
@@ -11,7 +10,10 @@ test('compiles conventional source paths, plays its composition and automaticall
await page
.getByRole('link', {name: 'Browser-compiled Player', exact: true})
.click();
- const composition = page.getByRole('region', {name: 'Compiled composition'});
+ const preview = page.frameLocator('iframe[title="Live Player preview"]');
+ const composition = preview.getByRole('region', {
+ name: 'Compiled composition',
+ });
await expect(
composition.getByRole('heading', {
name: 'Compiled in the browser',
@@ -21,46 +23,96 @@ test('compiles conventional source paths, plays its composition and automaticall
await expect(
composition.getByText('Frame 0 of 138', {exact: true}),
).toBeVisible();
+ await expect(
+ composition.getByText('1280 x 720 / 30 fps / 138 frames', {exact: true}),
+ ).toBeVisible();
+ await composition
+ .getByRole('button', {name: 'Clicks: 0', exact: true})
+ .click();
+ await composition
+ .getByRole('button', {name: 'Clicks: 1', exact: true})
+ .click();
+ const playbackRate = composition.getByRole('button', {
+ name: 'Change playback rate',
+ exact: true,
+ });
+ await playbackRate.click();
+ await composition.getByText('1.5x', {exact: true}).click();
+ const frame = composition.getByText(/^Frame \d+ of 138$/);
await composition
.getByRole('button', {name: 'Play video', exact: true})
.click();
- await expect(composition.getByText(/^Frame \d+ of 138$/)).not.toHaveText(
- 'Frame 0 of 138',
- );
+ await expect(frame).not.toHaveText('Frame 0 of 138');
await composition
.getByRole('button', {name: 'Pause video', exact: true})
.click();
+ const pausedFrame = await frame.innerText();
const editor = page.getByRole('textbox', {name: 'Video.tsx source'});
const original = await editor.inputValue();
- const dependencyRequest = page.waitForRequest((request) => {
- const url = new URL(request.url());
- return (
- url.hostname === 'esm.sh' &&
- url.pathname === `/@remotion/shapes@${VERSION}`
- );
- });
- await editor.fill(
- `import {Circle} from '@remotion/shapes';\n${original
- .replace('{title}', '{title.toUpperCase()}')
- .replace(
- '<Orb accent={accent} />',
- '<Circle radius={40} fill="red" role="img" aria-label="Bundled circle" />',
- )}`,
+ const compatibleEdit = original.replace(
+ '{title}',
+ '{title + " - refreshed"}',
+ );
+ await editor.fill(compatibleEdit);
+ await expect(
+ composition.getByRole('heading', {
+ name: 'Compiled in the browser - refreshed',
+ exact: true,
+ }),
+ ).toBeVisible();
+ await expect(
+ composition.getByRole('button', {name: 'Clicks: 2', exact: true}),
+ ).toBeVisible();
+ await expect(frame).toHaveText(pausedFrame);
+ await expect(playbackRate).toHaveText('1.5x');
+ await expect(
+ composition.getByRole('button', {name: 'Play video', exact: true}),
+ ).toBeVisible();
+ await expect(editor).toBeFocused();
+
+ const typingSource = `${compatibleEdit}\n// Consecutive edits: `;
+ const status = page.getByRole('status');
+ await editor.fill(typingSource);
+ await expect(status).toHaveText(
+ 'BrowserDemo compiled successfully with Fast Refresh.',
);
- expect(new URL((await dependencyRequest).url()).searchParams.has('dev')).toBe(
- false,
+ // Use the keyboard, not locator typing that would restore lost focus.
+ await page.keyboard.type('first', {delay: 80});
+ await expect(editor).toHaveValue(`${typingSource}first`);
+ await expect(status).toHaveText(
+ 'BrowserDemo compiled successfully with Fast Refresh.',
);
+ await expect(editor).toBeFocused();
+ await page.keyboard.type(' second', {delay: 80});
+ await expect(editor).toHaveValue(`${typingSource}first second`);
+ await expect(status).toHaveText(
+ 'BrowserDemo compiled successfully with Fast Refresh.',
+ );
+ await expect(editor).toBeFocused();
+ await expect(frame).toHaveText(pausedFrame);
+
+ await composition
+ .getByRole('button', {name: 'Play video', exact: true})
+ .click();
+ await editor.fill(original.replace('{title}', '{title + " - playing"}'));
await expect(
composition.getByRole('heading', {
- name: 'COMPILED IN THE BROWSER',
+ name: 'Compiled in the browser - playing',
exact: true,
}),
).toBeVisible();
await expect(
- composition.getByRole('img', {name: 'Bundled circle', exact: true}),
+ composition.getByRole('button', {name: 'Pause video', exact: true}),
).toBeVisible();
+ const playingFrame = await frame.innerText();
+ await expect(frame).not.toHaveText(playingFrame);
+ await expect(editor).toBeFocused();
+ await composition
+ .getByRole('button', {name: 'Pause video', exact: true})
+ .click();
+ const recoveryFrame = await frame.innerText();
await editor.fill("import {Broken from 'remotion';");
const compilationError = page
@@ -70,22 +122,67 @@ test('compiles conventional source paths, plays its composition and automaticall
await expect(compilationError).toContainText('Video.tsx');
await expect(
composition.getByRole('heading', {
- name: 'COMPILED IN THE BROWSER',
+ name: 'Compiled in the browser - playing',
exact: true,
}),
).toBeVisible();
+ await expect(frame).toHaveText(recoveryFrame);
+ await expect(
+ composition.getByRole('button', {name: 'Clicks: 2', exact: true}),
+ ).toBeVisible();
await editor.fill(original.replace('{title}', '{title + " - intermediate"}'));
- await editor.fill(original);
+ await editor.fill(original.replace('{title}', '{title + " - recovered"}'));
await expect(
composition.getByRole('heading', {
- name: 'Compiled in the browser',
+ name: 'Compiled in the browser - recovered',
exact: true,
}),
).toBeVisible();
+ await expect(compilationError).toBeHidden();
+
+ const npmSource = `import {Circle} from '@remotion/shapes';\n${original
+ .replace('{title}', '{title.toUpperCase()}')
+ .replace(
+ '<Orb accent={accent} />',
+ '<Circle radius={40} fill="red" role="img" aria-label="Bundled circle" />',
+ )}`;
+ await editor.fill(npmSource);
await expect(
- composition.getByText('Frame 0 of 138', {exact: true}),
+ composition.getByRole('heading', {
+ name: 'COMPILED IN THE BROWSER',
+ exact: true,
+ }),
+ ).toBeVisible();
+ await expect(
+ composition.getByRole('img', {name: 'Bundled circle', exact: true}),
+ ).toBeVisible();
+ await expect(
+ composition.getByRole('button', {name: 'Clicks: 2', exact: true}),
+ ).toBeVisible();
+ await expect(frame).toHaveText(recoveryFrame);
+ await expect(playbackRate).toHaveText('1.5x');
+ await expect(editor).toBeFocused();
+
+ await editor.fill(
+ npmSource
+ .replace(
+ 'const frame = useCurrentFrame();',
+ 'const [suffix] = useState("hook reset");\n const frame = useCurrentFrame();',
+ )
+ .replace('{title.toUpperCase()}', '{title + " - " + suffix}'),
+ );
+ await expect(
+ composition.getByRole('heading', {
+ name: 'Compiled in the browser - hook reset',
+ exact: true,
+ }),
+ ).toBeVisible();
+ await expect(
+ composition.getByRole('button', {name: 'Clicks: 0', exact: true}),
).toBeVisible();
+ await expect(frame).toHaveText(recoveryFrame);
+ await expect(playbackRate).toHaveText('1.5x');
await page
.getByRole('link', {name: 'All Player examples', exact: true})
@@ -102,5 +199,6 @@ test('compiles conventional source paths, plays its composition and automaticall
exact: true,
}),
).toBeVisible();
+ await expect(frame).toHaveText('Frame 0 of 138');
expect(pageErrors).toEqual([]);
});
diff --git a/packages/player-example/next.config.mjs b/packages/player-example/next.config.mjs
index 9c4fcab1ec..b4aabb5294 100644
--- a/packages/player-example/next.config.mjs
+++ b/packages/player-example/next.config.mjs
@@ -2,7 +2,12 @@
const nextConfig = {
agentRules: false,
async headers() {
- return ['/browser-bundler', '/_next/:path*'].map((source) => ({
+ return [
+ '/browser-bundler',
+ '/browser-bundler-preview.html',
+ '/browser-bundler-preview.js',
+ '/_next/:path*',
+ ].map((source) => ({
source,
headers: [
{key: 'Cross-Origin-Opener-Policy', value: 'same-origin'},
diff --git a/packages/player-example/package.json b/packages/player-example/package.json
index 26ebf4ea84..ebc87b339d 100644
--- a/packages/player-example/package.json
+++ b/packages/player-example/package.json
@@ -22,6 +22,7 @@
"next": "catalog:",
"react": "catalog:",
"react-dom": "catalog:",
+ "react-refresh": "0.18.0",
"remotion": "workspace:*",
"@remotion/media": "workspace:*"
},
@@ -32,11 +33,12 @@
"@types/node": "catalog:"
},
"scripts": {
- "formatting": "prettier src pages e2e playwright.config.ts next.config.mjs --check",
- "lint": "eslint src pages e2e playwright.config.ts next.config.mjs",
- "dev": "next dev --webpack",
- "build-site": "next build --webpack",
- "testnextjs": "next build --webpack",
+ "formatting": "prettier src pages e2e build-browser-bundler-preview.ts playwright.config.ts next.config.mjs --check",
+ "lint": "eslint src pages e2e build-browser-bundler-preview.ts playwright.config.ts next.config.mjs",
+ "make": "bun build-browser-bundler-preview.ts",
+ "dev": "bun run make && next dev --webpack",
+ "build-site": "bun run make && next build --webpack",
+ "testnextjs": "bun run make && next build --webpack",
"testbrowserbundler": "playwright test"
}
}
diff --git a/packages/player-example/public/browser-bundler-preview.html b/packages/player-example/public/browser-bundler-preview.html
new file mode 100644
index 0000000000..f22c2c9ad6
--- /dev/null
+++ b/packages/player-example/public/browser-bundler-preview.html
@@ -0,0 +1,20 @@
+<!doctype html>
+<html lang="en">
+ <head>
+ <meta charset="utf-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1" />
+ <title>Live Player preview</title>
+ <style>
+ body {
+ margin: 0;
+ font-family: sans-serif;
+ }
+ </style>
+ <script defer src="/browser-bundler-preview.js"></script>
+ </head>
+ <body>
+ <main id="browser-bundler-preview">
+ <p role="status">Loading the development Player preview…</p>
+ </main>
+ </body>
+</html>
diff --git a/packages/player-example/src/BrowserBundlerExample.tsx b/packages/player-example/src/BrowserBundlerExample.tsx
index ea3d7aa2f0..50f48fbdcc 100644
--- a/packages/player-example/src/BrowserBundlerExample.tsx
+++ b/packages/player-example/src/BrowserBundlerExample.tsx
@@ -3,20 +3,16 @@ import {
createBrowserBundler,
type VirtualProject,
} from '@remotion/browser-bundler';
-import {
- getBrowserComposition,
- loadBrowserBundle,
- type BrowserComposition,
-} from '@remotion/browser-bundler/runtime';
-import {Player} from '@remotion/player';
import Link from 'next/link';
import React, {useCallback, useEffect, useRef, useState} from 'react';
+import type {BrowserBundlerPreview} from './browser-bundler-preview/bridge';
-const initialSource = `import React from 'react';
+const initialSource = `import React, {useState} from 'react';
import {AbsoluteFill, useCurrentFrame, useVideoConfig} from 'remotion';
import {Orb} from './Orb';
export const Video: React.FC<{title: string; accent: string}> = ({title, accent}) => {
+ const [clicks, setClicks] = useState(0);
const frame = useCurrentFrame();
const {fps, durationInFrames} = useVideoConfig();
@@ -29,6 +25,13 @@ export const Video: React.FC<{title: string; accent: string}> = ({title, accent}
<div style={{position: 'relative', transform: \`translateY(\${Math.sin(frame / fps) * 12}px)\`}}>
<h1 style={{fontSize: 76, margin: 0}}>{title}</h1>
<p style={{fontSize: 28, color: accent}}>Frame {frame} of {durationInFrames}</p>
+ <button type="button" style={{fontSize: 28, padding: '8px 16px'}}
+ onClick={(event) => {
+ event.stopPropagation();
+ setClicks((value) => value + 1);
+ }}>
+ Clicks: {clicks}
+ </button>
</div>
</AbsoluteFill>
);
@@ -93,43 +96,45 @@ type CompilationState =
| {type: 'error'; message: string}
| {type: 'ready'};
+type CompilationSession = {
+ bundler: ReturnType<typeof createBrowserBundler>;
+ preview: Promise<BrowserBundlerPreview>;
+ queue: Promise<void>;
+ revision: number;
+ disposed: boolean;
+};
+
export const BrowserBundlerExample: React.FC = () => {
const [source, setSource] = useState(initialSource);
const [state, setState] = useState<CompilationState>({type: 'loading'});
- const [preview, setPreview] = useState<{
- composition: BrowserComposition;
- revision: number;
- } | null>(null);
const [progress, setProgress] = useState<string | null>(null);
const [warnings, setWarnings] = useState<string[]>([]);
- const bundlerRef = useRef<ReturnType<typeof createBrowserBundler> | null>(
- null,
- );
- const requestId = useRef(0);
- const abortRef = useRef<AbortController | null>(null);
- const compilationQueue = useRef<Promise<void>>(Promise.resolve());
+ const iframeRef = useRef<HTMLIFrameElement | null>(null);
+ const sessionRef = useRef<CompilationSession | null>(null);
const compile = useCallback(async (videoSource: string) => {
- const bundler = bundlerRef.current;
- if (!bundler) {
+ const session = sessionRef.current;
+ if (!session || session.disposed) {
return;
}
- const revision = ++requestId.current;
- abortRef.current?.abort();
- const controller = new AbortController();
- abortRef.current = controller;
+ const revision = ++session.revision;
setState({type: 'loading'});
setWarnings([]);
setProgress(null);
- compilationQueue.current = compilationQueue.current.then(async () => {
- if (controller.signal.aborted || revision !== requestId.current) {
+ session.queue = session.queue.then(async () => {
+ if (session.disposed || revision !== session.revision) {
return;
}
try {
- const bundle = await bundler.bundle({
+ const preview = await session.preview;
+ if (session.disposed || revision !== session.revision) {
+ return;
+ }
+
+ const bundle = await session.bundler.bundle({
project: {
...project,
files: {
@@ -138,26 +143,21 @@ export const BrowserBundlerExample: React.FC = () => {
},
},
});
- if (controller.signal.aborted || revision !== requestId.current) {
+ if (session.disposed) {
return;
}
- setWarnings(bundle.warnings);
- const root = loadBrowserBundle({bundle});
- const composition = await getBrowserComposition({
- root,
- compositionId: 'BrowserDemo',
- inputProps: {},
- signal: controller.signal,
- });
- if (controller.signal.aborted || revision !== requestId.current) {
+ // Coalesce edits before compilation, but never discard a compiled
+ // update: the next HMR update builds on this bundle's module graph.
+ await preview.applyBundle(bundle);
+ if (session.disposed || revision !== session.revision) {
return;
}
- setPreview({composition, revision});
+ setWarnings(bundle.warnings);
setState({type: 'ready'});
} catch (error) {
- if (controller.signal.aborted || revision !== requestId.current) {
+ if (session.disposed || revision !== session.revision) {
return;
}
@@ -167,13 +167,23 @@ export const BrowserBundlerExample: React.FC = () => {
});
}
});
- await compilationQueue.current;
+ await session.queue;
}, []);
useEffect(() => {
+ const iframe = iframeRef.current;
+ if (!iframe) {
+ setState({
+ type: 'error',
+ message: 'The Player preview iframe is missing.',
+ });
+ return;
+ }
+
let disposed = false;
try {
const bundler = createBrowserBundler({
+ enableFastRefresh: true,
onProgress: ({loadedBytes, totalBytes}) => {
if (disposed) {
return;
@@ -186,14 +196,112 @@ export const BrowserBundlerExample: React.FC = () => {
);
},
});
- bundlerRef.current = bundler;
+ let resolvePreview: (preview: BrowserBundlerPreview) => void;
+ let rejectPreview: (error: unknown) => void;
+ const preview = new Promise<BrowserBundlerPreview>((resolve, reject) => {
+ resolvePreview = resolve;
+ rejectPreview = reject;
+ });
+ const session: CompilationSession = {
+ bundler,
+ preview,
+ queue: Promise.resolve(),
+ revision: 0,
+ disposed: false,
+ };
+ sessionRef.current = session;
+ let previewRuntime: BrowserBundlerPreview | null = null;
+ let loaded = false;
+ let loadFailed = false;
+ let loadTimeout: number | null = null;
+ const reportPreviewError = (message: string) => {
+ if (!disposed) {
+ setState({type: 'error', message});
+ }
+ };
+ const failPreview = (error: unknown) => {
+ loadFailed = true;
+ if (loadTimeout !== null) {
+ window.clearTimeout(loadTimeout);
+ }
+
+ rejectPreview(error);
+ reportPreviewError(getCompilationErrorMessage(error));
+ };
+ void preview.catch((error: unknown) => {
+ reportPreviewError(getCompilationErrorMessage(error));
+ });
+ loadTimeout = window.setTimeout(
+ () =>
+ failPreview(new Error('Timed out while loading the Player preview.')),
+ 30_000,
+ );
+ const onLoad = () => {
+ if (
+ disposed ||
+ loadFailed ||
+ iframe.contentWindow?.location.href === 'about:blank'
+ ) {
+ return;
+ }
+
+ if (loaded) {
+ failPreview(
+ new Error(
+ 'The Player preview reloaded. Reload this page to reconnect.',
+ ),
+ );
+ return;
+ }
+
+ loaded = true;
+ const initialize = iframe.contentWindow?.remotionBrowserBundlerPreview;
+ if (!initialize) {
+ failPreview(
+ new Error(
+ 'Could not load the development Player preview. Run "bun run make" in packages/player-example and reload this page.',
+ ),
+ );
+ return;
+ }
+
+ void initialize
+ .then((createPreview) => {
+ if (disposed || loadFailed) {
+ return;
+ }
+
+ previewRuntime = createPreview({onError: reportPreviewError});
+ if (loadTimeout !== null) {
+ window.clearTimeout(loadTimeout);
+ }
+ resolvePreview(previewRuntime);
+ })
+ .catch(failPreview);
+ };
+ const onError = () =>
+ failPreview(new Error('The Player preview iframe failed to load.'));
+ iframe.addEventListener('load', onLoad);
+ iframe.addEventListener('error', onError);
+ iframe.src = '/browser-bundler-preview.html';
void compile(initialSource);
return () => {
disposed = true;
- abortRef.current?.abort();
- bundlerRef.current = null;
- bundler.dispose();
+ session.disposed = true;
+ sessionRef.current = null;
+ if (loadTimeout !== null) {
+ window.clearTimeout(loadTimeout);
+ }
+ iframe.removeEventListener('load', onLoad);
+ iframe.removeEventListener('error', onError);
+ rejectPreview(new Error('The Player preview was disposed.'));
+ try {
+ previewRuntime?.dispose();
+ } finally {
+ bundler.dispose();
+ iframe.src = 'about:blank';
+ }
};
} catch (error) {
setState({
@@ -212,16 +320,7 @@ export const BrowserBundlerExample: React.FC = () => {
padding: '0 20px',
}}
>
- <Link
- href="/"
- onNavigate={(event) => {
- // Leave the isolated document when returning to other examples.
- event.preventDefault();
- window.location.assign('/');
- }}
- >
- All Player examples
- </Link>
+ <Link href="/">All Player examples</Link>
<h1>Browser-compiled Player</h1>
<p>
A virtual Remotion project calls <code>registerRoot()</code>. This page
@@ -229,8 +328,10 @@ export const BrowserBundlerExample: React.FC = () => {
default props, and calculated metadata in a Player.
</p>
<p>
- Edits recompile automatically. Only run code you trust: the compiled
- code runs in this page, not in a sandbox.
+ Edits use React Fast Refresh to preserve component state and playback.
+ The persistent preview iframe bundles its own development React, even
+ when this page uses production React. Only run code you trust: this
+ same-origin iframe is not a security sandbox.
</p>
<div>
<label htmlFor="browser-video-source">
@@ -262,8 +363,8 @@ export const BrowserBundlerExample: React.FC = () => {
{state.type === 'loading'
? (progress ?? 'Compiling the virtual project...')
: state.type === 'ready'
- ? 'BrowserDemo compiled successfully.'
- : 'Compilation failed.'}
+ ? 'BrowserDemo compiled successfully with Fast Refresh.'
+ : 'Compilation or preview failed.'}
</p>
{warnings.length > 0 ? (
<section aria-label="Compiler warnings">
@@ -282,33 +383,13 @@ export const BrowserBundlerExample: React.FC = () => {
{state.message}
</pre>
) : null}
- {preview ? (
- <section aria-label="Compiled composition">
- <p>
- {preview.composition.width} x {preview.composition.height} /{' '}
- {preview.composition.fps} fps /{' '}
- {preview.composition.durationInFrames} frames
- </p>
- <Player
- key={preview.revision}
- component={preview.composition.component}
- inputProps={preview.composition.props}
- compositionWidth={preview.composition.width}
- compositionHeight={preview.composition.height}
- fps={preview.composition.fps}
- durationInFrames={preview.composition.durationInFrames}
- controls
- loop
- acknowledgeRemotionLicense
- errorFallback={({error}) => (
- <div role="alert">
- Could not play the composition: {error.message}
- </div>
- )}
- style={{width: '100%'}}
- />
- </section>
- ) : null}
+ {/* eslint-disable-next-line @remotion/warn-native-media-tag */}
+ <iframe
+ ref={iframeRef}
+ title="Live Player preview"
+ allow="autoplay; fullscreen"
+ style={{border: 0, width: '100%', aspectRatio: '1280 / 840'}}
+ />
</main>
);
};
diff --git a/packages/player-example/src/browser-bundler-preview/bridge.ts b/packages/player-example/src/browser-bundler-preview/bridge.ts
new file mode 100644
index 0000000000..1e1d669227
--- /dev/null
+++ b/packages/player-example/src/browser-bundler-preview/bridge.ts
@@ -0,0 +1,16 @@
+import type {BrowserBundle} from '@remotion/browser-bundler';
+
+export type BrowserBundlerPreview = {
+ applyBundle: (bundle: BrowserBundle) => Promise<void>;
+ dispose: () => void;
+};
+
+export type CreateBrowserBundlerPreview = (options: {
+ onError: (message: string) => void;
+}) => BrowserBundlerPreview;
+
+declare global {
+ interface Window {
+ remotionBrowserBundlerPreview: Promise<CreateBrowserBundlerPreview> | null;
+ }
+}
diff --git a/packages/player-example/src/browser-bundler-preview/entry.ts b/packages/player-example/src/browser-bundler-preview/entry.ts
new file mode 100644
index 0000000000..ff46fa78ed
--- /dev/null
+++ b/packages/player-example/src/browser-bundler-preview/entry.ts
@@ -0,0 +1,21 @@
+import ReactRefreshRuntime from 'react-refresh/runtime';
+import type {CreateBrowserBundlerPreview} from './bridge';
+
+ReactRefreshRuntime.injectIntoGlobalHook(globalThis);
+
+// React DOM must be evaluated after the development Refresh hook is installed.
+const initialize: Promise<CreateBrowserBundlerPreview> =
+ import('./runtime').then(
+ ({createBrowserBundlerPreview}) => createBrowserBundlerPreview,
+ );
+
+window.remotionBrowserBundlerPreview = initialize;
+
+void initialize.catch((error: unknown) => {
+ const message = document.createElement('p');
+ message.setAttribute('role', 'alert');
+ message.textContent = `Could not load the Player preview: ${
+ error instanceof Error ? error.message : String(error)
+ }`;
+ document.body.replaceChildren(message);
+});
diff --git a/packages/player-example/src/browser-bundler-preview/react-refresh-runtime.d.ts b/packages/player-example/src/browser-bundler-preview/react-refresh-runtime.d.ts
new file mode 100644
index 0000000000..59f9a81e5c
--- /dev/null
+++ b/packages/player-example/src/browser-bundler-preview/react-refresh-runtime.d.ts
@@ -0,0 +1,6 @@
+declare module 'react-refresh/runtime' {
+ const runtime: {
+ injectIntoGlobalHook: (globalObject: typeof globalThis) => void;
+ };
+ export = runtime;
+}
diff --git a/packages/player-example/src/browser-bundler-preview/runtime.tsx b/packages/player-example/src/browser-bundler-preview/runtime.tsx
new file mode 100644
index 0000000000..b4dc10aee2
--- /dev/null
+++ b/packages/player-example/src/browser-bundler-preview/runtime.tsx
@@ -0,0 +1,163 @@
+import {
+ createBrowserBundleRuntime,
+ createBrowserCompositionObserver,
+ type BrowserComposition,
+} from '@remotion/browser-bundler/runtime';
+import {Player} from '@remotion/player';
+import React, {useEffect} from 'react';
+import {createRoot} from 'react-dom/client';
+import type {CreateBrowserBundlerPreview} from './bridge';
+
+const Preview: React.FC<{
+ readonly composition: BrowserComposition;
+ readonly revision: number;
+ readonly onReady: (revision: number) => void;
+}> = ({composition: preview, revision, onReady}) => {
+ useEffect(() => onReady(revision), [onReady, preview, revision]);
+
+ return (
+ <section aria-label="Compiled composition">
+ <p>
+ {preview.width} x {preview.height} / {preview.fps} fps /{' '}
+ {preview.durationInFrames} frames
+ </p>
+ <Player
+ component={preview.component}
+ inputProps={preview.props}
+ compositionWidth={preview.width}
+ compositionHeight={preview.height}
+ fps={preview.fps}
+ durationInFrames={preview.durationInFrames}
+ controls
+ alwaysShowControls
+ showPlaybackRateControl
+ spaceKeyToPlayOrPause={false}
+ loop
+ acknowledgeRemotionLicense
+ errorFallback={({error}) => (
+ <p role="alert">Could not play the composition: {error.message}</p>
+ )}
+ style={{width: '100%'}}
+ />
+ </section>
+ );
+};
+
+export const createBrowserBundlerPreview: CreateBrowserBundlerPreview = ({
+ onError,
+}) => {
+ const container = document.getElementById('browser-bundler-preview');
+ if (!container) {
+ throw new Error('The Player preview container was not found.');
+ }
+
+ const runtime = createBrowserBundleRuntime();
+ let disposed = false;
+ let revision = 0;
+ let pending: {
+ revision: number;
+ resolve: () => void;
+ reject: (error: Error) => void;
+ timeout: number;
+ } | null = null;
+
+ const reportError = (error: unknown) => {
+ if (disposed) {
+ return;
+ }
+
+ const message = error instanceof Error ? error.message : String(error);
+ if (pending) {
+ window.clearTimeout(pending.timeout);
+ pending.reject(new Error(message));
+ pending = null;
+ }
+
+ onError(message);
+ };
+ const onReady = (readyRevision: number) => {
+ if (pending?.revision !== readyRevision) {
+ return;
+ }
+
+ window.clearTimeout(pending.timeout);
+ pending.resolve();
+ pending = null;
+ };
+ const root = createRoot(container, {
+ onCaughtError: reportError,
+ onUncaughtError: reportError,
+ });
+ const observer = createBrowserCompositionObserver({
+ onChange: (composition) => {
+ root.render(
+ <Preview
+ composition={composition}
+ revision={revision}
+ onReady={onReady}
+ />,
+ );
+ },
+ onError: reportError,
+ });
+
+ const dispose = () => {
+ if (disposed) {
+ return;
+ }
+
+ disposed = true;
+ window.removeEventListener('pagehide', dispose);
+ if (pending) {
+ window.clearTimeout(pending.timeout);
+ pending.reject(new Error('The Player preview was disposed.'));
+ pending = null;
+ }
+
+ try {
+ root.unmount();
+ } finally {
+ try {
+ observer.dispose();
+ } finally {
+ runtime.dispose();
+ }
+ }
+ };
+ window.addEventListener('pagehide', dispose);
+
+ return {
+ applyBundle: async (bundle) => {
+ if (disposed) {
+ throw new Error('The Player preview was disposed.');
+ }
+
+ const RegisteredRoot = await runtime.applyBundle(bundle);
+ if (disposed) {
+ throw new Error('The Player preview was disposed.');
+ }
+
+ revision++;
+ await new Promise<void>((resolve, reject) => {
+ pending = {
+ revision,
+ resolve,
+ reject,
+ timeout: window.setTimeout(
+ () =>
+ reportError(
+ new Error('Timed out while resolving the preview composition.'),
+ ),
+ 30_000,
+ ),
+ };
+ observer.update({
+ root: RegisteredRoot,
+ compositionId: 'BrowserDemo',
+ inputProps: {},
+ });
+ });
+ },
+ dispose,
+ };
+};
diff --git a/packages/player-example/turbo.json b/packages/player-example/turbo.json
new file mode 100644
index 0000000000..d5f0f2b2e2
--- /dev/null
+++ b/packages/player-example/turbo.json
@@ -0,0 +1,8 @@
+{
+ "extends": ["//"],
+ "tasks": {
+ "make": {
+ "outputs": ["public/browser-bundler-preview.js"]
+ }
+ }
+}