Skip to content

🎥 Make videos programmatically with React

Elements: Version uploaded previews

Igor Samokhovetsf3966ab0c1df
diff --git a/.agents/skills/upload-element-previews/SKILL.md b/.agents/skills/upload-element-previews/SKILL.md
index 11852fbb20..51ffe82bcc 100644
--- a/.agents/skills/upload-element-previews/SKILL.md
+++ b/.agents/skills/upload-element-previews/SKILL.md
@@ -18,8 +18,8 @@ bun run upload-element-preview \
--source=<render|submission>
```
-To refresh an already-published preview, add `--overwrite`. The uploader accepts it only when the Element definition already uses the exact expected `https://remotion.media/elements/...` PNG and MP4 URLs.
+Each upload uses a new random URL postfix, including when the Element already has hosted previews. This keeps previews from concurrent branches independent.
-4. For a new preview, replace `image`, `posterUrl`, and `videoUrl` with the printed `remotion.media` URLs. An overwritten preview keeps its existing URLs.
+4. Replace `image`, `posterUrl`, and `videoUrl` with the newly printed `remotion.media` URLs.
5. If using `submission`, delete the local review assets. If using `render`, leave `.element-previews` uncommitted.
6. Commit and push when the work belongs on a branch.
diff --git a/packages/docs/elements/contributing.mdx b/packages/docs/elements/contributing.mdx
index ac2a889b4b..9df19265ef 100644
--- a/packages/docs/elements/contributing.mdx
+++ b/packages/docs/elements/contributing.mdx
@@ -39,7 +39,7 @@ To make previews visible in the pull request deployment:
Preview workflows:
- External contributors render previews, commit them to static/elements, and use local URLs so the pull request deployment can show them.
-- Maintainers can use the upload-element-previews skill after rendering locally (source=render) or from a contributor's committed assets (source=submission). The uploader verifies the assets, publishes them to remotion.media, and prints the replacement URLs. To refresh an already-published preview, pass --overwrite; it is accepted only when the definition uses the exact expected remotion.media URLs. Delete the static review assets after a submission upload.
+- Maintainers can use the upload-element-previews skill after rendering locally (source=render) or from a contributor's committed assets (source=submission). The uploader verifies the assets, publishes them to unique remotion.media URLs, and prints the replacements. Delete the static review assets after a submission upload.
*/}
## 3. Open the pull request
diff --git a/packages/docs/src/components/Elements/element-definitions.ts b/packages/docs/src/components/Elements/element-definitions.ts
index 61249a9441..d1e83dc285 100644
--- a/packages/docs/src/components/Elements/element-definitions.ts
+++ b/packages/docs/src/components/Elements/element-definitions.ts
@@ -59,10 +59,12 @@ export type ElementPreviewMetadata = {
readonly previewLayout: ElementPreviewLayout;
readonly posterUrl:
| `/elements/${string}-preview.png`
- | `https://remotion.media/elements/${string}-preview.png`;
+ | `https://remotion.media/elements/${string}-preview.png`
+ | `https://remotion.media/elements/${string}-preview-${string}.png`;
readonly videoUrl:
| `/elements/${string}-preview.mp4`
- | `https://remotion.media/elements/${string}-preview.mp4`;
+ | `https://remotion.media/elements/${string}-preview.mp4`
+ | `https://remotion.media/elements/${string}-preview-${string}.mp4`;
};
export type ElementDefinition = {
diff --git a/packages/docs/src/test/elements.test.ts b/packages/docs/src/test/elements.test.ts
index b43187b7ed..c03e7fa656 100644
--- a/packages/docs/src/test/elements.test.ts
+++ b/packages/docs/src/test/elements.test.ts
@@ -936,7 +936,7 @@ describe('Element preview definitions', () => {
expect(source).toContain('height: 1920');
});
- test('uses stable composition IDs and flat review or published preview paths', () => {
+ test('uses stable composition IDs and valid review or published preview paths', () => {
const compositionIds = elementDefinitionList.map((definition) =>
getElementCompositionId(definition.slug),
);
@@ -950,8 +950,12 @@ describe('Element preview definitions', () => {
: definition.slug.replaceAll('/', '-');
const localPosterUrl = `/elements/${assetSlug}-preview.png`;
const localVideoUrl = `/elements/${assetSlug}-preview.mp4`;
- const publicPosterUrl = `https://remotion.media${localPosterUrl}`;
- const publicVideoUrl = `https://remotion.media${localVideoUrl}`;
+ const publicPosterUrlPattern = new RegExp(
+ `^https://remotion\\.media/elements/${assetSlug}-preview(?:-([a-f0-9-]+))?\\.png$`,
+ );
+ const publicVideoUrlPattern = new RegExp(
+ `^https://remotion\\.media/elements/${assetSlug}-preview(?:-([a-f0-9-]+))?\\.mp4$`,
+ );
const posterPath = path.join(
staticElementsRoot,
`${assetSlug}-preview.png`,
@@ -980,8 +984,15 @@ describe('Element preview definitions', () => {
).toBeLessThanOrEqual(10 * 1024 * 1024);
}
} else {
- expect(String(definition.preview.posterUrl)).toBe(publicPosterUrl);
- expect(String(definition.preview.videoUrl)).toBe(publicVideoUrl);
+ const publicPosterUrlMatch = String(definition.preview.posterUrl).match(
+ publicPosterUrlPattern,
+ );
+ const publicVideoUrlMatch = String(definition.preview.videoUrl).match(
+ publicVideoUrlPattern,
+ );
+ expect(publicPosterUrlMatch).not.toBeNull();
+ expect(publicVideoUrlMatch).not.toBeNull();
+ expect(publicPosterUrlMatch?.[1]).toBe(publicVideoUrlMatch?.[1]);
expect(existsSync(posterPath)).toBe(false);
expect(existsSync(videoPath)).toBe(false);
}
diff --git a/packages/docs/src/test/upload-element-preview.test.ts b/packages/docs/src/test/upload-element-preview.test.ts
index 8982feb4b8..01b0fe352f 100644
--- a/packages/docs/src/test/upload-element-preview.test.ts
+++ b/packages/docs/src/test/upload-element-preview.test.ts
@@ -4,7 +4,7 @@ import {mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync} from 'fs';
import {tmpdir} from 'os';
import path from 'path';
-test('upload-element-preview only overwrites the exact hosted preview URLs', () => {
+test('upload-element-preview creates unique versions without overwriting', () => {
const temporaryDirectory = mkdtempSync(
path.join(tmpdir(), 'remotion-upload-element-preview-'),
);
@@ -66,6 +66,10 @@ test('upload-element-preview only overwrites the exact hosted preview URLs', ()
'https://remotion.media/elements/test-example-preview.png';
const expectedHostedVideoUrl =
'https://remotion.media/elements/test-example-preview.mp4';
+ const versionedHostedPosterUrl =
+ 'https://remotion.media/elements/test-example-preview-23ebc740-62e6-4ad5-987a-77f22c27cd42.png';
+ const versionedHostedVideoUrl =
+ 'https://remotion.media/elements/test-example-preview-23ebc740-62e6-4ad5-987a-77f22c27cd42.mp4';
const runUpload = ({
args,
posterUrl,
@@ -92,9 +96,9 @@ test('upload-element-preview only overwrites the exact hosted preview URLs', ()
videoUrl: expectedHostedVideoUrl,
});
expect(helpResult.status).toBe(0);
- expect(helpResult.stdout).toContain('[--overwrite]');
+ expect(helpResult.stdout).not.toContain('--overwrite');
expect(helpResult.stdout).toContain(
- 'only when the definition uses its exact https://remotion.media/elements/... URLs',
+ 'Each upload gets a unique URL so previews from concurrent branches cannot overwrite each other.',
);
const localReviewResult = runUpload({
@@ -107,15 +111,25 @@ test('upload-element-preview only overwrites the exact hosted preview URLs', ()
'Uploading requires AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY',
);
- const protectedHostedResult = runUpload({
- args: ['--element=test/example', '--source=render'],
- posterUrl: expectedHostedPosterUrl,
- videoUrl: expectedHostedVideoUrl,
- });
- expect(protectedHostedResult.status).toBe(1);
- expect(protectedHostedResult.stderr).toContain(
- 'must use its exact local review URLs',
- );
+ for (const hostedUrls of [
+ {
+ posterUrl: expectedHostedPosterUrl,
+ videoUrl: expectedHostedVideoUrl,
+ },
+ {
+ posterUrl: versionedHostedPosterUrl,
+ videoUrl: versionedHostedVideoUrl,
+ },
+ ]) {
+ const hostedResult = runUpload({
+ args: ['--element=test/example', '--source=render'],
+ ...hostedUrls,
+ });
+ expect(hostedResult.status).toBe(1);
+ expect(hostedResult.stderr).toContain(
+ 'Uploading requires AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY',
+ );
+ }
const overwriteResult = runUpload({
args: ['--element=test/example', '--source=render', '--overwrite'],
@@ -124,7 +138,7 @@ test('upload-element-preview only overwrites the exact hosted preview URLs', ()
});
expect(overwriteResult.status).toBe(1);
expect(overwriteResult.stderr).toContain(
- 'Uploading requires AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY',
+ '--overwrite is no longer supported',
);
for (const rejectedUrls of [
@@ -140,15 +154,20 @@ test('upload-element-preview only overwrites the exact hosted preview URLs', ()
posterUrl: 'https://example.com/elements/test-example-preview.png',
videoUrl: expectedHostedVideoUrl,
},
+ {
+ posterUrl: versionedHostedPosterUrl,
+ videoUrl:
+ 'https://remotion.media/elements/test-example-preview-different.mp4',
+ },
]) {
- const rejectedOverwriteResult = runUpload({
- args: ['--element=test/example', '--source=render', '--overwrite'],
+ const rejectedResult = runUpload({
+ args: ['--element=test/example', '--source=render'],
posterUrl: rejectedUrls.posterUrl,
videoUrl: rejectedUrls.videoUrl,
});
- expect(rejectedOverwriteResult.status).toBe(1);
- expect(rejectedOverwriteResult.stderr).toContain(
- 'cannot be overwritten because its preview URLs do not exactly match',
+ expect(rejectedResult.status).toBe(1);
+ expect(rejectedResult.stderr).toContain(
+ 'must use either its exact local review URLs',
);
}
} finally {
diff --git a/packages/docs/upload-element-preview.ts b/packages/docs/upload-element-preview.ts
index 59ff6e5b00..9fd2f73e46 100644
--- a/packages/docs/upload-element-preview.ts
+++ b/packages/docs/upload-element-preview.ts
@@ -1,18 +1,24 @@
import {execFileSync} from 'child_process';
+import {randomUUID} from 'crypto';
import path from 'path';
import {S3Client} from 'bun';
import {elementDefinitions} from './src/components/Elements/element-definitions';
if (process.argv.includes('--help') || process.argv.includes('-h')) {
console.log(`Usage:
- bun run upload-element-preview --element=<category>/<slug> --source=render [--overwrite]
- bun run upload-element-preview --element=<category>/<slug> --source=submission [--overwrite]
+ bun run upload-element-preview --element=<category>/<slug> --source=render
+ bun run upload-element-preview --element=<category>/<slug> --source=submission
-Use render to upload files from .element-previews. Use submission to upload committed files from static/elements. By default, the Element definition must use its exact local /elements/... review URLs. Use --overwrite to refresh an already-published preview only when the definition uses its exact https://remotion.media/elements/... URLs. The command prints the hosted URLs and any cleanup required after a verified upload.`);
+Use render to upload files from .element-previews. Use submission to upload committed files from static/elements. The Element definition must use either its exact local /elements/... review URLs or a matching pair of its existing remotion.media URLs. Each upload gets a unique URL so previews from concurrent branches cannot overwrite each other. The command prints the hosted URLs and any cleanup required after a verified upload.`);
process.exit(0);
}
-const overwrite = process.argv.includes('--overwrite');
+if (process.argv.includes('--overwrite')) {
+ throw new Error(
+ '--overwrite is no longer supported. Each upload now gets a unique URL.',
+ );
+}
+
const elementArguments = process.argv.filter((argument) =>
argument.startsWith('--element='),
);
@@ -51,30 +57,37 @@ if (!definition) {
const assetSlug = definition.slug.replaceAll('/', '-');
const expectedPosterUrl = `/elements/${assetSlug}-preview.png` as const;
const expectedVideoUrl = `/elements/${assetSlug}-preview.mp4` as const;
-const expectedHostedPosterUrl =
- `https://remotion.media${expectedPosterUrl}` as const;
-const expectedHostedVideoUrl =
- `https://remotion.media${expectedVideoUrl}` as const;
+const hostedPosterUrlPattern = new RegExp(
+ `^https://remotion\\.media/elements/${assetSlug}-preview(?:-([a-f0-9-]+))?\\.png$`,
+);
+const hostedVideoUrlPattern = new RegExp(
+ `^https://remotion\\.media/elements/${assetSlug}-preview(?:-([a-f0-9-]+))?\\.mp4$`,
+);
+const hostedPosterUrlMatch = definition.preview.posterUrl.match(
+ hostedPosterUrlPattern,
+);
+const hostedVideoUrlMatch = definition.preview.videoUrl.match(
+ hostedVideoUrlPattern,
+);
const usesLocalReviewUrls =
definition.preview.posterUrl === expectedPosterUrl &&
definition.preview.videoUrl === expectedVideoUrl;
-const usesHostedPreviewUrls =
- definition.preview.posterUrl === expectedHostedPosterUrl &&
- definition.preview.videoUrl === expectedHostedVideoUrl;
-if (!usesLocalReviewUrls) {
- if (!overwrite) {
- throw new Error(
- `${definition.slug} must use its exact local review URLs (${expectedPosterUrl} and ${expectedVideoUrl}) before its previews can be uploaded. To refresh an already-published preview, use --overwrite while the definition uses ${expectedHostedPosterUrl} and ${expectedHostedVideoUrl}.`,
- );
- }
-
- if (!usesHostedPreviewUrls) {
- throw new Error(
- `${definition.slug} cannot be overwritten because its preview URLs do not exactly match ${expectedHostedPosterUrl} and ${expectedHostedVideoUrl}.`,
- );
- }
+const usesMatchingHostedPreviewUrls =
+ hostedPosterUrlMatch !== null &&
+ hostedVideoUrlMatch !== null &&
+ hostedPosterUrlMatch[1] === hostedVideoUrlMatch[1];
+if (!usesLocalReviewUrls && !usesMatchingHostedPreviewUrls) {
+ throw new Error(
+ `${definition.slug} must use either its exact local review URLs (${expectedPosterUrl} and ${expectedVideoUrl}) or a matching pair of its existing remotion.media preview URLs.`,
+ );
}
+const previewPostfix = randomUUID();
+const hostedPosterUrl =
+ `https://remotion.media/elements/${assetSlug}-preview-${previewPostfix}.png` as const;
+const hostedVideoUrl =
+ `https://remotion.media/elements/${assetSlug}-preview-${previewPostfix}.mp4` as const;
+
const sourceDirectory =
source === 'render'
? path.join(process.cwd(), '.element-previews', definition.slug)
@@ -86,7 +99,7 @@ const assets = [
sourceDirectory,
source === 'render' ? 'preview.png' : `${assetSlug}-preview.png`,
),
- localUrl: expectedPosterUrl,
+ publicUrl: hostedPosterUrl,
},
{
contentType: 'video/mp4',
@@ -94,7 +107,7 @@ const assets = [
sourceDirectory,
source === 'render' ? 'preview.mp4' : `${assetSlug}-preview.mp4`,
),
- localUrl: expectedVideoUrl,
+ publicUrl: hostedVideoUrl,
},
] as const;
@@ -178,12 +191,6 @@ if (!Bun.env.AWS_ACCESS_KEY_ID || !Bun.env.AWS_SECRET_ACCESS_KEY) {
);
}
-if (!Bun.env.CLOUDFLARE_API_TOKEN || !Bun.env.CLOUDFLARE_ZONE_ID) {
- throw new Error(
- 'Clearing the CDN cache requires CLOUDFLARE_API_TOKEN and CLOUDFLARE_ZONE_ID in packages/docs/.env.',
- );
-}
-
const client = new S3Client({
accessKeyId: Bun.env.AWS_ACCESS_KEY_ID,
secretAccessKey: Bun.env.AWS_SECRET_ACCESS_KEY,
@@ -193,8 +200,8 @@ const client = new S3Client({
for (const asset of assets) {
const file = Bun.file(asset.filePath, {type: asset.contentType});
- const key = asset.localUrl.slice(1);
- const publicUrl = `https://remotion.media${asset.localUrl}`;
+ const publicUrl = asset.publicUrl;
+ const key = new URL(publicUrl).pathname.slice(1);
await client.write(key, file);
const remote = await client.stat(key);
@@ -221,33 +228,9 @@ for (const asset of assets) {
console.log(`Uploaded ${publicUrl} (${file.size} bytes)`);
}
-const purgeResponse = await fetch(
- `https://api.cloudflare.com/client/v4/zones/${Bun.env.CLOUDFLARE_ZONE_ID}/purge_cache`,
- {
- method: 'POST',
- headers: {
- Authorization: `Bearer ${Bun.env.CLOUDFLARE_API_TOKEN}`,
- 'Content-Type': 'application/json',
- },
- body: JSON.stringify({
- files: assets.map((asset) => `https://remotion.media${asset.localUrl}`),
- }),
- },
-);
-const purgeResult = (await purgeResponse.json()) as {
- success: boolean;
- errors?: unknown;
-};
-if (!purgeResponse.ok || !purgeResult.success) {
- throw new Error(
- `Could not clear the CDN cache: HTTP ${purgeResponse.status} ${JSON.stringify(purgeResult.errors)}`,
- );
-}
-
-console.log('Cleared the CDN cache for both preview URLs.');
-console.log('Upload verified. Preview URLs:');
-console.log(expectedHostedPosterUrl);
-console.log(expectedHostedVideoUrl);
+console.log('Upload verified. Replace image, posterUrl, and videoUrl with:');
+console.log(hostedPosterUrl);
+console.log(hostedVideoUrl);
if (source === 'submission') {
console.log('Then delete the two files from packages/docs/static/elements.');
} else {