Next.js에서 사용하기
App Router에서 YD-UI를 사용하는 설정입니다. React 19.1 이상과 Tailwind CSS 4가 필요합니다. 기존 React 18 / Tailwind 3 프로젝트는 먼저 의존성을 맞춰야 합니다.
버전 확인
아래 CSS 설정은 theme.css를 제공하는 0.25.2부터 적용됩니다. 0.25.1에는 이 export가 없습니다. npm에 해당 버전이 아직 없다면 아래의 로컬 패키지 설치 방법으로 검증하세요.
1. 패키지 설치
npm install @youngduck/yd-ui react@^19.1.0 react-dom@^19.1.0
npm install -D tailwindcss@^4 @tailwindcss/postcss@^4 postcss
# TypeScript 프로젝트
npm install -D @types/react@^19 @types/react-dom@^19React 버전을 올릴 때는 next-themes 등 다른 패키지의 React 19 지원도 확인하세요. --force나 --legacy-peer-deps로 충돌을 숨기기보다 호환 버전으로 맞춥니다.
2. PostCSS 설정
프로젝트 루트의 기존 PostCSS 설정을 수정합니다. 여러 설정 파일을 함께 만들지 않습니다.
// postcss.config.mjs
export default {
plugins: {
'@tailwindcss/postcss': {},
},
}CommonJS인 postcss.config.js에서는 같은 객체를 module.exports = { ... }로 내보냅니다. Tailwind 3의 tailwindcss 플러그인, tailwindcss/nesting, postcss-import는 이 설정으로 교체합니다. v4는 import와 vendor prefix 처리를 포함합니다.
3. 전역 CSS와 루트 레이아웃
/* src/app/globals.css */
@import 'tailwindcss';
@import '@youngduck/yd-ui/theme.css';
@import '@youngduck/yd-ui/styles';
/* 프로젝트 스타일은 import 뒤에 작성합니다. */theme.css: Tailwind에 토큰 이름과 YD-UI 유틸리티를 등록하고 배포 JS의 클래스를 스캔합니다.styles: 실제 토큰 값과yds-*컴포넌트 CSS를 제공합니다.- 두 파일 모두 필요합니다. 컴포넌트마다 CSS를 다시 import하지 않습니다.
// src/app/layout.tsx — Server Component로 유지합니다.
import './globals.css'
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="ko">
<body>{children}</body>
</html>
)
}기존 Tailwind 설정을 유지한다면 globals.css에 CSS 파일 기준 상대 경로로 연결합니다.
@config '../../tailwind.config.ts';v4는 JS/TS 설정을 자동으로 읽지 않습니다. 기존 container 옵션, 기본 그림자·테두리 변화와 유틸리티 이름 변경은 Tailwind 업그레이드 가이드를 확인하세요. tailwind-merge를 쓴다면 v4를 지원하는 3.x로 맞춥니다.
4. Client Component에서 사용
현재 배포 번들에는 'use client' 지시문이 없습니다. YD-UI를 import하는 컴포넌트에 경계를 명시합니다. 루트 레이아웃 전체를 Client Component로 바꿀 필요는 없습니다.
// src/components/yd-ui-example.tsx
'use client'
import { useState } from 'react'
import { Button, MonthPicker } from '@youngduck/yd-ui'
export function YdUiExample() {
const [month, setMonth] = useState('2026-11')
const [count, setCount] = useState(0)
return (
<div className="flex flex-wrap items-center gap-4 bg-background-primary p-4 text-white">
<Button onClick={() => setCount(value => value + 1)}>클릭 {count}</Button>
<MonthPicker value={month} onValueChange={setMonth} />
<span aria-live="polite">선택한 월: {month}</span>
</div>
)
}// src/app/page.tsx — Server Component
import { YdUiExample } from '@/components/yd-ui-example'
export default function Page() {
return <YdUiExample />
}이벤트 함수는 Client Component 안에 둡니다. Server Component에서 onClick 같은 함수를 props로 넘기지 않습니다. 빌드된 배포 패키지를 사용하므로 이 구성에는 transpilePackages나 ssr: false가 필요하지 않습니다.
YD-UI의 기본 surface 토큰은 어두운 색입니다. next-themes의 .dark 클래스만으로 YD-UI 토큰 전체가 자동 전환되지는 않습니다. 위 예제는 데모 영역에 YD-UI 배경을 명시했습니다.
5. 배포 전 로컬 패키지로 검증
형제 폴더에 yd-ui와 Next.js 프로젝트가 있을 때:
# yd-ui 폴더에서
pnpm build
# 소비 프로젝트에 vendor 폴더를 먼저 만듭니다.
npm pack --pack-destination ../my-next-app/vendor
# my-next-app 폴더에서
npm install ./vendor/youngduck-yd-ui-0.25.2.tgz
npm run buildtarball은 빌드된 dist를 설치하므로 로컬 symlink가 별도의 React를 로드하는 문제를 피할 수 있습니다. package.json, lockfile, tarball을 함께 커밋하면 CI에서도 설치할 수 있습니다. 로컬 소스 수정은 자동 반영되지 않으므로 빌드·pack·설치를 다시 해야 합니다. 같은 버전의 파일을 덮어쓰기보다 새 버전/파일명으로 갱신하세요. npm에 정식 배포한 뒤에는 npm install @youngduck/yd-ui@버전으로 전환할 수 있습니다.
기존 Markdown 표를 YD-UI로 렌더링
react-markdown의 components에 YD-UI를 매핑하면 기존 .md의 표 문법을 그대로 사용할 수 있습니다. 글마다 JSX나 데모 태그를 추가할 필요가 없습니다.
npm install react-markdown remark-gfm'use client'
import ReactMarkdown from 'react-markdown'
import remarkGfm from 'remark-gfm'
import { Table, THead, TBody, Tr, Th, Td } from '@youngduck/yd-ui/Table'
export function MarkdownBody({ content }: { content: string }) {
return (
<ReactMarkdown
remarkPlugins={[remarkGfm]}
components={{
table: ({ node: _node, children, ...props }) => (
<div className="my-8 max-w-full overflow-x-auto">
<Table {...props} className="w-full table-auto">{children}</Table>
</div>
),
thead: ({ node: _node, children, ...props }) => <THead {...props}>{children}</THead>,
tbody: ({ node: _node, children, ...props }) => <TBody {...props}>{children}</TBody>,
tr: ({ node: _node, children, ...props }) => <Tr {...props}>{children}</Tr>,
th: ({ node: _node, children, ...props }) => (
<Th scope="col" {...props} className="min-w-[150px] whitespace-normal break-words overflow-visible text-clip">
{children}
</Th>
),
td: ({ node: _node, children, ...props }) => (
<Td {...props} className="min-w-[150px] whitespace-normal break-words overflow-visible text-clip">
{children}
</Td>
),
}}
>
{content}
</ReactMarkdown>
)
}remark-gfm이 일반 Markdown 표를 파싱합니다. 이 용도로rehype-raw나 MDX는 필요하지 않습니다.node는 Markdown 파서의 내부 데이터이므로 DOM에 전달하지 않습니다.style등 나머지 속성은 전달하여:---,:---:,---:의 셀 정렬을 유지합니다.- 글에서는 긴 내용을 읽을 수 있도록 기본 말줄임 대신 줄바꿈을 적용합니다. 색상·테두리·셀 여백은 YD-UI 토큰을 사용합니다.
- 가로 스크롤은 표 바깥 래퍼가 담당합니다. 부모가 flex/grid 아이템이라면 그 부모에도
min-w-0을 적용해 표가 페이지 전체 너비를 늘리지 않게 합니다. sortable을 지정하지 않으면 글에 작성한 행 순서가 유지됩니다.
인용문은 <blockquote> 안에 Card를 배치하고, 코드블록의 복사 버튼은 Button으로 교체하는 방식으로 확장할 수 있습니다. 제목·목록처럼 대응 컴포넌트가 없는 요소는 기존 렌더러를 유지합니다.
문제 해결
| 증상 | 확인할 설정 |
|---|---|
useState, createContext 관련 서버 렌더링 오류 | YD-UI를 import하는 파일의 첫 줄에 'use client'가 있는지 확인 |
theme.css를 찾지 못함 | 설치 버전과 package.json exports 확인. 0.25.1에는 없음 |
| 모양은 있으나 폭·정렬·폰트가 다름 | theme.css와 styles를 모두 import하고 v4 PostCSS 플러그인을 사용했는지 확인 |
Invalid hook call | npm ls react react-dom으로 중복 React 확인. 로컬 링크 대신 tarball 사용 |
| Markdown 표가 일반 텍스트로 표시됨 | remark-gfm 등록과 표 헤더 구분선 확인 |
| 모바일에서 표가 화면을 밀어냄 | 표 래퍼의 overflow-x-auto와 flex/grid 부모의 min-w-0 확인 |
