feat: Detect multiple contexts loaded at the same time (#861)

Author: franky47

errors/NUQS-303.md

@@ -0,0 +1,17 @@
+# Multiple adapter contexts detected
+
+## Probable cause
+
+This error occurs in [debug mode](https://nuqs.47ng.com/docs/debugging) in
+certain monorepo setups where references of the adapter context aren't the same
+in different packages, and cause a [`NUQS-404 - nuqs requires an adapter to work with your framework`](./NUQS-404) error.
+
+## Root cause
+
+As described in the [React docs](https://react.dev/reference/react/useContext#my-component-doesnt-see-the-value-from-my-provider), this can happen with Context providers (which
+is what adapters are) being re-created in different modules and causing different
+references being used for a provider and consumers.
+
+## Possible solutions
+
+See issue [#798](https://github.com/47ng/nuqs/issues/798) for more details.

errors/NUQS-404.md

@@ -27,3 +27,18 @@ If you encounter this error outside of the browser, like in a test
 runner (eg: Vitest or Jest), you may use the [testing adapter](https://nuqs.47ng.com/docs/testing)
 from `nuqs/adapters/testing` to mock the initial search params and access
 setup/assertion testing facilities.
+
+### Monorepo setups
+
+This error can also occur in monorepo setups where components using nuqs hooks
+are in different packages resolving to different `nuqs` versions,
+leading to different context references being used.
+
+If you [enable debugging](https://nuqs.47ng.com/docs/debugging), you might see a
+[`NUQS-303 - Multiple adapter contexts detected`](./NUQS-303) error, confirming
+this hypothesis.
+
+For additional clarification, ensure that all packages use compatible versions
+of `nuqs` to prevent this issue from arising. See issue
+[#798](https://github.com/your-repo/issues/798) for more details and
+possible solutions.

packages/nuqs/src/adapters/lib/context.ts

@@ -1,4 +1,5 @@
 import { createContext, createElement, useContext, type ReactNode } from 'react'
+import { debugEnabled } from '../../debug'
 import { error } from '../../errors'
 import type { UseAdapterHook } from './defs'
 
@@ -13,6 +14,19 @@ export const context = createContext<AdapterContext>({
 })
 context.displayName = 'NuqsAdapterContext'
 
+declare global {
+  interface Window {
+    __NuqsAdapterContext?: typeof context
+  }
+}
+
+if (debugEnabled && typeof window !== 'undefined') {
+  if (window.__NuqsAdapterContext && window.__NuqsAdapterContext !== context) {
+    console.error(error(303))
+  }
+  window.__NuqsAdapterContext = context
+}
+
 /**
  * Create a custom adapter (context provider) for nuqs to work with your framework / router.
  *

packages/nuqs/src/debug.ts

@@ -1,7 +1,7 @@
-const enabled = isDebugEnabled()
+export const debugEnabled = isDebugEnabled()
 
 export function debug(message: string, ...args: any[]) {
-  if (!enabled) {
+  if (!debugEnabled) {
     return
   }
   const msg = sprintf(message, ...args)
@@ -15,7 +15,7 @@ export function debug(message: string, ...args: any[]) {
 }
 
 export function warn(message: string, ...args: any[]) {
-  if (!enabled) {
+  if (!debugEnabled) {
     return
   }
   console.warn(message, ...args)

packages/nuqs/src/errors.ts

@@ -1,4 +1,5 @@
 export const errors = {
+  303: 'Multiple adapter contexts detected. This might happen in monorepos.',
   404: 'nuqs requires an adapter to work with your framework.',
   409: 'Multiple versions of the library are loaded. This may lead to unexpected behavior. Currently using `%s`, but `%s` (via the %s adapter) was about to load on top.',
   414: 'Max safe URL length exceeded. Some browsers may not be able to accept this URL. Consider limiting the amount of state stored in the URL.',