Material UI + Next.js 연동 스킬

Material UI와 Next.js App Router/Pages Router를 @mui/material-nextjs, Emotion 캐시 프로바이더, next/font, Tailwind/CSS 모듈 CSS 레이어, Link 컴포넌트 prop 패턴, CSS 테마 변수 SSR, App Router의 useSearchParams + Suspense로 통합합니다. MUI를 Next.js 앱에 설정하거나 디버깅할 때 사용하세요.

Material UI + Next.js 연동 스킬란 무엇인가요?

이 스킬은 Next.js 애플리케이션에서 Material UI(MUI)를 올바르게 설정하고 디버깅하기 위한 포괄적인 가이드를 제공합니다. App Router와 Pages Router 모두를 지원하며, SSR/스트리밍 환경에서 스타일이 누락되거나 순서가 잘못되는 문제를 해결합니다. 주요 기능으로는 Emotion 캐시 프로바이더(AppRouterCacheProvider, AppCacheProvider) 설정, next/font를 MUI 테마와 통합하여 CSS 변수 사용, Tailwind나 CSS Modules와의 충돌 방지를 위한 CSS 레이어(enableCssLayer) 활성화, Next.js Link 컴포넌트를 MUI Button 등에 사용할 때 발생하는 클라이언트 경계 오류 해결, 그리고 App Router에서 useSearchParams와 Suspense를 활용한 URL 기반 상태 관리 방법을 다룹니다. SKILL.md는 진입점이며, 자세한 단계별 가이드는 AGENTS.md에, import 경로 및 프로바이더 구조는 reference.md에 정리되어 있습니다.

지원 대상✓Claude Code~Codex CLI~Cursor

npx skills add https://github.com/0xAlchemist-cs/personal-ui-system/tree/HEAD/.agents/skills/material-ui-nextjs

문서

Material UI와 Next.js

Next.js + Material UI 연결을 위한 에이전트 스킬 (SSR/스트리밍, 캐시 프로바이더, 폰트, 레이어, Link, App Router URL 상태). SKILL.md는 진입점이며, AGENTS.md는 전체 가이드입니다.

적용 시점

@mui/material을 사용하는 새로운 App Router 또는 Pages Router 앱
스타일이 누락되거나 순서가 잘못됐거나 head 대신 body에 있는 경우
next/font + ThemeProvider / createTheme
Tailwind 또는 CSS Modules + MUI (enableCssLayer)
Button + component={Link} 또는 Next.js v16 클라이언트 경계 오류
useSearchParams / URL 기반 MUI 뷰 및 Suspense 경계

AGENTS.md의 섹션

영역	주제
App Router	`AppRouterCacheProvider`, `@emotion/cache`, `options`, `useSearchParams` + `<Suspense>`
Pages Router	`_document`, `_app`, `DocumentHeadTags`, `AppCacheProvider`
폰트	`'use client'` 테마, `next/font`, `html`의 CSS 변수
CSS 변수	`cssVariables`, SSR 깜빡임 문서
CSS 레이어	`enableCssLayer`, Tailwind / 기타 CSS
Link	클라이언트 래퍼, 라우팅 가이드, 예제 저장소

전체 가이드

전체 단계와 문서 링크는 AGENTS.md를 읽어보세요.

reference.md에는 import 경로와 프로바이더 구조가 나열되어 있습니다.

Material UI + Next.js 연동 스킬