Skip to Content
ResourcesMigration Guide

Migration Guide

기존 프로젝트를 Vortex 디자인 시스템으로 마이그레이션하는 가이드입니다.

개요

이 가이드는 다음과 같은 마이그레이션 시나리오를 다룹니다:

  1. 레거시 React 프로젝트 → Vortex
  2. Material-UI 프로젝트 → Vortex
  3. Ant Design 프로젝트 → Vortex
  4. Bootstrap 프로젝트 → Vortex
  5. 순수 CSS 프로젝트 → Vortex

마이그레이션 전 체크리스트

✅ 준비 사항

  • 현재 프로젝트 의존성 목록 작성
  • 사용 중인 UI 컴포넌트 인벤토리
  • 커스텀 스타일 및 테마 파악
  • 테스트 커버리지 확인
  • Git 백업 브랜치 생성

📊 호환성 체크

# Node.js 버전 확인 (v20+ 필요)
node --version
 
# React 버전 확인 (v19+ 권장)
npm list react
 
# TypeScript 버전 확인 (v5+ 권장)
npx tsc --version

1. 레거시 React 프로젝트 마이그레이션

1단계: Vortex 설치

# Vortex UI 설치
pnpm add @vortex/ui
 
# Tailwind CSS 설치 (필수)
pnpm add -D tailwindcss postcss autoprefixer
npx tailwindcss init -p
 
# Vortex CLI 설치 (선택)
pnpm add -D @vortex/cli

2단계: Tailwind 설정

// tailwind.config.js
module.exports = {
  content: [
    "./src/**/*.{js,jsx,ts,tsx}",
    "./node_modules/@vortex/ui/dist/**/*.js",
  ],
  theme: {
    extend: {
      colors: {
        primary: {
          DEFAULT: "#0066cc",
          50: "#e6f2ff",
          // ... 나머지 색상
        },
      },
    },
  },
  plugins: [],
};
/* src/index.css */
@tailwind base;
@tailwind components;
@tailwind utilities;
 
/* Vortex 스타일 import */
@import "@vortex/ui/styles";

3단계: 컴포넌트 교체

Before (레거시)

// Old custom button
<button className="btn btn-primary" onClick={handleClick}>
  클릭
</button>

After (Vortex)

import { Button } from "@vortex/ui";
 
<Button variant="primary" onClick={handleClick}>
  클릭
</Button>;

4단계: 점진적 마이그레이션

// 1. 새로운 컴포넌트부터 Vortex 사용
export function NewFeature() {
  return <Button>Vortex 사용</Button>;
}
 
// 2. 기존 컴포넌트는 점진적으로 교체
export function LegacyFeature() {
  return <button className="old-button">기존 스타일</button>;
}

2. Material-UI에서 마이그레이션

컴포넌트 매핑표

Material-UIVortex참고사항
<Button><Button>variant prop 동일
<TextField><Input>API 유사
<Card><Card>구조 동일
<Select><Select>options prop 변경
<Checkbox><Checkbox>API 동일

예시: Button 마이그레이션

Before (Material-UI)

import Button from "@mui/material/Button";
 
<Button variant="contained" color="primary" onClick={handleClick}>
  클릭
</Button>;

After (Vortex)

import { Button } from "@vortex/ui";
 
<Button variant="primary" onClick={handleClick}>
  클릭
</Button>;

테마 마이그레이션

Before (MUI Theme)

import { createTheme, ThemeProvider } from '@mui/material/styles'
 
const theme = createTheme({
  palette: {
    primary: {
      main: '#0066cc',
    },
  },
})
 
<ThemeProvider theme={theme}>
  <App />
</ThemeProvider>

After (Vortex Theme)

// tailwind.config.js에서 테마 설정
module.exports = {
  theme: {
    extend: {
      colors: {
        primary: '#0066cc',
      },
    },
  },
}
 
// CSS 변수로 테마 관리
:root {
  --color-primary: #0066cc;
}

3. Ant Design에서 마이그레이션

컴포넌트 매핑표

Ant DesignVortex참고사항
<Button type="primary"><Button variant="primary">prop 이름 변경
<Input><Input>API 유사
<Card><Card>구조 동일
<Select><Select>options 형식 변경
<Checkbox><Checkbox>API 동일

Form 마이그레이션

Before (Ant Design Form)

import { Form, Input, Button } from "antd";
 
<Form onFinish={handleSubmit}>
  <Form.Item name="email" rules={[{ required: true }]}>
    <Input placeholder="이메일" />
  </Form.Item>
  <Form.Item>
    <Button type="primary" htmlType="submit">
      제출
    </Button>
  </Form.Item>
</Form>;

After (Vortex + React Hook Form)

import { useForm } from 'react-hook-form'
import { Input, Button } from '@vortex/ui'
 
