로고SEED Design

Codemod

SEED V2 아이콘을 V3 아이콘으로 변환하는 Codemod

업그레이드 방법

현재 아이콘을 사용하고 있는 방법에 따라 적용할 수 있는 2가지 방법이 있어요.

Codemod 스크립트

아래 3개 아이콘 패키지를 사용하고 있다면, 제공되는 codemod 스크립트를 사용해서 리뉴얼된 아이콘 패키지로 손쉽게 업그레이드할 수 있어요.

3개 패키지에서 사용하고 있는 아이콘은 @karrotmarket/react-monochrome-icon의 아이콘으로 대체돼요.

수동 업그레이드

다음과 같은 경우에는 수동으로 업그레이드해야 해요.

작업 순서

시작하기 전

많은 변경사항이 발생하게 되므로, 커밋하지 않은 변경사항이 없는지 확인하고 시작하는 것이 좋아요.

Codemod 스크립트

리뉴얼된 아이콘 패키지 설치

npm install @karrotmarket/react-monochrome-icon @karrotmarket/react-multicolor-icon
pnpm add @karrotmarket/react-monochrome-icon @karrotmarket/react-multicolor-icon
yarn add @karrotmarket/react-monochrome-icon @karrotmarket/react-multicolor-icon
bun add @karrotmarket/react-monochrome-icon @karrotmarket/react-multicolor-icon

패키지 설명

2개 패키지 중 필요한 패키지만 설치해요.

  • @karrotmarket/react-monochrome-icon
    • 단색 아이콘 패키지에요. 일반 아이콘, 카테고리 아이콘, 서비스 아이콘이 포함되어 있어요.
    • 이 패키지에서 제공되는 서비스 아이콘은 검은색으로만 사용할 수 있어요.
    • codemod 실행 시, 기존 패키지들의 아이콘은 모두 이 패키지의 아이콘으로 대체돼요.
  • @karrotmarket/react-multicolor-icon
    • 멀티컬러 아이콘 패키지에요. 카테고리 아이콘과 서비스 아이콘이 포함되어 있어요.
    • 이 패키지에서 제공되는 카테고리 아이콘과 서비스 아이콘은 패키지에서 제공되는 색상 그대로만 사용할 수 있어요.
    • 기존에 SVG로 사용하던 멀티컬러 아이콘들을 이 패키지로 직접 대체할 수 있어요. 따라서, 필요한 경우에만 설치해도 좋아요.

Codemod 스크립트 실행

경로 내의 코드를 일괄적으로 변환하는 codemod 스크립트를 실행해요.

npx @seed-design/codemod@latest transform-name <...경로> <옵션>
npx @seed-design/codemod@latest transform-name src

Node.js 요구사항

스크립트 실행을 위해서는 Node.js 20.16.0 이상의 버전이 필요해요. 버전 요구사항을 만족시키지 않으면 안내 문구가 표시돼요.

nvm을 사용한다면 codemod 실행을 위해 Node.js 버전을 잠시 변경할 수 있어요.

nvm install 20.16

