[ESM] Publish packages in ESM module format

[Janpot]

Why

• Run untranspiled on server environments (e.g. Next.js experimental.esmxternals). Could help with [styled-engine-sc] MUI + styled-components + Next.js CSS rules ordering issue #29742 (comment) to give babel-plugin-styled-components a source that is easier to statically analyze.
• Snowpack has trouble serving our library: Compilation error caused by "circular reference" (@mui/core, @mui/core/ModalUnstyled) #28628
  It looks like it’s trying to convert back the commonjs version into ESM and getting confused (this is a non-deterministic process, best effort). It seems to resolve the package specifier to the commonjs module instead of ESM
• Next.js supports ESM by default in v12
• Issues with vite module ordering which seem to get resolved when packages have exports defined
• Issues around mixed cjs/esm imports when using icons-material both in Next.js and vite [ESM] @mui/icons-material move to pure ESM #35233

How

• Early attempt: Draft: Try converting packages to ESM #30510

• Figure out what happened with these PRs and verify whether the problem is still relevant:

  • [icons] Only ship ES modules #26310
  • Revert "[icons] Only ship ES modules (#26310)" #26656

• In our build output, make sure ESM files get the extension .mjs. We can probably start with this and maybe even release on a minor

• package.json: dual ESM/commonjs: https://nodejs.org/api/packages.html#dual-commonjses-module-packages

  • Add exports field, let's leave out the "type": "module" until v7?
  • We should do this one one major (v6)

• Internal imports will need file extensions https://github.com/jaydenseric/babel-plugin-transform-require-extensions. We can probably also consider releasing this on a minor version

• How do we deal with process.env.NODE_ENV (e.g. https://github.com/mui-org/material-ui/blob/1230b1a571942f1abf2fec81812b757ceb0e5d0b/packages/mui-system/src/spacing.js#L104)? It will break when run as a module in the browser.
  Perhaps:

  // This way it won't break uncompiled, but webpack can still 
  // replace `process.env.NODE_ENV`
  import process from './process'
  
  // ...
        if (process.env.NODE_ENV !== 'production') {
          if (typeof abs !== 'number') {
            console.error(
              `MUI: Expected ${propName} argument to be a number or a string, got ${abs}.`,
            );
          }
        }
  // ...
  
  // ./process.js
  // Gracefully handle being run in the browser
  export default typeof process === 'undefined' ? { env: {} } : process;

• This doesn't work with react <=17: Bug: Cannot import 'react/jsx-runtime' from esm node/webpack 5 facebook/react#20235, We may be stuck on this until package exports are backported to react 17 (or when we can bump our react peer dependency >=18).

[MicahZoltu]

Internal imports will need file extensions https://github.com/jaydenseric/babel-plugin-transform-require-extensions

I think this should probably be extracted out into a separate issue, as it would be a boon to using Material UI natively in a browser (without a bundler/transpiler), I think even without addressing the other things mentioned here (I could be wrong though).

[cseas]

Publint is reporting that the components are written in ESM but getting interpreted as CJS.

I tried the MUI imports in a Next.js project with type: module and moduleResolution: node16 though, seems to work fine. (https://codesandbox.io/p/sandbox/angry-benji-oi33ry)

Is this because Next.js is reading the CJS exports under node/ directory instead of ESM ones?

[zbynekwinkler]

In order to be able to use @mui/icons-material in ES module (with remix), I had to use named import:

import { LockOutlined } from '@mui/icons-material';

I believe it relies on the presence of "module": "./esm/index.js" field in the installed package.json which reexports everything. Reaching out to @mui/icons-material/LockOutlinedIcon like the examples do, fails.

[mapache-salvaje]

This seems to be a blocker for getting MUI components to play nicely with Remix. Named imports appear to work fine.

❌ import Box from "@mui/joy/Box";
✅ import { Box } from "@mui/material";

[cjoecker]

As a workaround, you can do for now the following search-and-replace with regex to fix it:
Search import (.*)Icon from "@mui/icons-material/(.*)"; and replace with import { $1 as $1Icon } from "@mui/icons-material";

[Janpot]

Just recording some tips for anyone that wants to debug this:

• Remove all pages and add just a single page with

  import * as React from 'react';
  import { DataGridPro } from '@mui/x-data-grid-pro';
  
  export default function MyPage() {
    return <DataGridPro rows={[]} columns={[]} />;
  }

  This will drastically speed up the build and reproduce the error (pnpm docs:build)

• Disable the minifier to be able to inspect the bundles more easily. Look into the server bundles (.next/server/pages/...) If you've only got 1 page, there should be no code splitting happening.

  // next.config.mjs
    // ...
    webpack: (config, options) => {
      // ...
      config.optimization.minimize = false;
      config.optimization.minimizer = [];
      // ...

It looks like webpack isn't using the ESM bundle of @mui/x-data-grid. We may be able to fix this by:

• Being strict about file extensions, our packages are type: 'commonjs', so our ESM files should have the .mjs extension.
• For Node.js to be actually able to load these ESM files, we'll need to make sure the files contain only fully resolved module specifiers. This can't be done easily with our current build setup. Short term I see three potential solutions:
  • We rewrite every import to the full path without extension (so resolve index files). The add a babel plugin that adds a specific extension to each relative import. Open question: how to avoid regressions in the future? This needs to be linted somehow.
  • Build a babel plugin that resolves all relative imports and rewrites them with their full file name and extension (we can't just straight add the extension because of index.ts files)
  • Move to rollup for building (second snippet in this guide shows how to transpile a full set of files 1-to-1, just like we currently do with babel). Unlike babel, rollup is a bundler, so it should fully resolve every import. If we just compile each file 1 on 1, we can keep the type generation.

[akomm]

Currently the issue is maximized in the sense of blocking every possible simple workaround at once, by exporting .js, not .cjs (for interop workaround TS) or .mjs and at the same time using esm syntax in the .js build:

#30671 (comment)

main points to .js:

ESM syntax in .js output:

[justin-hackin]

I've gotten used to copy-pasting icons from the website into my project. I forgot about this issue and accidentally broke my app in dev. That's why I went out of my way to prevent this from happening in the future by adding an eslint rule to prevent imports of the icons as in the copypasta:

       "no-restricted-imports": ["error", {
          "patterns": [{
            "group": ["@mui/icons-material/*"],
          }]
        }]

[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 still 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.

[elyobo]

Thanks @Janpot; why the requirement to use the legacy peer deps flag?

[Janpot]

MUI X v8 packages have @mui/material as a peer dep but only v5 or v6. I don't believe it's possible to specify a dependency range for v7 as that doesn't work with alpha versions. as soon as we go stable we can update the peer dependency and the legacy peer dep flag won't be necessary anymore