Monorepo setup - Error: [nuqs] nuqs requires an adapter to work with your framework.

[janglad]

Context

What's your version of nuqs?
2.2.3

"nuqs": "^2.2.3",

What framework are you using?

Next JS

• ✅/❌ Next.js (app router) (with React Compiler turned on, using Turbopack in dev but issue also occurs during build)

Which version of your framework are you using?

Operating System:
  Platform: darwin
  Arch: arm64
  Version: Darwin Kernel Version 24.0.0: Mon Aug 12 20:51:54 PDT 2024; root:xnu-11215.1.10~2/RELEASE_ARM64_T6000
  Available memory (MB): 65536
  Available CPU cores: 10
Binaries:
  Node: 22.10.0
  npm: 10.9.0
  Yarn: 1.22.22
  pnpm: 9.12.2
Relevant Packages:
  next: 15.0.3 // There is a newer version (15.0.4) available, upgrade recommended!
  eslint-config-next: N/A
  react: 19.0.0-rc-fb9a90fa48-20240614
  react-dom: 19.0.0-rc-fb9a90fa48-20240614
  typescript: 5.6.3
Next.js Config:

Description

We have a turbo pnpm monorepo with next js. Nuqs has been acting up for a bit, erroring out and saying that the adapter isn't installed. This is however the case (and the adapter gets resolved fine). In the past this was fixed by uninstalling nuqs from the pacakges that used it and adding it again, however this now also isn't working. Below is relevant information about nuqs in the pnpm-lock

importers:
  apps/web:
    dependencies:
      ...
      nuqs:
        specifier: ^2.2.3
        version: 2.2.3([email protected](@babel/[email protected])(@opentelemetry/[email protected])(@playwright/[email protected])([email protected])([email protected]([email protected]))([email protected]))([email protected])

importers:
  packages/some-package-that-is-used-in-web:
    dependencies:
      ...
      nuqs:
        specifier: ^2.2.3
        version: 2.2.3([email protected](@opentelemetry/[email protected])(@playwright/[email protected])([email protected]([email protected]))([email protected]))([email protected])

packages:
   ...
  [email protected]:
    resolution: {integrity: sha512-nMCcUW06KSqEXA0xp+LiRqDpIE59BVYbjZLe0HUisJAlswfihHYSsAjYTzV0lcE1thfh8uh+LqUHGdQ8qq8rfA==}
    peerDependencies:
      '@remix-run/react': '>=2'
      next: '>=14.2.0'
      react: ^19.0.0-rc
      react-router-dom: '>=6'
    peerDependenciesMeta:
      '@remix-run/react':
        optional: true
      next:
        optional: true
      react-router-dom:
        optional: true

snapshots:
    [email protected]([email protected](@babel/[email protected])(@opentelemetry/[email protected])(@playwright/[email protected])([email protected])([email protected]([email protected]))([email protected]))([email protected]):
    dependencies:
      mitt: 3.0.1
      react: 19.0.0-rc-fb9a90fa48-20240614
    optionalDependencies:
      next: 15.0.3(@babel/[email protected])(@opentelemetry/[email protected])(@playwright/[email protected])([email protected])([email protected]([email protected]))([email protected])

  [email protected]([email protected](@opentelemetry/[email protected])(@playwright/[email protected])([email protected]([email protected]))([email protected]))([email protected]):
    dependencies:
      mitt: 3.0.1
      react: 19.0.0-rc-fb9a90fa48-20240614
    optionalDependencies:
      next: 15.0.3(@opentelemetry/[email protected])(@playwright/[email protected])([email protected]([email protected]))([email protected])

The thing that jumps out to me is the mismatch in the long string of seemingly next specific identifiers (babel/core...). I'm not sure if this maters, and if it does if this is an issue on the Nuqs side or on the pnpm side (or ours!).

[janglad]

As an update, got this resolved by manually editing the pnpm-lock and removing the first entry under snapshots in the post above. Again not sure if this is nuqs, pnpm or something on our end. FWIW uninstalling did remove every nuqs reference in the lock, adding it added both of those automatically.

[franky47]

Are you importing the adapter and using the hooks that cause the error in different packages by any chance?

I think this is what would cause the issue: different instances of the module being loaded in memory by different parts of your monorepo setup, causing the React Context reference to differ, and making nuqs hooks unaware of the adapter/provider which is under a different reference.