옵션

  • --log
    • 로그를 파일로 저장해요.
    • ./에 migrate-icons-combined.log와 migrate-icons-warnings.log 파일이 생성돼요.
  • --extensions
    • 변환할 파일 확장자를 지정해요.
    • 이 옵션을 지정하지 않으면 경로 안의 js, jsx, ts, tsx 파일을 변환해요. (d.ts 제외)
    • 예시: --extensions="ts,tsx"
  • --ignore-config
    • 변환하지 않을 경로들을 glob 패턴으로 작성한 파일을 지정해요.
    • 예시: --ignore-config=".gitignore"
    • 이 옵션을 지정하지 않아도 jscodeshift에 의해 **/node_modules/**는 자동으로 무시돼요.

결과 확인

문제 없이 모든 변환이 완료된 경우 다음과 같은 결과가 표시돼요.

All done.
Results:
0 errors // [!code highlight]
439 unmodified
1 skipped
27 ok
Time elapsed: 43.376seconds

결과별 설명

  • errors: 파싱 오류 등으로 인해, 아이콘을 참조하는 코드가 있는지 확인하지 못한 파일의 수에요.
    • 에러가 발생한 파일에 이전 아이콘을 참조하는 코드가 없다면, 해당 파일에서 발생하는 에러는 무시해도 좋아요.
    • 이전 아이콘을 참조하는 코드가 있다면, 문제가 발생한 부분을 수정하고 다시 스크립트를 실행하거나, 해당 파일의 아이콘 마이그레이션을 직접 진행해주세요.
  • unmodified: 아이콘을 참조하는 코드가 없어, 아무 변환도 이루어지지 않은 파일의 수에요.
  • skipped: 빈 파일 등 변환 대상이 아니어서, 아무 변환도 이루어지지 않은 파일의 수에요.
  • ok: 변환이 이루어진 파일의 수에요.

파싱 오류

ERR /Users/seed/foo/bar.js Transformation error (Unexpected reserved word 'package'. (3:3))

codemod 스크립트 실행 중 파싱 오류가 발생할 수 있어요. 파싱 오류는 다음과 같은 이유로 발생해요.

  • assert를 사용한 import assertion과 같은, deprecated된 문법이 있는 경우
  • package와 같은 예약어를 변수 이름으로 사용한 경우 등

코드 포맷

프로젝트에서 사용하는 포매터를 사용해서 코드를 포맷해요.

이전 패키지 제거

이전 아이콘이 모두 대체된 것을 확인하고, 이전 패키지를 제거해요.

npm uninstall @seed-design/icon @seed-design/react-icon @karrotmarket/karrot-ui-icon
pnpm remove @seed-design/icon @seed-design/react-icon @karrotmarket/karrot-ui-icon
yarn remove @seed-design/icon @seed-design/react-icon @karrotmarket/karrot-ui-icon
bun remove @seed-design/icon @seed-design/react-icon @karrotmarket/karrot-ui-icon

사이드 이펙트 확인

  • 사이드 이펙트가 발생했는지 확인하여 의도한 대로 변경이 이루어졌는지 검토해요.
  • 디자인 QA 과정에서, 자동으로 변경된 아이콘이 아닌 새로운 아이콘을 사용하도록 결정되었을 수 있어요. 이러한 경우, Figma 디자인 파일을 참고하여 코드에 반영해요.
  • 멀티컬러 아이콘 사용이 필요한 곳에는 멀티컬러 아이콘 패키지를 사용해주세요.

수동 업그레이드

이전 패키지 제거

이전 아이콘 패키지들을 제거해요.

npm uninstall @seed-design/icon @seed-design/react-icon @karrotmarket/karrot-ui-icon @seed-design/vue2-icon @seed-design/vue3-icon
pnpm remove @seed-design/icon @seed-design/react-icon @karrotmarket/karrot-ui-icon @seed-design/vue2-icon @seed-design/vue3-icon
yarn remove @seed-design/icon @seed-design/react-icon @karrotmarket/karrot-ui-icon @seed-design/vue2-icon @seed-design/vue3-icon
bun remove @seed-design/icon @seed-design/react-icon @karrotmarket/karrot-ui-icon @seed-design/vue2-icon @seed-design/vue3-icon

리뉴얼된 패키지 설치

React
npm install @karrotmarket/react-monochrome-icon @karrotmarket/react-multicolor-icon
pnpm add @karrotmarket/react-monochrome-icon @karrotmarket/react-multicolor-icon
yarn add @karrotmarket/react-monochrome-icon @karrotmarket/react-multicolor-icon
bun add @karrotmarket/react-monochrome-icon @karrotmarket/react-multicolor-icon
Vue 2
npm install @daangn/vue2-monochrome-icon @daangn/vue2-multicolor-icon
pnpm add @daangn/vue2-monochrome-icon @daangn/vue2-multicolor-icon
yarn add @daangn/vue2-monochrome-icon @daangn/vue2-multicolor-icon
bun add @daangn/vue2-monochrome-icon @daangn/vue2-multicolor-icon
Vue 3
npm install @daangn/vue3-monochrome-icon @daangn/vue3-multicolor-icon
pnpm add @daangn/vue3-monochrome-icon @daangn/vue3-multicolor-icon
yarn add @daangn/vue3-monochrome-icon @daangn/vue3-multicolor-icon
bun add @daangn/vue3-monochrome-icon @daangn/vue3-multicolor-icon

패키지 설명

2개 패키지 중 필요한 패키지만 설치해요.

  • @daangn/*-monochrome-icon
    • 단색 아이콘 패키지에요. 일반 아이콘, 카테고리 아이콘, 서비스 아이콘이 포함되어 있어요.
    • 이 패키지에서 제공되는 서비스 아이콘은 검은색으로만 사용할 수 있어요.
    • codemod 실행 시, 기존 패키지들의 아이콘은 모두 이 패키지의 아이콘으로 대체돼요.
  • @daangn/*-multicolor-icon
    • 멀티컬러 아이콘 패키지에요. 카테고리 아이콘과 서비스 아이콘이 포함되어 있어요.
    • 이 패키지에서 제공되는 카테고리 아이콘과 서비스 아이콘은 패키지에서 제공되는 색상 그대로만 사용할 수 있어요.
    • 기존에 SVG로 사용하던 멀티컬러 아이콘들을 이 패키지로 직접 대체할 수 있어요. 따라서, 필요한 경우에만 설치해도 좋아요.

아이콘 이름 변경

V2 V3 아이콘 맵핑 문서를 참고하여 리뉴얼된 패키지를 사용하도록 코드를 수정해요.

이름 변경 관련 유의 사항

  • 기존 아이콘의 IconHome*은 신규 아이콘에서 IconHouse*로 이름이 바뀌었어요.
  • 기존 아이콘의 IconHouse*는 신규 아이콘에서 IconWindow4House*로 이름이 바뀌었어요.

따라서, 수동 마이그레이션 시 IconHome*이 IconWindow4House*로 잘못 변경되지 않게 주의해야 해요.

IconHouse*를 먼저 마이그레이션하고, IconHome*을 마이그레이션하는 것을 추천해요.

사이드 이펙트 확인

  • 사이드 이펙트가 발생했는지 확인하여 의도한 대로 변경이 이루어졌는지 검토해요.
  • 디자인 QA 과정에서, V2 V3 아이콘 맵핑에 따른 아이콘이 아닌 새로운 아이콘을 사용하도록 결정되었을 수 있어요. 이러한 경우, Figma 디자인 파일을 참고하여 코드에 반영해요.
  • 멀티컬러 아이콘 사용이 필요한 곳에는 멀티컬러 아이콘 패키지를 사용해주세요.

발생 가능한 사이드 이펙트

정확히 대응되는 리뉴얼된 아이콘이 없는 경우

  • 이전 아이콘 중 아래 5개 아이콘(총 15개 variant)은 리뉴얼된 아이콘 패키지에 시각적으로 정확히 대응되는 항목이 없어요.
  • codemod 스크립트 실행 시 추천되는 아이콘으로 변환되지만, 시각적인 차이가 크기 때문에 변경 후 확인이 필요해요.
이전 아이콘 이름리뉴얼된 아이콘 이름
IconBoldThin
IconTUppercaseSerifLine
IconBoldRegular
IconTUppercaseSerifLine
IconBoldFill
IconTUppercaseSerifFill
IconCobuyingThin
IconShoppingbag2StackedLine
IconCobuyingRegular
IconShoppingbag2StackedLine
IconCobuyingFill
IconShoppingbag2StackedFill
IconDeliveryThin
IconTruckLine
IconDeliveryRegular
IconTruckLine
IconDeliveryFill
IconTruckFill
IconSuggestThin
IconLightbulbDot5Line
IconSuggestRegular
IconLightbulbDot5Line
IconSuggestFill
IconLightbulbDot5Fill
IconWriteStoryThin
IconHorizline2VerticalChatbubbleRectangularRightLine
IconWriteStoryRegular
IconHorizline2VerticalChatbubbleRectangularRightLine
IconWriteStoryFill
IconHorizline2VerticalChatbubbleRectangularRightFill

사용 여부 확인 방법

  • codemod 스크립트 사용 시, 5개 아이콘(총 15개 variant)이 사용된 경우 터미널에 메시지가 출력돼요.
REP ...을 ...로 변경했지만, 변경된 아이콘이 적절한지 확인이 필요해요
  • codemod 스크립트를 --log flag와 함께 사용 시, 사용된 내역이 migrate-icons-warnings.log에 기록돼요.
  • 다음을 활용하여 코드를 직접 검색할 수 있어요.
(IconBold|IconCobuying|IconDelivery|IconSuggest|IconWriteStory)(Thin|Regular|Fill)|(IconTUppercaseSerif|IconShoppingbag2Stacked|IconTruck|IconLightbulbDot5|IconHorizline2VerticalChatbubbleRight)(Line|Fill)
git grep -E '(IconBold|IconCobuying|IconDelivery|IconSuggest|IconWriteStory)(Thin|Regular|Fill)|(IconTUppercaseSerif|IconShoppingbag2Stacked|IconTruck|IconLightbulbDot5|IconHorizline2VerticalChatbubbleRight)(Line|Fill)'

여러 이전 아이콘이 하나의 리뉴얼된 아이콘으로 대체되는 경우

이전 아이콘과 리뉴얼된 아이콘은 n:1로 대응돼요. 따라서, 같은 페이지에 표시되었던 서로 다른 여러 개의 아이콘이, 동일한 리뉴얼된 아이콘으로 대체되는 경우가 있어요. 의도한 목적대로 아이콘이 표시되는지 확인해요.

  • 한 이전 아이콘의 3개 variant 중 Thin variant와 Regular variant는 리뉴얼된 아이콘에서 모두 Line variant로 대체돼요.
    • 예를 들면, IconForwardThin, IconForwardRegular는 모두 IconArrowRightLine으로 대체돼요.
    • 이전 아이콘의 Fill variant는 리뉴얼된 아이콘에서도 Fill variant로 대체돼요.
  • 여러 개의 이전 아이콘이 하나의 리뉴얼된 아이콘으로 대체되는 경우도 있어요.
    • 예를 들면, IconHeadphoneRegular, IconHelpcenterRegular, IconHelperRegular는 모두 IconHeadsetLine으로 대체돼요.

Last updated on

Library

리액트 아이콘 패키지는 아이콘을 사용할 때 필요한 컴포넌트를 제공합니다.

Composition

컴포넌트를 조합하여 복잡한 UI를 구성하는 방법과 원칙을 설명합니다.

On this page

업그레이드 방법
Codemod 스크립트
수동 업그레이드
작업 순서
Codemod 스크립트
리뉴얼된 아이콘 패키지 설치
Codemod 스크립트 실행
결과 확인
코드 포맷
이전 패키지 제거
사이드 이펙트 확인
수동 업그레이드
이전 패키지 제거
리뉴얼된 패키지 설치
React
Vue 2
Vue 3
아이콘 이름 변경
사이드 이펙트 확인
발생 가능한 사이드 이펙트
정확히 대응되는 리뉴얼된 아이콘이 없는 경우
여러 이전 아이콘이 하나의 리뉴얼된 아이콘으로 대체되는 경우