[ESM] Feature a distribution compatible with Node in "type": "module"

[garronej]

Steps to reproduce 🕹

Hi MUI team,

Steps to Reproduce:

You can reproduce the problem using the below repository:

git clone https://github.com/garronej/mui-import-esm  
cd mui-import-esm
yarn install
node index.mjs

Current behavior 😯

Node is unable to import MUI in the type: "module" environment.

We're getting Error [ERR_UNSUPPORTED_DIR_IMPORT]: Directory import '/Users/joseph/github/mui-import-esm/node_modules/@mui/material/styles' when importing any submodule of @mui/material.

Expected behavior 🤔

MUI should be correctly imported when running under Node's ESM environment.

Context 🔦

As the publisher of modules that depend on MUI, such as tss-react and onyxia-ui, I've encountered some problems with distributing real ECMAScript Modules (ESM) due to MUI's lack of a functional ESM distribution compatible with a "type": "module" node environment. While MUI does provide an ESM distribution that works with bundlers, it unfortunately fails to do the same for node.

Proposed Solutions:

To resolve the above issue, an additional entry to node_modules/@mui/material/package.json could potentially fix the problem:

  "exports": {
    "./styles": {
      "default": "./node/styles/index.js"
    },
    "./Button": {
      "default": "./node/Button/index.js"
    }
  }

Implementing this works for import { useStyles } from "@mui/material/styles" but doesn't function correctly for import Button from "@mui/material/Button". This issue arises as Button is represented as an object, rather than as the default function.

For the above scenario, there are two possible strategies:

• Adopt @Andarist's Emotion strategy: Expose a .mjs file that reexports everything from the CommonJS ESModuleInterop distribution (See an example here). This strategy allows for correct defaults. And avoiding the dual package hazard. MUI also stands to gain nothing by being a real ESM, as it does not support lazy imports.

• Publish a full, standards-compliant ESM distribution: Similar to tsafe.

The popularity of this comment based on its upvotes demonstrates that other developers are experiencing similar issues.

Regardless, I appreciate all the hard work done by the MUI team. Thank you!

Your environment 🌎

No response

[Andarist]

Implementing this works for import { useStyles } from "@mui/material/styles"

This is true but at the same time, this is also possible in node and I'd consider this to be a problem:

import ns from "@mui/material/styles"
ns.useStyles

[garronej]

I'd consider this to be a problem

Really? I'm surprised that you think it's a problem.
To achieve total compliance with the standard upon importing the default from @mui/material/styles, we should encounter the following runtime error:

import ns from "@mui/material/styles"
            ^^^
SyntaxError: The requested module '@mui/material/styles' does not provide an export named 'default'

However, bear in mind that allowSyntheticDefaultImports is enabled by default in TypeScript. Thus, TypeScript won't raise any objections when you attempt to import it in this manner.

Publish a full, standards-compliant ESM distribution: Similar to tsafe.

Following further examination, I recommend not implementing this option, even if it appears to be the sensible path. @Andarist has made the correct choice. Publishing an actual Node compliant ESM distribution will result in situations where MUI is duplicated. If it helps, I can demonstrate this through a repository.

[garronej]

Upon conducting a thorough investigation, it appears there isn't a straightforward solution to this problem there will be a solution once Anderist's PR on Vite gets merged.

Not providing a distribution compatible with the "type: module" mode of Node.js isn't ideal. However, there's also no apparent way (to my knowledge) to provide this distribution without generating the potential risk of a dual package hazard.

For further illustration, I've created a repository where I demonstrate an issue present in Emotion but not in MUI. Here's the link for your reference: https://github.com/garronej/vite-dual-package-repro-repo.

[Andarist]

This particular issue is a Vite bug, you can track the fix here: vitejs/vite#13370

[michaldudak]

Hey guys, sorry for the late response - I was on vacation.
I'm looking forward to the day when everything will be ESM, and we won't have such problems.
I wonder what the impact would be for the community if we shipped just pure ESM. I think this is something we need to consider for the future (cc @Janpot, @alexfauquette, @flaviendelangle).

As for this particular thread, if I read it correctly, once Vite 4.4 is released, the problem will be solvable, right?

[Andarist]

As for this particular thread, if I read it correctly, once Vite 4.4 is released, the problem will be solvable, right?

Yes, it should be solvable. Note that solving this in full on your side requires some serious package.json#exports gymnastics but it's doable - as far as I could verify it. Emotion shipped using this strategy and so far we didn't quite get any issue reports about this, apart from the mentioned Vite issue and the one that you have found here. The first one (Vite issue) is supposed to get fixed soon (in the mentioned 4.4 release) but we are still waiting for any kind of response from the Vercel team. Note that the Next.js issue isn't affecting everybody - you have to mix ESM and CJS files in a particular way to end up with that issue and it's not something that people do often.

I wonder what the impact would be for the community if we shipped just pure ESM. I think this is something we need to consider for the future (cc @Janpot, @alexfauquette, @flaviendelangle).

Likely... it could be quite severe 😅 and that's definitely not something that you can consider within the current major version. I'm also looking for ESM days ahead of us but, quite frankly, I'm rather afraid of paving the way with my libraries and I'm waiting for other people to start doing that at scale to join them at some point.

[Janpot]

Maybe not an ideal solution, but none of them are, so for completeness: To mitigate dual package problems we could also consider adding a check at runtime and warn/error when a module is loaded that has a different format than the previous loaded ones.

[Janpot]

Proper dual ESM/commonjs packages were released in 7.0.0-alpha.1. If you want to try it out, you can take the following steps:

1. Set the version of all your @mui/* packages to next
2. Install dependencies (if you use npm, install with --legacy-peer-deps)

If you run into issues with this, please report back to us.

[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

@garronej 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.