Since manually editing the lockfile isn't very robust, have you tried using pnpm overrides yet? It feels like it could be a good candidate for pinning the same nuqs module reference across all consuming packages.

[janglad]

Are you importing the adapter and using the hooks that cause the error in different packages by any chance?

I think this is what would cause the issue: different instances of the module being loaded in memory by different parts of your monorepo setup, causing the React Context reference to differ, and making nuqs hooks unaware of the adapter/provider which is under a different reference.

Since manually editing the lockfile isn't very robust, have you tried using pnpm overrides yet? It feels like it could be a good candidate for pinning the same nuqs module reference across all consuming packages.

This is indeed what I'm doing, and that makes a lot of sense. I'll look into that! Thanks!

[franky47]

@janglad have you had any luck in making it work?

[janglad]

@janglad have you had any luck in making it work?

I actually haven't sadly, using the overwrites you mentioned does not fix the issue when using a specifier like "2.2.3" (that version was shared between the versions either way), and using the exact one used in the lock doesn't work either.

It is working again right now due to the manual lock edit but yeah indeed just very brittle. I guess another solution would he creating a single package that just has Nuqs, and using it across the repo from there?

[franky47]

Thanks for the feedback. Would you be able to create a minimal reproduction repo?

I'm pretty sure there's got to be a pnpm config that causes/explains this behaviour, as the root of the issue is in the lock resolution, it should not require a userland fix.

If all else fails, could be a bug to escalate to PNPM.

[Philitician]

We had the same issue with our monorepo when importing components using nuqs from a turborepo package. The error went away when we included both react and nextjs as dependencies in the turborepo package. Not sure if this is the best way to solve it, but seemed to do the trick for us without fiddling with the pnpm-lock file.

[janglad]

We had the same issue with our monorepo when importing components using nuqs from a turborepo package. The error went away when we included both react and nextjs as dependencies in the turborepo package. Not sure if this is the best way to solve it, but seemed to do the trick for us without fiddling with the pnpm-lock file.

The package in question already has deps on both of those so sadly doesn't seem like a reliable way to solve it

[BjoernRave]

also a little bit hacky, but you can try to re-export everything from nuqs from your shared package and then only import from that file, so there is only one dep on nuqs in the shared package

[ktisakib]

in my case sometimes it appears it doesn't.
I am using monorepo packages and nuqs is used in one of my packages
sometimes cleanng and reinstalling fixes but comes again dont know how

[crownofapollo]

In case anyone else runs into this with turborepo, I ended up installing nuqs at the root of the repo so the same dependency is referenced in every package. Not ideal, but it worked for me.

[XsidX]

any reason we are not using this adapter? or it just came out? https://nuqs.47ng.com/docs/adapters . this worked for me but am yet to test its implications.

[franky47]

The root cause of this issue is described in the React docs in the useContext troubleshooting section:

You might be running into some build issue with your tooling that causes SomeContext as seen from the providing component and SomeContext as seen by the reading component to be two different objects. This can happen if you use symlinks, for example. You can verify this by assigning them to globals like window.SomeContext1 and window.SomeContext2 and then checking whether window.SomeContext1 === window.SomeContext2 in the console. If they’re not the same, fix that issue on the build tool level.

The NuqsAdapter is an internal context provider, so the window.SomeContext{1,2} debug tip might not work straight away, and would need a little digging into the nuqs bundled code.

If someone is feeling adventurous, here's the steps to test if the context reference had already been created:

1. Go to node_modules/nuqs/dist/adapters/{path/to/your/adapter}.js
2. Look for the chunk where createAdapterProvider is exported from, and open it (eg: node_modules/nuqs/dist/chunk-DASHEO2X.js for version 2.3.1)
3. After the line context.displayName = "NuqsAdapterContext";, insert the following code:

if (process.env.NODE_ENV === 'development') {
  if (typeof window !== 'undefined') {
    if (
      window.__NuqsAdapterContext !== undefined &&
      window.__NuqsAdapterContext !== context
    ) {
      console.error('[nuqs] Adapter context was already created')
    }
    window.__NuqsAdapterContext = context
  }
}

4. Run your app in development mode and see if an error comes up.

[franky47]

I added this in a preview PR, to make it a bit user-friendlier. Steps are now:

1. Install the preview:

pnpm add https://pkg.pr.new/nuqs@861

2. Enable debugging

It will log an error if multiple context references are loaded.