❗ 문제 상황
Next.js 15(App Router) 환경에서 Ant Design v5를 사용해 구현한 SelectBox 컴포넌트가 페이지 새로고침 시 일시적으로 스타일이 풀리는 문제를 겪었다.
- 첫 렌더링 시 레이아웃이 깨짐
- 잠깐 기본 스타일로 보였다가 다시 정상 적용
FOUC(Flash of Unstyled Content) 증상이 발생
🔍 발생 원인
Ant Design v5는 전통적인 CSS 파일을 사용하는 대신 CSS-in-JS 방식으로 런타임에 스타일을 생성한다.
서버에서 HTML만 내려오고 CSS는 클라이언트 JS가 실행된 뒤에야 생성되는 것이다.
1. 서버 → 스타일 없는 HTML 전달
2. 브라우저 → HTML 먼저 렌더링
3. 클라이언트 JS 실행
4. Antd 스타일 생성 및 주입
이 과정에서 스타일이 없는 상태가 잠깐 노출되며, 그 결과 CSS가 “풀린 것처럼” 보이게 되는 것이다.
즉, SSR 환경에서 Ant Design v5 스타일이 서버 HTML에 포함되지 않는다.
✅ 해결 방법
Next.js 15 이상(App Router) 환경에서 Ant Design v5를 SSR과 함께 올바르게 사용하려면 @ant-design/nextjs-registry를 반드시 적용해야 한다.
이 레지스트리는:
- 서버 렌더링 시 Antd 컴포넌트가 사용하는 스타일을 미리 수집
- 해당 CSS를 <style> 태그로 HTML에 직접 주입
- 브라우저가 HTML + CSS를 동시에 렌더링하도록 보장
👉 결과적으로 FOUC를 완전히 방지한다.
1. 패키지 설치
npm install antd @ant-design/nextjs-registry
2. app/layout.tsx 설정
import { AntdRegistry } from "@ant-design/nextjs-registry";
export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
<html lang="ko">
<body>
<AntdRegistry>{children}</AntdRegistry>
</body>
</html>
);
}
'Frontend' 카테고리의 다른 글
| query 기반 필터 안전하게 가져오는 방법 (0) | 2025.10.13 |
|---|---|
| 얕은 복사(shallow copy) vs 깊은 복사(deep copy) (0) | 2025.09.08 |
| React input 포커스 풀림: key 관리 (2) | 2025.08.27 |
| Zod z.preprocess 활용 (1) | 2025.08.14 |
| 공통 로직 처리: 커스텀 훅 호출 위치 (1) | 2025.07.08 |
