[RFC] Improve Next.js integration with a dedicated npm package

[garronej]

Hello everyone 👋🏻

What's the problem? 🤔

It's currently not as straight forward as it could be to setup Material UI in a Next.js project.
Users are encouraged to copy past a bunch of complicated, not type safe code from an example setup.

Proposed solution 🟢

tss-react exports a utility that abstract away the implementation of emotion's advanced approach for setting up SSR in a Next.js project:

Users are expected to set it up this way:

//pages/_app.tsx
import Head from "next/head";
import App from "next/app";
import type { AppProps } from 'next/app'
import { createEmotionSsrAdvancedApproach } from "tss-react/next";

const {
    augmentDocumentWithEmotionCache,
    withAppEmotionCache
} = createEmotionSsrAdvancedApproach({ "key": "css" });

export { augmentDocumentWithEmotionCache };

export default withAppEmotionCache(App);

//pages/_document.tsx
import Document from "next/document";
import { augmentDocumentWithEmotionCache } from "./_app";

augmentDocumentWithEmotionCache(Document);

export default Document;

This utility also works well when there's need for multiple emotion caches.

There is nothing specific to tss-react in this utility so it could be moved over to the MUI codebase:

-import { createEmotionSsrAdvancedApproach } from "tss-react/next";
+import { createEmotionSsrAdvancedApproach } from "@mui/next"; // Or whatever other path

Resources and benchmarks 🔗

• TSS
  • The documentation
  • The code
  • A demo setup
  • The demo setup live
• Mantine: @mantine/next: https://mantine.dev/guides/next/.
• Chakra: @chakra-ui/next-js: https://chakra-ui.com/getting-started/nextjs-guide

[garronej]

Hello @mnajdova @oliviertassinari,
I think this is worth reviewing, Material UI is getting a bad press for not being easy enough to use in SSR setups:

relevent timestamp

Best regards,

[oliviertassinari]

@garronej It used to be tricky to configure SSR correctly with Material UI v4. The issue was the JSS counter based approach to generate class names, once you have a mismatch it breaks the styles and is really hard to find. I would imagine it's what Theo refers to.

Now, I agree that it could be great to abstract this logic. If we do, I think that we should look into how we can make it support different Next.js's versions if they make breaking changes. For example, they have a new experimental layout system vercel/next.js#37136.

This could also open the door to more Next.js specific modules, we could abstract the Link and progress bar integration.

[garronej]

It used to be tricky to configure SSR correctly with Material UI v4. The issue was the JSS counter based approach to
generate class names, once you have a mismatch it breaks the styles and is really hard to find. I would imagine it's what
Theo refers to.

Fair enought, I wasn't aware of the legacy.

This could also open the door to more Next.js specific modules, we could abstract the Link and progress bar integration.

👍

[garronej]

For example, they have a new experimental layout system

tss-react now provides a helper for Next.js 13 appDir.

[siriwatknp]

Check out #39712

[oliviertassinari]

Related to Next.js Link integration: https://twitter.com/benmvp/status/1458609672731070468.

[garronej]

Hi @sgoodrow-zymergen,
Over on the tss-react repo, the comunity is helping me incrementally maintain a generic provider.
You can give it a shot, see if it solves your issue, no need to install tss-react, you can just copy paste the code:

https://github.com/garronej/tss-react/blob/main/src/next/appDir.tsx
https://docs.tss-react.dev/ssr/next.js

We have dark App Router + theme switchin working without issues as demonstrated here: https://next-demo.react-dsfr.fr/mui

[sgoodrow-zymergen]

Thanks @garronej, those updates do resolve the issue. Hoping this all gets bundled into a nice package soon!

[mwskwong]

@siriwatknp I noticed @mui/material-nextjs seems to be intended for Material UI specifically. It is named as such. Only the Mateiral UI doc mentions it.

Yet, this can also be used in other libraries like Joy UI by simply setting the key to joy. Why not just make this package generic, e.g '@mui/nextjs-integration and in the doc, just instruct the user to specify the correct key correspondingly?

[siriwatknp]

@siriwatknp I noticed @mui/material-nextjs seems to be intended for Material UI specifically. It is named as such. Only the Mateiral UI doc mentions it.

Yet, this can also be used in other libraries like Joy UI by simply setting the key to joy. Why not just make this package generic, e.g '@mui/nextjs-integration and in the doc, just instruct the user to specify the correct key correspondingly?

Thanks for the suggestion but there will be APIs that are specific to Material UI like Link, Image, and NProgressBar.

[oliviertassinari]

I'm reopening, I think that until the examples use the new npm package, most people won't use it (until Next.js makes a breaking change and it's less work to just use our package). It will also allow us to guarantee that it works end-to-end.

• Update the 5 Next.js examples [examples] Use material-nextjs integration package #40199

[siriwatknp]

@oliviertassinari #40199 is merged.

[oliviertassinari]

@siriwatknp I think we should update the examples before considering the problem solved: #34575 (comment).

[siriwatknp]

@siriwatknp I think we should update the examples before considering the problem solved: #34575 (comment).

As I mentioned, #40199 is the PR that update examples to use @mui/material-nextjs package and it is merged. It's in the latest master.

[oliviertassinari]

@siriwatknp Oh, got it, awesome 👌.

In the future, I think we need a @mui/system-nextjs too. Most of Material UI integration with Next.js should be concerned about components. All the style and theming logic should be into @mui/system-nextjs, providing a similar separation of concerns as we have with Shadcn.

• Radix Primitives -> Base UI
• Tailwind CSS -> MUI System
• Shadcn UI -> Material UI

This isolation of problem scopes seems to work well with what's common for developers.