Upgrade Guides

SEED 패키지(@seed-design/react, @seed-design/css 등)의 버전을 올릴 때 호환성을 확인하고 안전하게 업그레이드하는 방법을 안내합니다.

세부 변경 목록은 업그레이드하려는 목표 버전에 맞춰 확인하세요.

버저닝 정책

SEED는 2.0을 분기점으로 버저닝 정책이 다릅니다.

여기서 "하위 호환"은 코드뿐 아니라 화면에도 적용됩니다. 색상 토큰은 이름뿐 아니라 값도 major에서만 바뀝니다. 디자인 판단에 따른 색상·스타일 변경은 major에서만 일어나므로, minor·patch를 올려도 의도적으로 화면이 달라지지는 않습니다. 다만 잘못된 값을 바로잡는 조정(대비 기준 미달 등)은 patch에 포함될 수 있습니다.

호환성: react ↔ css

@seed-design/react는 @seed-design/css를 런타임 기반(클래스네임·스타일)으로 사용합니다. 두 패키지를 호환되지 않는 버전으로 섞으면 클래스네임이 어긋나 스타일이 깨질 수 있습니다.

• 2.0 이상: react가 peerDependencies로 호환되는 css 범위(^N.M.0)를 선언합니다. 선언을 그대로 신뢰하면 됩니다.
• 2.0 미만: 선언에 상한이 없거나 아예 누락된 구간이 있어, 선언만 보면 통과하지만 실제로는 스타일이 어긋나는 조합이 존재합니다.

2.0 이상

설치된 패키지의 peer 선언을 확인합니다.

cat node_modules/@seed-design/react/package.json | grep -A5 peerDependencies

^2.0.0처럼 선언된 범위 안에 설치된 css 버전이 들어가면 호환됩니다. strict SemVer를 따르므로 minor·patch 업그레이드는 안전합니다.

2.0 미만

1.x 구간은 선언만으로 판단할 수 없습니다. 어떤 조합이 실제로 맞는지는 SEED React 1 and older 문서의 패키지 간 버전 호환성 섹션에 버전별 표로 정리돼 있습니다. @seed-design/stackflow를 함께 쓴다면 알려진 비호환 조합도 그 표에서 확인하세요.

핵심 규칙만 옮기면, css는 react와 같은 마이너 라인이어야 하고 표에 적힌 하한 이상이어야 합니다. 정확한 하한과 예외는 표를 따르세요.

스니펫 호환성 확인하기

설치된 스니펫이 현재 패키지 버전과 맞는지는 compat으로 확인합니다.

npx @seed-design/cli@latest compat

호환 이슈가 있으면 종료 코드 1로 끝나므로 CI 게이트로도 쓸 수 있습니다.

버전 올리기

npx @seed-design/cli@latest compat

npx @seed-design/cli@latest docs react/updates/changelog/react/{현재버전} --raw

npm install @seed-design/react@{react목표버전} @seed-design/css@{css목표버전}

pnpm add @seed-design/react@{react목표버전} @seed-design/css@{css목표버전}

yarn add @seed-design/react@{react목표버전} @seed-design/css@{css목표버전}

bun add @seed-design/react@{react목표버전} @seed-design/css@{css목표버전}

npx @seed-design/cli@latest add ui:{component}