Next.js + HANUI 프로젝트 세팅 가이드

Next.js 프로젝트에서 HANUI 쓰려고 하는데 뭐부터 해야 하지?

처음 세팅할 때 은근 헷갈리는 부분들 있어서 정리해봤어요.

1. Next.js 프로젝트 생성

설정 옵션:

Tailwind CSS는 Yes 필수예요. HANUI가 Tailwind 기반이거든요.

2. HANUI 설치

CLI가 알아서 해주는 것들:

• @hanui/react 패키지 설치
• tailwind.config.ts KRDS 설정 추가
• globals.css 스타일 설정
• lib/utils.ts cn 유틸 생성
• components.json 설정 파일 생성

3. 컴포넌트 추가

설치된 컴포넌트는 src/components/ui/ 폴더에 들어가요.

4. 사용하기

5. KRDS 폰트 설정

KRDS는 Pretendard GOV 폰트를 사용해요. app/layout.tsx에 추가:

폰트 파일은 Pretendard GOV에서 다운로드하세요.

CDN을 쓰고 싶으면:

6. tailwind.config.ts 확인

npx hanui init 하면 자동으로 설정되지만, 수동으로 하려면:

hanuiPreset에 KRDS 색상, 타이포그래피, 간격 등 다 들어있어요.

7. 공통 레이아웃 구성

공공 웹사이트 기본 구조:

SkipLink는 웹접근성 필수 요소예요. 키보드 사용자가 본문으로 바로 이동할 수 있게 해줘요.

8. 개발 서버 실행

http://localhost:3000 에서 확인하세요.

폴더 구조 추천

트러블슈팅

Tailwind 클래스 안 먹힘

tailwind.config.ts의 content에 경로 확인:

폰트 적용 안 됨

globals.css에 추가:

TypeScript 에러

tsconfig.json paths 확인:

정리

1. create-next-app (Tailwind 포함)
2. npx hanui init
3. npx hanui add [컴포넌트]
4. 폰트 설정
5. 레이아웃 구성

5분이면 KRDS 기반 프로젝트 세팅이 끝나요.

더 자세한 내용은 hanui.io에서 확인하세요.

---

관련 글:

• HANUI 컴포넌트 시스템 소개
• KRDS 디자인 토큰 완전 정복
• 폼 컴포넌트 구현기

관련 프로젝트:

• HANUI — KRDS 기반 React 디자인 시스템
• claude-settings — Claude Code 슬래시 커맨드 모음