AGENTS.md

skills/material-ui-nextjs/AGENTS.md

AGENTS.md

Quality

70/100

Scores the file, not the repository.

Length

890 words

19 headings · 1 code blocks

Repository

99k

— · pushed 0 days ago

Last changed

3 days ago

First indexed 3 days ago.

mui/material-ui/skills/material-ui-nextjs/AGENTS.mdRaw GitHub

1# Material UI and Next.js
2 
3Version 1.0.0 (Material UI v9)
4 
5> **Version notice:** This skill targets Material UI v9 (`>=9.0.0 <10.0.0`). If you are using a different major version, verify the API details before following this guidance.
6 
7> Note: This document is for agents and LLMs integrating Material UI with Next.js. Source: `docs/data/material/integrations/nextjs/nextjs.md` and related integration docs in this repository.
8 
9---
10 
11## Abstract
12 
13Material UI uses Emotion for styles. On Next.js you must wire an Emotion cache so SSR and streaming produce correct CSS (prefer injecting styles into `head` instead of only `body`). The `@mui/material-nextjs` package supplies `AppRouterCacheProvider` (App Router) and `AppCacheProvider` / `DocumentHeadTags` (Pages Router). Material UI components ship as client components (`"use client"`); they still SSR but are not React Server Components. Match the package import suffix (for example `v15-appRouter`) to your Next.js major version.
14 
15---
16 
17## Table of contents
18 
191. [App Router (recommended)](#app-router-recommended)
202. [Pages Router](#pages-router)
213. [Fonts (`next/font`)](#fonts-nextfont)
224. [CSS theme variables and SSR](#css-theme-variables-and-ssr)
235. [Other styling stacks (CSS layers)](#other-styling-stacks-css-layers)
246. [Next.js Link and `component` prop](#nextjs-link-and-component-prop)
257. [Further reading](#further-reading)
26 
27---
28 
29## App Router (recommended)
30 
31### Dependencies
32 
33Have `@mui/material` and `next` installed, then add:
34 
35- `@mui/material-nextjs`
36- `@emotion/cache`
37 
38Example: `pnpm add @mui/material-nextjs @emotion/cache`
39 
40### Root layout
41 
42In `app/layout.tsx`, wrap everything under `<body>` with `AppRouterCacheProvider` from the entry that matches your Next major, for example:
43 
44`import { AppRouterCacheProvider } from '@mui/material-nextjs/v15-appRouter';`
45 
46(Use the `v1X-appRouter` path that matches your Next.js version if not on v15.)
47 
48Why: it collects CSS from MUI System during server rendering and streaming so styles attach predictably; it is recommended so styles go to `<head>` instead of only `<body>`. See [Next.js integration—Configuration](https://mui.com/material-ui/integrations/nextjs.md#configuration).
49 
50### Optional cache `options`
51 
52Pass `options` to `AppRouterCacheProvider` to override [Emotion cache options](https://emotion.sh/docs/@emotion/cache#options), for example `key: 'css'` (the default MUI key is `mui`). See [Next.js integration—Custom cache (optional)](https://mui.com/material-ui/integrations/nextjs.md#custom-cache-optional).
53 
54### URL hooks and Suspense
55 
56Dashboards and internal tools often combine MUI client components with URL-driven UI (filters, tabs, pagination) using `useSearchParams()` from `next/navigation`.
57 
58Next.js expects a `<Suspense>` boundary around the part of the tree that uses `useSearchParams` (and similar patterns that opt the route into client-side rendering), otherwise you can get build failures or runtime errors about a missing Suspense boundary.
59 
60Practical pattern: keep `app/.../page.tsx` as a server component when possible; render a client subtree that uses components such as `Table`, `Tabs`, or `TextField` and is tied to the query string inside `<Suspense>` from that server page. Do not use `fallback={null}` for UI that occupies layout space (toolbars, filters, and similar); it tends to cause layout shift when the client mounts. Use a fallback that matches the real layout (for example `Skeleton` with `Stack` or `Box` and the same `minHeight` and rough dimensions as the final UI). Full example: [Next.js integration—URL-driven UI and the Suspense boundary](https://mui.com/material-ui/integrations/nextjs.md#url-driven-ui-and-the-suspense-boundary).
61 
62Official reference: [Next.js—`useSearchParams`](https://nextjs.org/docs/app/api-reference/functions/use-search-params) (static rendering and Suspense notes vary by major version).
63 
64---
65 
66## Pages Router
67 
68### Dependencies
69 
70Add `@mui/material-nextjs`, `@emotion/cache`, and `@emotion/server`.
71 
72Example: `pnpm add @mui/material-nextjs @emotion/cache @emotion/server`
73 
74### `_document.tsx`
75 
76- Import `DocumentHeadTags` and `documentGetInitialProps` from the `v15-pagesRouter` (or matching `v1X-pagesRouter`) entry.
77- Render `<DocumentHeadTags {...props} />` inside `<Head>`.
78- Assign `getInitialProps` to call `documentGetInitialProps`.
79 
80### `_app.tsx`
81 
82Wrap the app with `AppCacheProvider` from the same major entry (for example `v15-pagesRouter`).
83 
84### Optional: custom cache and cascade layers
85 
86- Pass a custom `emotionCache` into `documentGetInitialProps` options when needed.
87- For `@layer`, use `createEmotionCache({ enableCssLayer: true })` from `@mui/material-nextjs`, pass it from `_document` and align `_app` with the same cache pattern. See [Next.js integration—Cascade layers (optional)](https://mui.com/material-ui/integrations/nextjs.md#cascade-layers-optional).
88 
89### TypeScript
90 
91Extend `Document` props with `DocumentHeadTagsProps` from the same import path. See [Next.js integration—TypeScript](https://mui.com/material-ui/integrations/nextjs.md#typescript).
92 
93---
94 
95## Fonts (`next/font`)
96 
97App Router: theme modules that call `createTheme` need `'use client'` when they are consumed from server components. Use `next/font/google` (or local fonts), set `variable: '--font-…'`, put `className={font.variable}` on `<html>` (or as in docs), and set `typography.fontFamily` to `'var(--font-…)'`. Wrap with `ThemeProvider` inside `AppRouterCacheProvider` as needed.
98 
99Pages Router: similar pattern in `pages/_app.tsx` with `AppCacheProvider` and `ThemeProvider`.
100 
101Details: [Next.js integration—Font optimization](https://mui.com/material-ui/integrations/nextjs.md#font-optimization) (App) and [Next.js integration—Font optimization](https://mui.com/material-ui/integrations/nextjs.md#font-optimization-1) (Pages).
102 
103---
104 
105## CSS theme variables and SSR
106 
107Enable `cssVariables: true` in `createTheme` when using [CSS theme variables](https://mui.com/material-ui/customization/css-theme-variables/overview.md). For SSR flicker and `InitColorSchemeScript`, follow [CSS theme variables—Preventing SSR flickering](https://mui.com/material-ui/customization/css-theme-variables/configuration.md#preventing-ssr-flickering) and [CSS theme variables overview—Advantages](https://mui.com/material-ui/customization/css-theme-variables/overview.md#advantages). Add `suppressHydrationWarning` to `<html>` when using `colorSchemes` — the color scheme attribute is written client-side on first render and will otherwise produce a React hydration mismatch.
108 
109---
110 
111## Other styling stacks (CSS layers)
112 
113If you combine MUI with Tailwind CSS, CSS Modules, or other global CSS, set `enableCssLayer: true` on `AppRouterCacheProvider`:
114 
115`<AppRouterCacheProvider options={{ enableCssLayer: true }}>`
116 
117That wraps MUI output in `@layer mui` so anonymous layers can override as intended. See [Next.js integration—Using other styling solutions](https://mui.com/material-ui/integrations/nextjs.md#using-other-styling-solutions) and [MDN—@layer](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@layer).
118 
119---
120 
121## Next.js Link and `component` prop
122 
123Next.js v16: passing `next/link` directly into `component` can trigger "Functions cannot be passed directly to Client Components". Fix: a small client re-export:
124 
125```tsx
126'use client';
127import Link, { LinkProps } from 'next/link';
128export default Link;
129```
130 
131Import that wrapper and use `component={Link}` on `Button` and similar. See [Next.js integration—Next.js v16 Client Component restriction](https://mui.com/material-ui/integrations/nextjs.md#nextjs-v16-client-component-restriction).
132 
133Pages Router and theme-wide patterns: see [Routing libraries—Next.js Pages Router](https://mui.com/material-ui/integrations/routing.md#nextjs-pages-router) and the [material-ui-nextjs-pages-router-ts example](https://github.com/mui/material-ui/tree/master/examples/material-ui-nextjs-pages-router-ts).
134 
135---
136 
137## Further reading
138 
139| Topic                            | Link                                                                                                   |
140| :------------------------------- | :----------------------------------------------------------------------------------------------------- |
141| Full integration guide           | [Next.js integration](https://mui.com/material-ui/integrations/nextjs.md)                              |
142| Example (App Router, TypeScript) | [material-ui-nextjs-ts](https://github.com/mui/material-ui/tree/master/examples/material-ui-nextjs-ts) |
143| Routing + Link adapters          | [Routing libraries](https://mui.com/material-ui/integrations/routing.md)                               |
144| RSC vs SSR (terminology)         | [React WG discussion](https://github.com/reactwg/server-components/discussions/4)                      |
145 
146Import path cheat sheet: [reference.md](reference.md).
147

Commands it names

pnpm add @mui/material-nextjs @emotion/cache
pnpm add @mui/material-nextjs @emotion/cache @emotion/server

Sections

Material UI and Next.js
Abstract
Table of contents
App Router (recommended)
Dependencies
Root layout
Optional cache `options`
URL hooks and Suspense
Pages Router
Dependencies
`_document.tsx`
`_app.tsx`
Optional: custom cache and cascade layers
TypeScript
Fonts (`next/font`)
CSS theme variables and SSR
Other styling stacks (CSS layers)
Next.js Link and `component` prop
Further reading

What it covers

setup code-style architecture types dependencies ui

Stack — with the evidence

(1.00)

(1.00)

(1.00)

(1.00)

(0.85)

(0.70)

(0.70)

(0.70)

(0.70)

(0.70)

(0.70)

(0.60)

monorepo

(0.60)

github-actions

(0.60)

vercel

(0.60)

Format

AGENTS.md

A plain-markdown README for coding agents, deliberately unopinionated: no frontmatter, no globs, no vendor keys. That minimalism is why it became the one file a dozen different agents will read, and why it carries the least per-file targeting power of any format here.

What the corpus says about it

Repository

Owner: mui
Language: —
License: —
Archived: no

All configs in this repo

Also in mui/material-ui

Diff this repo’s formats

One repository carrying more than one format is the comparison this product exists for: does anyone actually write different content in each file, or is one a copy of the other?

The other instruction files in this repository
Repository	Format	Stack	Covers	Score	Changed
mui/material-uiAGENTS.md · 99k	AGENTS.md	typescriptjavascript+13	setupbuildtestlint-format+9	100/100	3 days ago
mui/material-uiskills/material-ui-styling/AGENTS.md · 99k	AGENTS.md	typescriptjavascript+13	styleui	58/100	3 days ago
mui/material-uiskills/material-ui-tailwind/AGENTS.md · 99k	AGENTS.md	typescriptjavascript+13	styleui	58/100	3 days ago
mui/material-uiskills/material-ui-theming/AGENTS.md · 99k	AGENTS.md	typescriptjavascript+13	setupstyleui	58/100	3 days ago

Diff against AGENTS.md Diff against skills/material-ui-styling/AGENTS.md Diff against skills/material-ui-tailwind/AGENTS.md Diff against skills/material-ui-theming/AGENTS.md

Similar configs

Same format, overlapping stack, ranked by quality.

Same format, overlapping stack, ranked by quality
Repository	Format	Stack	Covers	Score	Changed
mui/material-uiAGENTS.md · 99k	AGENTS.md	typescriptjavascript+13	setupbuildtestlint-format+9	100/100	3 days ago
SkeneTechnologies/skene-cookbookAGENTS.md · 51	AGENTS.md	pythoneslint+4	setupbuildtestlint-format+7	100/100	2 days ago
wpscanteam/wpscanAGENTS.md · 9.7k	AGENTS.md	rubyvue+3	setupbuildteststyle+6	100/100	2 days ago
code-yeongyu/oh-my-openagentpackages/web/AGENTS.md · 67k	AGENTS.md	typescriptbun+10	setupbuildtestlint-format+6	100/100	2 days ago
aaif-goose/gooseAGENTS.md · 52k	AGENTS.md	rusttypescript+2	setupbuildtestlint-format+6	100/100	3 days ago
n8n-io/n8npackages/@n8n/agents/AGENTS.md · 199k	AGENTS.md	typescriptlangchain+16	buildteststylearch+3	100/100	3 days ago
duckduckgo/content-scope-scriptsspecial-pages/AGENTS.md · 70	AGENTS.md	typescriptjavascript+5	buildteststylearch+3	100/100	3 days ago
TryGhost/Ghoste2e/AGENTS.md · 55k	AGENTS.md	typescriptjavascript+12	setupteststylearch+2	100/100	3 days ago