> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/contributor/contributor-ko/contributor-guides/ui-1/migration.md). # 마이그레이션 가이드 이 가이드는 UI1 (`decentraland-ui`)에서 UI2 (`decentraland-ui2`). ## 마이그레이션할 시기 마이그레이션은 다음 세 가지 정당한 이유로 시작할 수 있습니다: ### 1. 기술적 개선 다음과 같은 이유로 컴포넌트를 마이그레이션하려는 경우: * 더 나은 테마 지원 * 향상된 TypeScript 타입 * 다른 UI2 컴포넌트와의 일관성 * 성능 최적화 * 접근성 향상 ### 2. 컴포넌트 업데이트 * UI1 컴포넌트를 업데이트해야 하는 경우 * 아직 UI2에 대응하는 버전이 없습니다 * **요구 사항**: 먼저 UI2에 만든 다음 사용하세요 ### 3. 프로젝트 요구 사항 * 이 컴포넌트는 새 프로젝트 또는 기존 프로젝트에서 사용됩니다 * 적절하게 마이그레이션할 시간이 있습니다 * 프로젝트 리소스로 충분히 마이그레이션할 수 있습니다 {% hint style="warning" %} **하지 마세요** 컴포넌트를 "그냥 그런 이유로" 마이그레이션하지 마세요. 각 마이그레이션에는 명확한 비즈니스 또는 기술적 근거가 있어야 합니다. {% endhint %} *** ## 마이그레이션 프로세스 ### 1단계: 계획 마이그레이션을 시작하기 전에: 1. **의존성 식별** * 어떤 다른 컴포넌트를 사용하나요? * 현재 어떤 프로젝트에서 사용하나요? * 예정된 Breaking Change가 있나요? 2. **현재 사용 현황 검토** * 이 컴포넌트를 사용하는 프로젝트가 몇 개인가요? * 가장 자주 사용되는 props는 무엇인가요? * 알려진 이슈가 있나요? 3. **범위 정의** * 이것은 1:1 마이그레이션인가요? * 예정된 개선 사항이 있나요? * 일정은 어떻게 되나요? ### 2단계: UI2 컴포넌트 생성 다음 내용을 따르세요 [커스텀 컴포넌트](/contributor/contributor-ko/contributor-guides/ui-1/custom-components.md) UI2 후보 컴포넌트용 가이드. **요구 사항:** * styled-components에는 객체 구문을 사용하세요 * theme 값만 사용하세요(임의 값 사용 금지) * 포괄적인 Storybook 스토리를 추가하세요 * 완전한 테스트를 작성하세요 * 모든 props와 동작을 문서화하세요 **예시 구조:** ``` ui2/src/components/Button/ ├── Button.tsx ├── Button.styles.ts ├── Button.stories.tsx ├── Button.test.tsx ├── types.ts ├── index.ts └── README.md ``` ### 3단계: 호환성 유지 UI2 컴포넌트는 **반드시** UI1 버전과 동일한 props와 동작을 제공해야 합니다. #### 동일한 Props ```tsx // UI1 Button interface ButtonProps { primary?: boolean; size?: 'small' | 'medium' | 'large'; onClick?: () => void; disabled?: boolean; children: React.ReactNode; } // UI2 Button - 동일한 props를 반드시 지원해야 함 interface ButtonProps { primary?: boolean; size?: 'small' | 'medium' | 'large'; onClick?: () => void; disabled?: boolean; children: React.ReactNode; // 새 선택적 props를 추가할 수 있음 variant?: 'text' | 'outlined' | 'contained'; } ``` #### 하위 호환 변경 props를 변경하거나 추가해야 한다면: 1. **먼저**, 새 props를 UI1에 선택적으로 추가하세요 2. **그다음**, UI1 사용처가 새 props를 사용하도록 마이그레이션하세요 3. **마지막으로**, 새 API로 UI2 컴포넌트를 만드세요 ```tsx // 1단계: UI1에 선택적 prop 추가 interface ButtonProps { primary?: boolean; // 새 선택적 prop variant?: 'primary' | 'secondary'; } // 2단계: UI1 구현 업데이트 export function Button({ primary, variant = primary ? 'primary' : 'secondary' }: ButtonProps) { // 내부에서는 primary 대신 variant 사용 } // 3단계: 새 API로 UI2 생성 interface ButtonProps { // 이제 variant가 주요 prop입니다 variant?: 'primary' | 'secondary'; // 호환성을 위해 primary는 유지하고 deprecated로 표시 /** @deprecated 대신 variant를 사용하세요 */ primary?: boolean; } ``` ### 4단계: UI1 컴포넌트 폐기 예고 UI1 컴포넌트에 폐기 예고를 추가하세요: ````tsx /** * @deprecated 이 컴포넌트는 UI2로 마이그레이션되었습니다. * 대신 'decentraland-ui2'에서 가져오세요: * * ```tsx * import { Button } from 'decentraland-ui2'; * ``` * * 마이그레이션 가이드 참조: https://docs.decentraland.org/contributor-guides/web-ui-standards/migration */ export function Button(props: ButtonProps) { // ... 기존 구현 } ```` ### 5단계: 점진적 도입 즉시 마이그레이션을 강요하지 마세요. 점진적 도입을 허용하세요: 1. **배포** UI2 컴포넌트 2. **문서화** 마이그레이션 경로 3. **업데이트** 새 프로젝트가 UI2를 사용하도록 4. **마이그레이션** 기존 프로젝트를 기회가 있을 때마다 5. **계획** 향후 UI1 제거 계획(사전 고지 포함) *** ## 마이그레이션 예시 ### 예시 1: 단순 컴포넌트 기본 `Card` 컴포넌트: #### UI1 버전 ```tsx // decentraland-ui/src/components/Card/Card.tsx import React from 'react'; import './Card.css'; export interface CardProps { className?: string; children: React.ReactNode; } export function Card({ className, children }: CardProps) { return (
{children}
); } ``` #### UI2 버전 ```tsx // decentraland-ui2/src/components/Card/Card.tsx import { styled } from '@mui/material/styles'; export interface CardProps { className?: string; children: React.ReactNode; } const StyledCard = styled('div')(({ theme }) => ({ backgroundColor: theme.palette.background.paper, borderRadius: theme.shape.borderRadius, padding: theme.spacing(2), boxShadow: theme.shadows[1], [theme.breakpoints.down('sm')]: { padding: theme.spacing(1), }, })); export function Card({ className, children }: CardProps) { return ( {children} ); } ``` ### 예시 2: 변형이 있는 컴포넌트 마이그레이션하는 `Button` 변형이 있는: #### UI1 버전 ```tsx // UI1 import './Button.css'; interface ButtonProps { primary?: boolean; secondary?: boolean; size?: 'small' | 'medium' | 'large'; } export function Button({ primary, secondary, size = 'medium', ...props }: ButtonProps) { const classes = [ 'dcl-button', primary && 'primary', secondary && 'secondary', `size-${size}` ].filter(Boolean).join(' '); return