const { register, handleSubmit } = useForm()
 
<form onSubmit={handleSubmit(onSubmit)}>
  <Input
    {...register('email', { required: true })}
    placeholder="이메일"
  />
  <Button type="submit">제출</Button>
</form>

4. Bootstrap에서 마이그레이션

클래스 매핑표

BootstrapVortex/Tailwind참고사항
.btn-primary<Button variant="primary">컴포넌트 사용
.form-control<Input>컴포넌트 사용
.card<Card>컴포넌트 사용
.container.containerTailwind 동일
.row.flexFlexbox 사용
.col-*.gridGrid 사용

레이아웃 마이그레이션

Before (Bootstrap)

<div class="container">
  <div class="row">
    <div class="col-md-6">왼쪽</div>
    <div class="col-md-6">오른쪽</div>
  </div>
</div>

After (Tailwind)

<div className="container mx-auto px-4">
  <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
    <div>왼쪽</div>
    <div>오른쪽</div>
  </div>
</div>

5. 순수 CSS에서 마이그레이션

1단계: CSS를 Tailwind로 변환

Before (CSS)

.button {
  padding: 0.5rem 1rem;
  background-color: #0066cc;
  color: white;
  border-radius: 0.25rem;
  border: none;
  cursor: pointer;
}
 
.button:hover {
  background-color: #0052a3;
}

After (Tailwind)

<button className="px-4 py-2 bg-blue-600 text-white rounded border-0 cursor-pointer hover:bg-blue-700">
  클릭
</button>

2단계: Vortex 컴포넌트로 교체

import { Button } from "@vortex/ui";
 
<Button variant="primary">클릭</Button>;

공통 마이그레이션 패턴

패턴 1: 커스텀 훅 래핑

기존 로직을 유지하면서 Vortex 컴포넌트 사용:

// hooks/useOldButton.ts (기존)
export function useOldButton(onClick: () => void) {
  const [loading, setLoading] = useState(false);
 
  const handleClick = async () => {
    setLoading(true);
    await onClick();
    setLoading(false);
  };
 
  return { loading, handleClick };
}
 
// VortexButton.tsx (새로운 래퍼)
import { Button } from "@vortex/ui";
import { useOldButton } from "./hooks/useOldButton";
 
export function VortexButton({ onClick, children }: Props) {
  const { loading, handleClick } = useOldButton(onClick);
 
  return (
    <Button onClick={handleClick} disabled={loading}>
      {loading ? "로딩 중..." : children}
    </Button>
  );
}

패턴 2: 점진적 스타일 교체

// 1단계: 기존 스타일과 병행
<div className="old-container container mx-auto">
  컨텐츠
</div>
 
// 2단계: 기존 스타일 제거
<div className="container mx-auto">
  컨텐츠
</div>

패턴 3: 컴포넌트 별칭

호환성을 위한 별칭 제공:

// components/compat.ts
export { Button as MuiButton } from "@vortex/ui";
export { Input as AntInput } from "@vortex/ui";
 
// 기존 코드 수정 최소화
import { MuiButton } from "./components/compat";

마이그레이션 체크리스트

Phase 1: 준비 (1-2일)

  • 현재 프로젝트 분석
  • Vortex 설치 및 설정
  • Tailwind CSS 설정
  • 테스트 환경 구축

Phase 2: 기반 작업 (3-5일)

  • 디자인 토큰 마이그레이션
  • 레이아웃 컴포넌트 교체
  • 공통 유틸리티 함수 이전
  • 테마 시스템 구축

Phase 3: 컴포넌트 교체 (1-2주)

  • Button 교체
  • Input 교체
  • Card 교체
  • Select 교체
  • Form 컴포넌트 교체
  • 나머지 컴포넌트 교체

Phase 4: 테스트 및 최적화 (3-5일)

  • 단위 테스트 업데이트
  • E2E 테스트 실행
  • 스타일 검증
  • 접근성 테스트
  • 성능 최적화

Phase 5: 정리 (1-2일)

  • 미사용 의존성 제거
  • 레거시 코드 정리
  • 문서 업데이트
  • 코드 리뷰

문제 해결

스타일 충돌

/* Vortex 스타일 우선순위를 높임 */
@layer vortex {
  @import "@vortex/ui/styles";
}

TypeScript 타입 오류

// vortex-ui.d.ts 생성
declare module "@vortex/ui" {
  export const Button: React.FC<ButtonProps>;
  // ...
}

번들 크기 증가

// vite.config.ts - Tree shaking 설정
export default {
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          vendor: ["@vortex/ui"],
        },
      },
    },
  },
};

지원

마이그레이션 중 문제가 발생하면:

추가 리소스

Last updated on
FAQSupport