Skip to content

🎥 Make videos programmatically with React

`@remotion/browser-studio`: Load GitHub projects (#10673)

Jonny Burger0efa19c0345a
diff --git a/packages/browser-studio/src/index.tsx b/packages/browser-studio/src/index.tsx
index b222aaba1f..9a0d1150e4 100644
--- a/packages/browser-studio/src/index.tsx
+++ b/packages/browser-studio/src/index.tsx
@@ -1,4 +1,5 @@
export {BrowserStudio} from './BrowserStudio';
+export {loadGitHubRepository} from './load-github-repository';
export {createBlankTemplateProject} from './templates/blank';
export type {
BrowserStudioDependencyResolution,
@@ -10,3 +11,4 @@ export type {
VirtualFileSystem,
VirtualProject,
} from './types';
+export type {LoadGitHubRepositoryProgress} from './load-github-repository';
diff --git a/packages/browser-studio/src/load-github-repository.ts b/packages/browser-studio/src/load-github-repository.ts
new file mode 100644
index 0000000000..00052d6a1e
--- /dev/null
+++ b/packages/browser-studio/src/load-github-repository.ts
@@ -0,0 +1,251 @@
+import type {VirtualProject} from './types';
+
+type GitHubTreeEntry = {
+ path: string;
+ size?: number;
+ type: 'blob' | 'commit' | 'tree';
+};
+
+type GitHubTreeResponse = {
+ message?: string;
+ sha?: string;
+ tree?: GitHubTreeEntry[];
+ truncated?: boolean;
+};
+
+export type LoadGitHubRepositoryProgress =
+ | {
+ phase: 'reading-repository';
+ }
+ | {
+ loadedBytes: number;
+ loadedFiles: number;
+ phase: 'downloading-files';
+ totalBytes: number;
+ totalFiles: number;
+ }
+ | {
+ phase: 'preparing-project';
+ };
+
+const entryPointCandidates = [
+ 'src/index.ts',
+ 'src/index.tsx',
+ 'src/index.js',
+ 'src/index.mjs',
+ 'remotion/index.tsx',
+ 'remotion/index.ts',
+ 'remotion/index.js',
+ 'remotion/index.mjs',
+ 'src/remotion/index.tsx',
+ 'src/remotion/index.ts',
+ 'src/remotion/index.js',
+ 'src/remotion/index.mjs',
+];
+
+const maximumRepositoryBytes = 100 * 1024 * 1024;
+const maximumRepositoryFiles = 2_000;
+const downloadConcurrency = 8;
+
+const parseGitHubRepositoryUrl = (repoUrl: string) => {
+ let url: URL;
+ try {
+ url = new URL(repoUrl);
+ } catch {
+ throw new Error(`Invalid GitHub repository URL: ${repoUrl}`);
+ }
+
+ if (url.protocol !== 'https:' || url.hostname !== 'github.com') {
+ throw new Error('The repo parameter must be an https://github.com URL.');
+ }
+
+ const pathSegments = url.pathname.split('/').filter(Boolean);
+ if (pathSegments.length !== 2) {
+ throw new Error(
+ 'The GitHub URL must point to a repository, for example https://github.com/remotion-dev/template-audiogram.',
+ );
+ }
+
+ const owner = pathSegments[0];
+ const repo = pathSegments[1].replace(/\.git$/, '');
+ if (
+ !owner ||
+ !repo ||
+ ![owner, repo].every((part) => /^[a-zA-Z0-9_.-]+$/.test(part))
+ ) {
+ throw new Error(`Invalid GitHub repository URL: ${repoUrl}`);
+ }
+
+ return {owner, repo};
+};
+
+const getResponseError = async (response: Response) => {
+ try {
+ const body = (await response.json()) as {message?: unknown};
+ if (typeof body.message === 'string') {
+ return body.message;
+ }
+ } catch {
+ // The GitHub raw file server generally has no JSON error body.
+ }
+
+ return response.statusText || `HTTP ${response.status}`;
+};
+
+const encodePath = (path: string) =>
+ path
+ .split('/')
+ .map((segment) => encodeURIComponent(segment))
+ .join('/');
+
+const validateRepositoryPath = (path: string) => {
+ if (
+ path.includes('\\') ||
+ path.includes('\0') ||
+ path
+ .split('/')
+ .some((segment) => segment === '' || segment === '.' || segment === '..')
+ ) {
+ throw new Error(`The repository contains an unsupported path: ${path}`);
+ }
+};
+
+const decodeTextFile = (contents: Uint8Array) => {
+ if (contents.includes(0)) {
+ return null;
+ }
+
+ try {
+ return new TextDecoder('utf-8', {fatal: true}).decode(contents);
+ } catch {
+ return null;
+ }
+};
+
+export const loadGitHubRepository = async ({
+ onProgress,
+ repoUrl,
+ signal,
+}: {
+ onProgress?: (progress: LoadGitHubRepositoryProgress) => void;
+ repoUrl: string;
+ signal?: AbortSignal;
+}): Promise<VirtualProject> => {
+ const {owner, repo} = parseGitHubRepositoryUrl(repoUrl);
+ onProgress?.({phase: 'reading-repository'});
+
+ const treeResponse = await fetch(
+ `https://api.github.com/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/git/trees/HEAD?recursive=1`,
+ {signal},
+ );
+ if (!treeResponse.ok) {
+ throw new Error(
+ `Could not read ${owner}/${repo}: ${await getResponseError(treeResponse)}`,
+ );
+ }
+
+ const tree = (await treeResponse.json()) as GitHubTreeResponse;
+ if (!tree.tree || !tree.sha) {
+ throw new Error(
+ `Could not read ${owner}/${repo}: ${tree.message ?? 'GitHub returned an invalid file tree.'}`,
+ );
+ }
+
+ const treeSha = tree.sha;
+
+ if (tree.truncated) {
+ throw new Error(
+ `${owner}/${repo} has too many files for Browser Studio to load.`,
+ );
+ }
+
+ const fileEntries = tree.tree.filter(
+ (entry): entry is GitHubTreeEntry & {type: 'blob'} => entry.type === 'blob',
+ );
+ for (const file of fileEntries) {
+ validateRepositoryPath(file.path);
+ }
+
+ if (fileEntries.length > maximumRepositoryFiles) {
+ throw new Error(
+ `${owner}/${repo} has ${fileEntries.length.toLocaleString()} files. Browser Studio supports up to ${maximumRepositoryFiles.toLocaleString()}.`,
+ );
+ }
+
+ const totalBytes = fileEntries.reduce(
+ (total, entry) => total + (entry.size ?? 0),
+ 0,
+ );
+ if (totalBytes > maximumRepositoryBytes) {
+ throw new Error(
+ `${owner}/${repo} is larger than the 100 MB Browser Studio limit.`,
+ );
+ }
+
+ let loadedBytes = 0;
+ let loadedFiles = 0;
+ const files: Record<string, string> = {};
+ const publicFiles: Record<string, Uint8Array> = {};
+ const totalFiles = fileEntries.length;
+ const reportDownloadProgress = () =>
+ onProgress?.({
+ loadedBytes,
+ loadedFiles,
+ phase: 'downloading-files',
+ totalBytes,
+ totalFiles,
+ });
+ reportDownloadProgress();
+
+ let nextFileIndex = 0;
+ await Promise.all(
+ Array.from(
+ {length: Math.min(downloadConcurrency, fileEntries.length)},
+ async () => {
+ while (nextFileIndex < fileEntries.length) {
+ const file = fileEntries[nextFileIndex++];
+ const response = await fetch(
+ `https://raw.githubusercontent.com/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/${encodeURIComponent(treeSha)}/${encodePath(file.path)}`,
+ {signal},
+ );
+ if (!response.ok) {
+ throw new Error(
+ `Could not download ${file.path}: ${await getResponseError(response)}`,
+ );
+ }
+
+ const contents = new Uint8Array(await response.arrayBuffer());
+ if (file.path.startsWith('public/')) {
+ publicFiles[file.path.slice('public/'.length)] = contents;
+ } else {
+ const text = decodeTextFile(contents);
+ if (text !== null) {
+ files[`/project/${file.path}`] = text;
+ }
+ }
+
+ loadedBytes += file.size ?? contents.byteLength;
+ loadedFiles++;
+ reportDownloadProgress();
+ }
+ },
+ ),
+ );
+
+ onProgress?.({phase: 'preparing-project'});
+ const entryPoint = entryPointCandidates.find(
+ (candidate) => files[`/project/${candidate}`] !== undefined,
+ );
+ if (!entryPoint) {
+ throw new Error(
+ `${owner}/${repo} does not have a supported Remotion entry point. Expected src/index.ts or another standard Remotion entry point.`,
+ );
+ }
+
+ return {
+ entryPoint: `/project/${entryPoint}`,
+ files,
+ publicFiles,
+ rootDir: '/project',
+ };
+};
diff --git a/packages/browser-studio/src/test/load-github-repository.test.ts b/packages/browser-studio/src/test/load-github-repository.test.ts
new file mode 100644
index 0000000000..8d89cc84c3
--- /dev/null
+++ b/packages/browser-studio/src/test/load-github-repository.test.ts
@@ -0,0 +1,114 @@
+import {afterEach, expect, test} from 'bun:test';
+import {
+ loadGitHubRepository,
+ type LoadGitHubRepositoryProgress,
+} from '../load-github-repository';
+
+const originalFetch = globalThis.fetch;
+
+afterEach(() => {
+ globalThis.fetch = originalFetch;
+});
+
+test('loads a GitHub repository into a virtual project', async () => {
+ const rawFiles: Record<string, Uint8Array | string> = {
+ 'package.json': '{"name":"example"}',
+ 'public/audio.wav': new Uint8Array([0, 1, 2, 255]),
+ 'public/captions.json': '[{"text":"Hello"}]',
+ 'Promo.png': new Uint8Array([137, 80, 78, 71, 0, 255]),
+ 'src/Root.tsx': 'export const Root = () => null;',
+ 'src/index.ts': 'import {registerRoot} from "remotion";',
+ };
+ const encoder = new TextEncoder();
+ const tree = Object.entries(rawFiles).map(([path, contents]) => ({
+ path,
+ size:
+ typeof contents === 'string'
+ ? encoder.encode(contents).byteLength
+ : contents.byteLength,
+ type: 'blob',
+ }));
+ globalThis.fetch = ((input: RequestInfo | URL) => {
+ const url = input.toString();
+ if (url.includes('api.github.com')) {
+ return Promise.resolve(
+ Response.json({
+ sha: 'ddc7ec42c2c9c06e84c9d5d2606e7ffc1394d900',
+ tree,
+ truncated: false,
+ }),
+ );
+ }
+
+ const marker = '/ddc7ec42c2c9c06e84c9d5d2606e7ffc1394d900/';
+ const path = decodeURIComponent(
+ url.slice(url.indexOf(marker) + marker.length),
+ );
+ const contents = rawFiles[path];
+ if (contents === undefined) {
+ return Promise.resolve(new Response(null, {status: 404}));
+ }
+
+ return Promise.resolve(
+ new Response(
+ typeof contents === 'string' ? contents : contents.slice().buffer,
+ ),
+ );
+ }) as unknown as typeof fetch;
+
+ const progress: LoadGitHubRepositoryProgress[] = [];
+ const project = await loadGitHubRepository({
+ onProgress: (update) => progress.push(update),
+ repoUrl: 'https://github.com/remotion-dev/example.git',
+ });
+
+ expect(project.rootDir).toBe('/project');
+ expect(project.entryPoint).toBe('/project/src/index.ts');
+ expect(project.files['/project/src/Root.tsx']).toBe(
+ 'export const Root = () => null;',
+ );
+ expect(project.files['/project/Promo.png']).toBeUndefined();
+ expect(project.publicFiles?.['audio.wav']).toEqual(
+ new Uint8Array([0, 1, 2, 255]),
+ );
+ const captions = project.publicFiles?.['captions.json'];
+ if (!(captions instanceof Uint8Array)) {
+ throw new Error('Expected captions.json to be a Uint8Array');
+ }
+
+ expect(new TextDecoder().decode(captions)).toBe('[{"text":"Hello"}]');
+ expect(progress[0]).toEqual({phase: 'reading-repository'});
+ expect(progress.at(-1)).toEqual({phase: 'preparing-project'});
+ expect(
+ progress.some(
+ (update) =>
+ update.phase === 'downloading-files' &&
+ update.loadedFiles === tree.length &&
+ update.loadedBytes === tree.reduce((sum, entry) => sum + entry.size, 0),
+ ),
+ ).toBe(true);
+});
+
+test('validates GitHub repository URLs before fetching', async () => {
+ await expect(
+ loadGitHubRepository({repoUrl: 'https://example.com/owner/repo'}),
+ ).rejects.toThrow('must be an https://github.com URL');
+ await expect(
+ loadGitHubRepository({
+ repoUrl: 'https://github.com/owner/repo/tree/main',
+ }),
+ ).rejects.toThrow('must point to a repository');
+});
+
+test('reports GitHub API errors', async () => {
+ globalThis.fetch = (() =>
+ Promise.resolve(
+ Response.json({message: 'Not Found'}, {status: 404}),
+ )) as unknown as typeof fetch;
+
+ await expect(
+ loadGitHubRepository({
+ repoUrl: 'https://github.com/remotion-dev/missing',
+ }),
+ ).rejects.toThrow('Could not read remotion-dev/missing: Not Found');
+});
diff --git a/packages/docs/src/pages/experimental_new/index.tsx b/packages/docs/src/pages/experimental_new/index.tsx
index fc5de1c672..142c701c19 100644
--- a/packages/docs/src/pages/experimental_new/index.tsx
+++ b/packages/docs/src/pages/experimental_new/index.tsx
@@ -4,6 +4,9 @@ import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
import {
BrowserStudio,
createBlankTemplateProject,
+ loadGitHubRepository,
+ type LoadGitHubRepositoryProgress,
+ type VirtualProject,
} from '@remotion/browser-studio';
import {StudioProtocolInternals} from '@remotion/studio-protocol';
import React, {useEffect, useState} from 'react';
@@ -26,6 +29,33 @@ const fallback: React.CSSProperties = {
width: '100%',
};
+const loadingBackdrop: React.CSSProperties = {
+ ...fallback,
+ backgroundColor: '#111111',
+ color: '#ffffff',
+ padding: 24,
+};
+
+const loadingDialog: React.CSSProperties = {
+ backgroundColor: '#1f1f1f',
+ border: '1px solid #3a3a3a',
+ borderRadius: 8,
+ boxShadow: '0 16px 60px rgba(0, 0, 0, 0.5)',
+ boxSizing: 'border-box',
+ color: '#ffffff',
+ maxWidth: 480,
+ padding: 24,
+ width: '100%',
+};
+
+const progressBar: React.CSSProperties = {
+ accentColor: '#0b84f3',
+ display: 'block',
+ height: 8,
+ marginTop: 20,
+ width: '100%',
+};
+
const standaloneCss = `
html,
body,
@@ -54,6 +84,28 @@ type InitialElementState =
>;
};
+type ProjectState =
+ | {type: 'ready'; project: VirtualProject}
+ | {
+ type: 'loading';
+ repoUrl: string;
+ progress: LoadGitHubRepositoryProgress;
+ }
+ | {type: 'error'; repoUrl: string; message: string};
+
+const getInitialProjectState = (): ProjectState => {
+ const repoUrl = new URLSearchParams(window.location.search).get('repo');
+ if (!repoUrl) {
+ return {type: 'ready', project: createBlankTemplateProject()};
+ }
+
+ return {
+ type: 'loading',
+ repoUrl,
+ progress: {phase: 'reading-repository'},
+ };
+};
+
const getInitialElementState = (): InitialElementState => {
const hasPayload = new URLSearchParams(window.location.hash.slice(1)).has(
'remotion-browser-studio',
@@ -83,7 +135,9 @@ const BrowserStudioContent: React.FC<{
readonly browserStudioWorkspaceCommit: string;
}> = ({browserStudioWorkspaceCommit}) => {
const [initialElementState] = useState(getInitialElementState);
- const [project] = useState(createBlankTemplateProject);
+ const [projectState, setProjectState] = useState(getInitialProjectState);
+ const loadingRepoUrl =
+ projectState.type === 'loading' ? projectState.repoUrl : null;
useEffect(() => {
if (initialElementState.type === 'none') {
@@ -97,10 +151,132 @@ const BrowserStudioContent: React.FC<{
);
}, [initialElementState.type]);
+ useEffect(() => {
+ if (loadingRepoUrl === null) {
+ return;
+ }
+
+ const controller = new AbortController();
+ loadGitHubRepository({
+ onProgress: (progress) => {
+ setProjectState((currentState) =>
+ currentState.type === 'loading'
+ ? {...currentState, progress}
+ : currentState,
+ );
+ },
+ repoUrl: loadingRepoUrl,
+ signal: controller.signal,
+ })
+ .then((project) => setProjectState({type: 'ready', project}))
+ .catch((error: unknown) => {
+ if (controller.signal.aborted) {
+ return;
+ }
+
+ setProjectState({
+ message: error instanceof Error ? error.message : String(error),
+ repoUrl: loadingRepoUrl,
+ type: 'error',
+ });
+ });
+
+ return () => controller.abort();
+ }, [loadingRepoUrl]);
+
if (initialElementState.type === 'invalid') {
return <div style={fallback}>Invalid Browser Studio payload.</div>;
}
+ if (projectState.type !== 'ready') {
+ let progress: number | null = null;
+ if (
+ projectState.type === 'loading' &&
+ projectState.progress.phase === 'downloading-files'
+ ) {
+ progress =
+ projectState.progress.totalBytes === 0
+ ? projectState.progress.totalFiles === 0
+ ? 0
+ : Math.min(
+ 1,
+ projectState.progress.loadedFiles /
+ projectState.progress.totalFiles,
+ )
+ : Math.min(
+ 1,
+ projectState.progress.loadedBytes /
+ projectState.progress.totalBytes,
+ );
+ }
+
+ return (
+ <div style={loadingBackdrop}>
+ <div aria-modal="true" role="dialog" style={loadingDialog}>
+ <div style={{fontSize: 18, fontWeight: 600}}>
+ {projectState.type === 'loading'
+ ? 'Loading GitHub project'
+ : 'Could not load GitHub project'}
+ </div>
+ <div
+ style={{
+ color: '#aaaaaa',
+ fontSize: 13,
+ marginTop: 8,
+ overflowWrap: 'anywhere',
+ }}
+ >
+ {projectState.repoUrl}
+ </div>
+ {projectState.type === 'loading' ? (
+ <>
+ <progress
+ aria-label="Loading repository"
+ max={1}
+ style={progressBar}
+ value={progress ?? undefined}
+ />
+ <div style={{color: '#cccccc', fontSize: 13, marginTop: 10}}>
+ {projectState.progress.phase === 'reading-repository'
+ ? 'Reading repository…'
+ : projectState.progress.phase === 'preparing-project'
+ ? 'Preparing project…'
+ : `Downloading files… ${Math.round((progress ?? 0) * 100)}%`}
+ </div>
+ </>
+ ) : (
+ <>
+ <div style={{color: '#ff8080', fontSize: 14, marginTop: 20}}>
+ {projectState.message}
+ </div>
+ <button
+ onClick={() =>
+ setProjectState({
+ project: createBlankTemplateProject(),
+ type: 'ready',
+ })
+ }
+ style={{
+ backgroundColor: '#0b84f3',
+ border: 0,
+ borderRadius: 4,
+ color: '#ffffff',
+ cursor: 'pointer',
+ fontSize: 14,
+ marginTop: 20,
+ padding: '8px 12px',
+ }}
+ type="button"
+ >
+ Start with a blank project
+ </button>
+ </>
+ )}
+ </div>
+ </div>
+ );
+ }
+
return (
<BrowserStudio
iframeSrc="/experimental_new/frame.html"
@@ -109,7 +285,7 @@ const BrowserStudioContent: React.FC<{
? initialElementState.payload
: null
}
- project={project}
+ project={projectState.project}
readOnly={false}
remotionPackageSource={{
baseUrl: new URL(