Cannot resolve @mui/utils/getReactNodeRef

[o-alexandrov]

Steps to reproduce

1. Look at @mui/base on NPM, it tries to import a non-existent file
   • import getReactNodeRef from '@mui/utils/getReactNodeRef';

NPM file /@mui/base/Portal/Portal.js

2. Look at @mui/utils on NPM it doesn't contain getReactNodeRef

Current behavior

Error trace:

Could not resolve "@mui/utils/getReactNodeRef"

    ../node_modules/@mui/base/Portal/Portal.js:6:28:
      6 │ ...t getReactNodeRef from '@mui/utils/getReactNodeRef';
        ╵                           ~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  You can mark the path "@mui/utils/getReactNodeRef" as external
  to exclude it from the bundle, which will remove this error and
  leave the unresolved path in the bundle.

2:36:21 PM [vite] error while updating dependencies:
Error: Build failed with 1 error:
../node_modules/@mui/base/Portal/Portal.js:6:28: ERROR: Could not resolve "@mui/utils/getReactNodeRef"
    at failureErrorWithLog (/material-ui-pigment-css-vite-ts/node_modules/esbuild/lib/main.js:1472:15)
    at /material-ui-pigment-css-vite-ts/node_modules/esbuild/lib/main.js:945:25
    at /material-ui-pigment-css-vite-ts/node_modules/esbuild/lib/main.js:1353:9
    at process.processTicksAndRejections (node:internal/process/task_queues:105:5)

Your environment

npx @mui/envinfo

  System:
    OS: macOS 15.0.1
  Binaries:
    Node: 22.9.0 - /opt/homebrew/bin/node
    npm: 10.8.3 - /opt/homebrew/bin/npm
    pnpm: 9.9.0 - /opt/homebrew/bin/pnpm
  Browsers:
    Chrome: 129.0.6668.91
    Edge: 112.0.1722.39
    Safari: 18.0.1
  npmPackages:
    @emotion/react:  11.13.3 
    @emotion/styled:  11.13.0 
    @mui/base:  5.0.0-beta.58 
    @mui/core-downloads-tracker:  6.1.3 
    @mui/icons-material:  6.1.3 
    @mui/lab:  6.0.0-beta.11 
    @mui/material:  6.1.3 
    @mui/material-pigment-css:  6.1.3 
    @mui/private-theming:  6.1.3 
    @mui/styled-engine:  6.1.3 
    @mui/system:  6.1.3 
    @mui/types:  7.2.18 
    @mui/utils:  6.1.3 
    @pigment-css/react:  0.0.24 
    @pigment-css/vite-plugin:  0.0.24 
    @types/react:  18.3.11 
    react:  18.3.1 
    react-dom:  18.3.1 
    typescript:  5.5.4 

Search keywords: @mui/base, @mui/utils getReactNodeRef

[o-alexandrov]

You introduced this issue in @mui/utils 6.1.2.
When fixing, it’s probably a good idea to fix release triggers for @mui/base

[o-alexandrov]

Even the latest @mui/base on npm 5.0.0-beta.58-dev.20240919-130050-82a6448768 does not contain latest code from this repo to avoid a breaking change.
Pinging the last 3 devs who worked on mui/base so you are aware your changes are not reflected on npm:
@sai6855 @aarongarciah @oliviertassinari

[mnajdova]

We should have pinned the versions of the @mui/base's dependencies when we stopped releasing it. Otherwise, we will need to keep releasing it until we actually plan to provide the migration to @base_ui/react. We can release the package with the release today to mitigate these issues. cc @DiegoAndai

[aarongarciah]

Indeed. I think this is the culprit #43957 (comment). Note to self: whenever a version bump is suggested by the release script, don't ignore it.

[DiegoAndai]

We're releasing an updated @mui/base version at #44104. The fix for this is already there. @o-alexandrov, may I ask you to test with that PR's build to see if the issue is fixed? You can do so by adding the following in your package.json:

"resolutions": {
  "@mui/base": "https://pkg.csb.dev/mui/material-ui/commit/b0bcfcf6/@mui/base",
}

[DiegoAndai]

