[ESM] Publish packages in ESM module format

[Janpot]

Why

• Run untranspiled on server environments (e.g. Next.js experimental.esmxternals). Could help with https://github.com/mui-org/material-ui/issues/29742#issuecomment-982597676 to give babel-plugin-styled-components a source that is easier to statically analyze.
• Snowpack has trouble serving our library: https://github.com/mui-org/material-ui/issues/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 https://github.com/mui/material-ui/issues/35233

How

• [x] Early attempt: https://github.com/mui-org/material-ui/pull/30510

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

  • https://github.com/mui-org/material-ui/pull/26310
  • https://github.com/mui-org/material-ui/pull/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.

[samuelsycamore]

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";

[akomm]

Output .cjs file, set it under package.json should make it possible use it with tsconfig esModuleInterop: true. Currently you can't do anything in esm configured project, because there is just a .js file in the build. And this .js file uses esm syntax.

Having this issue with the AdapterXYZ exports - date-pickers.

[oliviertassinari]

Requirement for both CommonJS and ESM support from Docker: https://app.supernormal.com/posts/mui-docker-x-charts-6b722290c9c8013c6d350e8110019023

[Janpot]

Would be interested in what those infrastructure requirements are exactly. What mandates the need for a commonjs bundle? Does their bundler not understand ESM? Or does their SSR setup not compile modules on the server? It's an odd choice to try and fix this by adding a commonjs version to their chart library, rather than to force their bundler to transpile the dependency.

[DiegoAndai]

Sadly, I'm removing this issue from the v6 milestone, tentatively moving it to v7. I'll write an in-depth document on what we tried, why we're blocked, and the steps forward. As a summary, we found a blocker with Next.js Pages Router: https://github.com/vercel/next.js/issues/65056. The probable path forward is removing the esmExternals: false from our documentation infra, but that's currently blocked by https://github.com/vercel/next.js/issues/49898#issuecomment-1762202697.

esmExternal was added in https://github.com/mui/material-ui/pull/37264#issuecomment-1551116576.

[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:

https://github.com/mui/material-ui/issues/30671#issuecomment-1941097296

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/*"],
          }]
        }]