[docs] Migration to pigment and NextJS integration docs are conflicting

abriginets commented 2 months ago

Kind of issue

Missing information

Issue description

NextJS integration documentation tells us to create a theme and override Typography's fontFamily with it [https://mui.com/material-ui/migration/migrating-to-pigment-css/#configuring-the-theme]

const theme = createTheme({
  typography: {
    fontFamily: roboto.style.fontFamily,
  },
});

While in Pigment migration docs it doesn't mention the need of changing it to be like this:

 import type { Metadata } from 'next';
 import { Inter } from 'next/font/google';

+import '@mui/material-pigment-css/styles.css';

 export default function RootLayout(props) {
   return (
     <html lang="en">
       <body className={`${inter.className}`}>
       {/* this one here ^^^^^^^^^^^^^^^^^^ */}
         {props.children}
       </body>
     </html>
   );
 }

I was under impression that the first one was the only way of combining next/font and MUI, so I went by pigment migration docs and imported Roboto from next/font directly into next.config.mjs:

export const roboto = Roboto({
  weight: ['300', '400', '500', '700', '900'],
  display: 'swap',
  subsets: ['latin', 'latin-ext', 'cyrillic', 'cyrillic-ext'],
});

/**
 * @type {import('@pigment-css/nextjs-plugin').PigmentOptions}
 */
const pigmentConfig = {
  transformLibraries: ['@mui/material'],
  theme: createTheme({
    typography: {
      fontFamily: roboto.style.fontFamily,
    },

Obviously it didn't work

Error [ERR_UNSUPPORTED_DIR_IMPORT]: Directory import '/home/goodwin/flaut/flaut-nextjs/node_modules/next/font/google' is not supported resolving ES modules imported from /home/goodwin/flaut/flaut-nextjs/next.config.mjs
Did you mean to import "next/font/google/index.js"?
    at finalizeResolution (node:internal/modules/esm/resolve:259:11)
    at moduleResolve (node:internal/modules/esm/resolve:933:10)
    at defaultResolve (node:internal/modules/esm/resolve:1157:11)
    at ModuleLoader.defaultResolve (node:internal/modules/esm/loader:390:12)
    at ModuleLoader.resolve (node:internal/modules/esm/loader:359:25)
    at ModuleLoader.getModuleJob (node:internal/modules/esm/loader:234:38)
    at ModuleWrap.<anonymous> (node:internal/modules/esm/module_job:87:39)
    at link (node:internal/modules/esm/module_job:86:36) {
  code: 'ERR_UNSUPPORTED_DIR_IMPORT',
  url: 'file:///home/goodwin/flaut/flaut-nextjs/node_modules/next/font/google'
}

So here's my point. MUI doesn't explicitly tells you which way is preferable and doesn't force you into any of the possible solutions though one of them works with Pigment and the other one works by default. Is there a difference and how would it affect our apps if there is. I believe it would be better if docs were consistent and advised users to use next/font via passing class name into body tag. Or if that's only possible with Pigment, then Pigment migration docs should also highlight this change in the code snippet. Thank you.

Context

No response

Search keywords: pigment, nextjs

DiegoAndai commented 1 month ago

Hey, @abriginets! Thanks for the report. We will add a section to the Pigment CSS migration guide to cover this: https://github.com/mui/material-ui/pull/43631/files#diff-603580bb6644e16532b7ca1d7356ab1aa73aa8f9fa68a13664a6406b792db4e5

If you have some time, may I ask you to try this and confirm that is solves your issue? Thanks in advance.

abriginets commented 1 month ago

Hello, @DiegoAndai. I tried following steps from updated guide and everything seems to be easy and straighforward, no errors in the terminal now.

github-actions[bot] commented 1 month ago

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] We value your feedback @abriginets! How was your experience with our support team? If you could spare a moment, we'd love to hear your thoughts in this brief Support Satisfaction survey. Your insights help us improve!

mui / material-ui