@mnajdova @aarongarciah I'm not sure we should pin the versions. It might be more complex for the team to deal with different utils versions than updating @mui/base. It will depend on how many times @mui/base will require updates. I expect it not to be too frequent, so I propose not pinning the versions at this moment. What do you think?

[o-alexandrov]

@DiegoAndai thank you for the quick upcoming release, it resolves this issue

[github-actions]

This issue has been closed. If you have a similar problem but not exactly the same, please open a new issue.
Now, if you have additional information related to this issue or things that could help future readers, feel free to leave a comment.

Note

@o-alexandrov How did we do? Your experience with our support team matters to us. If you have a moment, please share your thoughts in this short Support Satisfaction survey.

[oliviertassinari]

If I understand correctly, the problem was:

1. We did this change: packages/mui-base/src/Portal/Portal.tsx

 import * as React from 'react';
 import * as ReactDOM from 'react-dom';
 import PropTypes from 'prop-types';
-import getReactNodeRef from '@mui/utils/getReactNodeRef';
+import getReactElementRef from '@mui/utils/getReactElementRef';

in https://github.com/mui/material-ui/pull/43022/files#diff-6a7ffcecb079d43c7d19f218cc19daa9c03fa6129a780194dac0f67e58f824c9R5

which is ok, the important piece is that we deleted packages/mui-utils/src/getReactNodeRef/getReactNodeRef.ts. It's a breaking change at the @mui/utils level.

2. We have a range dependence on @mui/utils

   material-ui/packages/mui-base/package.json

   Line 46 in b84c85d

   "@mui/utils": "workspace:^",

   
   

   material-ui/packages/mui-material/package.json

   Line 47 in b84c85d

   "@mui/utils": "workspace:^",

MUI X, etc.

3. So it broke

---

It looks like HEAD is not in a working state. If we treat @mui/utils as unstable, we must upgrade all dependents to pin the version, MUI X, Material UI, etc. If we treat @mui/utils as stable, we have to add the old API back until the next major. Since we use @mui/utils in the docs, I believe anything that we expose without unstable_ can be considered public API.

So we should add the old API back, no? I'm reopening to have space to discuss this further. Thoughts?

For the long term, we have https://mui-org.notion.site/engineering-mui-utils-purpose-9a9fc9da3a004864b6c4e1f4d1f24f95 on better organizing those utils.

Edit: Ah great, @Janpot spotted it this too in #44112.

---

Note to self: whenever a version bump is suggested by the release script, don't ignore it.

@aarongarciah To be nuanced, this only made the problem more visible, it didn't create the issue. In the same way, releasing a new version helps but doesn't solve the problem. Actually, we can't fully solve the problem, only do our best to mitigate the spread of it.

[Janpot]

So we should add the old API back, no?

👍 we should put old API back, we can't retroactively narrow down those ranges of older dependent packages, so they would be forever broken. For the future we'll have to make a choice: Either pin internal dependencies, or follow semver for internal APIs. (And if we choose the latter, we can't use unstable_ APIs internally as they won't follow semver)

[cristopher55]

Hello everyone, I don´t get the technicalities of the development of this library so I ask as a user.
What is the solution or mitigation I have to do to use the library without errors? I downgraded to other versions of Mui Base as low as beta 40 but the error keeps on appearing and is breaking my webpage.

[DiegoAndai]

@cristopher55 version @mui/[email protected] should work.

I will be on vacation the following weeks so I won't be able to lead this effort, I'm reassigning to @aarongarciah so we add the old API back, let's also add a deprecation message.

[oliviertassinari]

For people landing here from this error (Could not resolve "@mui/utils/getReactNodeRef"), you need one of those two cases to be met to solve the problem:

• @mui/utils ≥ 6.1.2 and @mui/base ≥ 5.0.0-beta.59
• @mui/utils < 6.1.2 and @mui/base < 5.0.0-beta.59

[cristopher55]

For people landing here from this error (Could not resolve "@mui/utils/getReactNodeRef"), you need one of those two cases to be met to solve the problem:

• @mui/utils ≥ 6.1.2 and @mui/base ≥ 5.0.0-beta.59
• @mui/utils < 6.1.2 and @mui/base < 5.0.0-beta.59

Thanks a lot it worked perfectly 😄