mui · siriwatknp · Dec 11, 2023 · Nov 21, 2023 · Nov 21, 2023 · Nov 22, 2023
diff --git a/.codesandbox/ci.json b/.codesandbox/ci.json
@@ -16,6 +16,7 @@
     "packages/mui-styled-engine",
     "packages/mui-styled-engine-sc",
     "packages/mui-material-next",
+    "packages/mui-material-nextjs",
     "packages/mui-joy"
   ],
   "publishDirectory": {
@@ -32,6 +33,7 @@
     "@mui/utils": "packages/mui-utils/build",
     "@mui/base": "packages/mui-base/build",
     "@mui/material-next": "packages/mui-material-next/build",
+    "@mui/material-nextjs": "packages/mui-material-nextjs/build",
     "@mui/joy": "packages/mui-joy/build"
   },
   "sandboxes": [

diff --git a/docs/babel.config.js b/docs/babel.config.js
@@ -18,6 +18,7 @@ const alias = {
   '@mui/utils': '../packages/mui-utils/src',
   '@mui/base': '../packages/mui-base/src',
   '@mui/material-next': '../packages/mui-material-next/src',
+  '@mui/material-nextjs': '../packages/mui-material-nextjs/src',
   '@mui/joy': '../packages/mui-joy/src',
   docs: './',
   modules: '../modules',

diff --git a/docs/data/material/guides/next-js-app-router/next-js-app-router.md b/docs/data/material/guides/next-js-app-router/next-js-app-router.md
diff --git a/docs/data/material/guides/nextjs/nextjs.md b/docs/data/material/guides/nextjs/nextjs.md
@@ -0,0 +1,142 @@
+# Next.js Integration
+
+<p class="description">Learn how to use Material UI with Next.js</p>
+
+## App Router
+
+This section walks through the Material UI integration with the Next.js [App Router](https://nextjs.org/docs/app), an evolution of the [Pages Router](#pages-router), and, currently, the recommended way of building new Next.js applications starting from version 13.
+
+### Intalling the dependencies
+
+Start by ensuring that you already have `@mui/material` and `next` installed.
+Then, run one of the following commands to install the dependencies:
+
+<codeblock storageKey="package-manager">
+
+```bash npm
+npm install @mui/material-nextjs @emotion/cache
+```
+
+```bash yarn
+yarn add @mui/material-nextjs @emotion/cache
+```
+
+```bash pnpm
+pnpm add @mui/material-nextjs @emotion/cache
+```
+
+</codeblock>
+
+### Configuration
+
+Inside `app/layout.tsx`, import the `AppRouterCacheProvider` and wrap all elements under the `<body>` with it:
+
+```diff
+ // app/layout.tsx
++ import { AppRouterCacheProvider } from '@mui/material-nextjs/v13-appRouter'; // or `v14-appRouter` if you are using Next.js v14
+
+ export default function RootLayout(props) {
+   const { children } = props;
+   return (
+     <html lang="en">
+       <body>
++        <AppRouterCacheProvider>{children}</AppRouterCacheProvider>
+       </body>
+     </html>
+   );
+ }
+```
+
+### Using other styling solutions
+
+If you are using a styling solution other than Emotion to customize Material UI components, set `enableCssLayer: true` in the `options` prop:
+
+```js
+<AppRouterCacheProvider options={{ enableCssLayer: true }}>
+```
+
+This option ensures that the styles generated by Material UI will be wrapped in a CSS `@layer mui` rule, which is overridden by anonymous layer styles when using Material UI with CSS modules, Tailwind CSS, or even plain CSS without using `@layer`.
+
+To learn more about it, see [the MDN CSS layer documentation](https://developer.mozilla.org/en-US/docs/Web/CSS/@layer).
+
+## Pages Router
+
+This section walks through the Material UI integration with the Next.js [Pages Router](https://nextjs.org/docs/pages/building-your-application), for both [Server Side Rendering](https://nextjs.org/docs/pages/building-your-application/rendering/server-side-rendering) (SSR) and [Static Site Generation](https://nextjs.org/docs/pages/building-your-application/rendering/static-site-generation) (SSG).
+
+### Intalling the dependencies
+
+Start by ensuring that you already have `@mui/material` and `next` installed.
+Then, run one of the following commands to install the dependencies:
+
+<codeblock storageKey="package-manager">
+
+```bash npm
+npm install @mui/material-nextjs @emotion/cache @emotion/server
+```
+
+```bash yarn
+yarn add @mui/material-nextjs @emotion/cache @emotion/server
+```
+
+```bash pnpm
+pnpm add @mui/material-nextjs @emotion/cache @emotion/server
+```
+
+</codeblock>
+
+### Configuration
+
+Inside the `pages/_document.tsx` file:
+
+- Import `documentGetInitialProps` and use it as the Document's `getInitialProps`.
+- Import `DocumentHeadTags` and render it inside the `<Head>`.
+
+```diff
++ import { DocumentHeadTags, documentGetInitialProps } from '@mui/material-nextjs/v13-pagesRouter'; // or `v14-pagesRouter` if you are using Next.js v14
+
+ export default function MyDocument(props) {
+   return (
+     <Html lang="en">
+       <Head>
++        <DocumentHeadTags {...props} />
+         ...
+       </Head>
+       <body>
+         <Main />
+         <NextScript />
+       </body>
+     </Html>
+   );
+ }
+
++ MyDocument.getInitialProps = documentGetInitialProps;
+```
+
+Then, inside `pages/_app.tsx`, import the `AppCacheProvider` component and render it as the root element:
+
+```diff
++ import { AppCacheProvider } from '@mui/material-nextjs/v13-pagesRouter'; // or `v14-pages` if you are using Next.js v14
+
+ export default function MyApp(props) {
+   return (
++    <AppCacheProvider {...props}>
+       <Head>
+         ...
+       </Head>
+       ...
++    </AppCacheProvider>
+   );
+ }
+```
+
+### TypeScript
+
+If you are using TypeScript, add `DocumentHeadTagsProps` to the Document's props interface:
+
+```diff
++ import type { DocumentHeadTagsProps } from '@mui/material-nextjs/v13-pagesRouter'; // or `v14-pagesRouter` if you are using Next.js v14
+
++ export default function MyDocument(props: DocumentProps & DocumentHeadTagsProps) {
+   ...
+ }
+```