@remotion/studio-server: Add existence-only file watcher for render outputs

Avoid readFileSync on large binary outputs by tracking path existence only
for render queue and file-existence watchers. Prevents ERR_STRING_TOO_LONG
when re-encoding to the same path as a watched output file.

Made-with: Cursor

Author: JonnyBurger

packages/cli/src/render-queue/queue.ts

@@ -223,6 +223,7 @@ const processJobIfPossible = async ({
 
 		const {unwatch} = StudioServerInternals.installFileWatcher({
 			file: path.resolve(remotionRoot, nextJob.outName),
+			existenceOnly: true,
 			onChange: (event) => {
 				if (event.type === 'created') {
 					updateJob(nextJob.id, (job) => ({

packages/studio-server/src/client-render-queue.ts

@@ -35,6 +35,7 @@ export const addCompletedClientRender = ({
 	const filePath = resolveOutputPath(remotionRoot, render.outName);
 	const {unwatch} = installFileWatcher({
 		file: filePath,
+		existenceOnly: true,
 		onChange: (event) => {
 			if (event.type === 'created' || event.type === 'deleted') {
 				updateCompletedClientRender(render.id, {

packages/studio-server/src/file-watcher.ts

@@ -14,8 +14,20 @@ type SharedWatcher = {
 	unwatch: () => void;
 };
 
+const getRegistryKey = (file: string, existenceOnly: boolean): string =>
+	existenceOnly ? `${file}\0existence-only` : file;
+
 export type FileWatcherRegistry = {
-	installFileWatcher: (options: {file: string; onChange: OnChange}) => {
+	installFileWatcher: (options: {
+		file: string;
+		onChange: OnChange;
+		/**
+		 * When true, only created/deleted events are emitted (no reads on change).
+		 * Use for binary or very large files (e.g. render output) where subscribers
+		 * only need to know whether the path exists.
+		 */
+		existenceOnly?: boolean;
+	}) => {
 		exists: boolean;
 		unwatch: () => void;
 	};
@@ -28,11 +40,14 @@ export const createFileWatcherRegistry = (): FileWatcherRegistry => {
 	const _installFileWatcher = ({
 		file,
 		onChange,
+		existenceOnly = false,
 	}: {
 		file: string;
 		onChange: OnChange;
+		existenceOnly?: boolean;
 	}): {exists: boolean; unwatch: () => void} => {
-		const existing = sharedWatchers.get(file);
+		const registryKey = getRegistryKey(file, existenceOnly);
+		const existing = sharedWatchers.get(registryKey);
 
 		if (existing) {
 			existing.subscribers.add(onChange);
@@ -43,7 +58,7 @@ export const createFileWatcherRegistry = (): FileWatcherRegistry => {
 					existing.subscribers.delete(onChange);
 					if (existing.subscribers.size === 0) {
 						existing.unwatch();
-						sharedWatchers.delete(file);
+						sharedWatchers.delete(registryKey);
 					}
 				},
 			};
@@ -65,7 +80,15 @@ export const createFileWatcherRegistry = (): FileWatcherRegistry => {
 
 			let event: FileChangeEvent | null = null;
 
-			if (!shared.existedBefore && existsNow) {
+			if (existenceOnly) {
+				if (!shared.existedBefore && existsNow) {
+					shared.existedBefore = true;
+					event = {type: 'created', content: ''};
+				} else if (shared.existedBefore && !existsNow) {
+					shared.existedBefore = false;
+					event = {type: 'deleted'};
+				}
+			} else if (!shared.existedBefore && existsNow) {
 				const content = readFileSync(file, 'utf-8');
 				shared.existedBefore = true;
 				shared.lastKnownContent = content;
@@ -102,15 +125,15 @@ export const createFileWatcherRegistry = (): FileWatcherRegistry => {
 		};
 
 		fs.watchFile(file, {interval: 100}, listener);
-		sharedWatchers.set(file, shared);
+		sharedWatchers.set(registryKey, shared);
 
 		return {
 			exists: existedAtBeginning,
 			unwatch: () => {
 				shared.subscribers.delete(onChange);
 				if (shared.subscribers.size === 0) {
 					shared.unwatch();
-					sharedWatchers.delete(file);
+					sharedWatchers.delete(registryKey);
 				}
 			},
 		};
@@ -119,7 +142,7 @@ export const createFileWatcherRegistry = (): FileWatcherRegistry => {
 	const _writeFileAndNotifyFileWatchers = (file: string, content: string) => {
 		writeFileSync(file, content);
 
-		const shared = sharedWatchers.get(file);
+		const shared = sharedWatchers.get(getRegistryKey(file, false));
 		if (!shared) {
 			return;
 		}

packages/studio-server/src/preview-server/file-existence-watchers.ts

@@ -17,6 +17,7 @@ export const subscribeToFileExistenceWatchers = ({
 
 	const {unwatch, exists} = installFileWatcher({
 		file,
+		existenceOnly: true,
 		onChange: (event) => {
 			if (event.type === 'created') {
 				waitForLiveEventsListener().then((listener) => {

packages/studio-server/src/test/file-watcher.test.ts

@@ -179,3 +179,89 @@ test('exists returns false for non-existent file', () => {
 
 	w.unwatch();
 });
+
+test('existenceOnly does not read the file when content changes', async () => {
+	const readSpy = spyOn(fs, 'readFileSync');
+
+	const cb = mock(() => {});
+
+	const w = registry.installFileWatcher({
+		file: tmpFile,
+		existenceOnly: true,
+		onChange: cb,
+	});
+
+	await new Promise((resolve) => setTimeout(resolve, 350));
+
+	writeFileSync(tmpFile, 'updated without reading');
+
+	await new Promise((resolve) => setTimeout(resolve, 350));
+
+	expect(readSpy).not.toHaveBeenCalled();
+
+	w.unwatch();
+	readSpy.mockRestore();
+});
+
+test('existenceOnly emits created with empty content when file appears', async () => {
+	const newFile = path.join(tmpDir, `existence-created-${Date.now()}.txt`);
+
+	const cb = mock(() => {});
+
+	const w = registry.installFileWatcher({
+		file: newFile,
+		existenceOnly: true,
+		onChange: cb,
+	});
+
+	expect(w.exists).toBe(false);
+
+	writeFileSync(newFile, 'hello');
+
+	await new Promise((resolve) => setTimeout(resolve, 350));
+
+	expect(cb).toHaveBeenCalledWith({type: 'created', content: ''});
+
+	w.unwatch();
+	unlinkSync(newFile);
+});
+
+test('existenceOnly emits deleted when file is removed', async () => {
+	const cb = mock(() => {});
+
+	const w = registry.installFileWatcher({
+		file: tmpFile,
+		existenceOnly: true,
+		onChange: cb,
+	});
+
+	expect(w.exists).toBe(true);
+
+	unlinkSync(tmpFile);
+
+	await new Promise((resolve) => setTimeout(resolve, 350));
+
+	expect(cb).toHaveBeenCalledWith({type: 'deleted'});
+
+	w.unwatch();
+});
+
+test('existenceOnly and content watchers on the same path use separate OS watchers', () => {
+	const watchFileSpy = spyOn(fs, 'watchFile');
+
+	const cb1 = mock(() => {});
+	const cb2 = mock(() => {});
+
+	const w1 = registry.installFileWatcher({
+		file: tmpFile,
+		existenceOnly: true,
+		onChange: cb1,
+	});
+	const w2 = registry.installFileWatcher({file: tmpFile, onChange: cb2});
+
+	expect(watchFileSpy).toHaveBeenCalledTimes(2);
+
+	w1.unwatch();
+	w2.unwatch();
+	watchFileSpy.mockRestore();
+});