Ignore duplicate lib registrations in Next dev

steveruizok · steveruizok · commit cc920c01d365 · 2026-03-10T16:31:40.000Z
Avoid false-positive multiple-instance warnings caused by Next.js Fast Refresh re-executing module code. Add an isNextjsDev() helper and only skip exact duplicate registrations when running in Next.js development mode (process.env.NODE_ENV === 'development' and global __NEXT_DATA__ present). Update tests to stub __NEXT_DATA__, toggle NODE_ENV and restore it, and add a new test that verifies duplicates still trigger a warning outside Next.js dev mode. Files changed: packages/utils/src/lib/version.ts, packages/utils/src/lib/version.test.ts.
diff --git a/packages/utils/src/lib/version.test.ts b/packages/utils/src/lib/version.test.ts
@@ -294,17 +294,35 @@ describe('version utilities', () => {
 			expect(mockConsoleLog).not.toHaveBeenCalled()
 		})
 
-		it('should ignore duplicate registrations of the same library', () => {
-			// Re-registering the same library with the same version and module type
-			// (e.g. due to module re-evaluation in Next.js dev mode) should not
-			// trigger a warning
+		it('should ignore duplicate registrations in Next.js dev mode', () => {
+			// In Next.js dev mode, Fast Refresh re-executes module-level code which causes
+			// the same library to register multiple times, producing a false positive warning.
+			vi.stubGlobal('__NEXT_DATA__', {})
+			const originalNodeEnv = process.env.NODE_ENV
+			process.env.NODE_ENV = 'development'
+
 			registerTldrawLibraryVersion('@tldraw/editor', '2.0.0', 'esm')
 			registerTldrawLibraryVersion('@tldraw/editor', '2.0.0', 'esm')
 			registerTldrawLibraryVersion('@tldraw/editor', '2.0.0', 'esm')
 
 			vi.runAllTimers()
 
 			expect(mockConsoleLog).not.toHaveBeenCalled()
+
+			process.env.NODE_ENV = originalNodeEnv
+		})
+
+		it('should detect duplicate registrations outside Next.js dev mode', () => {
+			// Outside Next.js dev, duplicate exact registrations should still be
+			// tracked and trigger the multiple instances warning
+			registerTldrawLibraryVersion('@tldraw/editor', '2.0.0', 'esm')
+			registerTldrawLibraryVersion('@tldraw/editor', '2.0.0', 'esm')
+
+			vi.runAllTimers()
+
+			expect(mockConsoleLog).toHaveBeenCalled()
+			const logMessage = mockConsoleLog.mock.calls[0][0]
+			expect(logMessage).toContain('multiple instances')
 		})
 
 		it('should handle bundler misconfiguration scenario', () => {
diff --git a/packages/utils/src/lib/version.ts b/packages/utils/src/lib/version.ts
@@ -93,10 +93,17 @@ export function registerTldrawLibraryVersion(name?: string, version?: string, mo
 	}
 
 	const info = getLibraryVersions()
-	const isDuplicate = info.versions.some(
-		(v) => v.name === name && v.version === version && v.modules === modules
-	)
-	if (isDuplicate) return
+
+	// In Next.js dev mode, Fast Refresh re-executes module-level code which causes
+	// the same library to register multiple times, producing a false positive warning.
+	// We skip exact duplicates only in Next.js dev to avoid hiding genuine issues.
+	if (isNextjsDev()) {
+		const isDuplicate = info.versions.some(
+			(v) => v.name === name && v.version === version && v.modules === modules
+		)
+		if (isDuplicate) return
+	}
+
 	info.versions.push({ name, version, modules })
 
 	if (!info.scheduledNotice) {
@@ -223,6 +230,14 @@ function format(value: string, formatters: (keyof typeof formats)[] = []) {
 	return `\x1B[${formatters.map((f) => formats[f]).join(';')}m${value}\x1B[m`
 }
 
+function isNextjsDev(): boolean {
+	try {
+		return process.env.NODE_ENV === 'development' && '__NEXT_DATA__' in globalThis
+	} catch {
+		return false
+	}
+}
+
 function entry<K, V>(map: Map<K, V>, key: K, defaultValue: V): V {
 	if (map.has(key)) {
 		return map.get(key)!
