# Migrating Icons URL: /react/migration/migrating-icons Source: https://github.com/daangn/seed-design/blob/dev/docs/content/react/migration/migrating-icons.mdx 구형 아이콘을 신규 아이콘으로 쉽게 마이그레이션해요. ## 업그레이드 방법 현재 아이콘을 사용하고 있는 방법에 따라 적용할 수 있는 2가지 방법이 있어요. ### Codemod 스크립트 아래 3개 아이콘 패키지를 사용하고 있다면, 제공되는 codemod 스크립트를 사용해서 리뉴얼된 아이콘 패키지로 손쉽게 업그레이드할 수 있어요. - [`@seed-deesign/react-icon`](https://www.npmjs.com/package/@seed-design/react-icon) - [`@seed-design/icon`](https://www.npmjs.com/package/@seed-design/icon) (deprecated) - [`@karrotmarket/karrot-ui-icon`](https://www.npmjs.com/package/@karrotmarket/karrot-ui-icon) (deprecated) (React 컴포넌트를 사용하는 경우) 3개 패키지에서 사용하고 있는 아이콘은 [`@karrotmarket/react-monochrome-icon`](https://github.com/daangn/seed-icon-v3/pkgs/npm/react-monochrome-icon)의 아이콘으로 대체돼요. ### 수동 업그레이드 다음과 같은 경우에는 수동으로 업그레이드해야 해요. - PNG, SVG 등의 파일로 기존 아이콘을 사용하는 경우 - [`@karrotmarket/karrot-ui-icon`](https://www.npmjs.com/package/@karrotmarket/karrot-ui-icon) (deprecated)에서 제공되는 SVG 파일을 사용하는 경우 - 다음 패키지를 사용하는 경우 - [`@seed-design/vue2-icon`](https://www.npmjs.com/package/@seed-design/vue2-icon) → [`@daangn/vue2-monochrome-icon`](https://github.com/daangn/seed-icon-v3/pkgs/npm/vue2-monochrome-icon)으로 대체돼요. - [`@seed-design/vue3-icon`](https://www.npmjs.com/package/@seed-design/vue3-icon) → [`@daangn/vue3-monochrome-icon`](https://github.com/daangn/seed-icon-v3/pkgs/npm/vue3-monochrome-icon)으로 대체돼요. ## 작업 순서 많은 변경사항이 발생하게 되므로, 커밋하지 않은 변경사항이 없는지 확인하고 시작하는 것이 좋아요. ### Codemod 스크립트 #### 리뉴얼된 아이콘 패키지 설치 - npm: npm install @karrotmarket/react-monochrome-icon @karrotmarket/react-multicolor-icon - pnpm: pnpm add @karrotmarket/react-monochrome-icon @karrotmarket/react-multicolor-icon - yarn: yarn add @karrotmarket/react-monochrome-icon @karrotmarket/react-multicolor-icon - bun: bun add @karrotmarket/react-monochrome-icon @karrotmarket/react-multicolor-icon 2개 패키지 중 필요한 패키지만 설치해요. - [`@karrotmarket/react-monochrome-icon`](https://github.com/daangn/seed-icon-v3/pkgs/npm/react-monochrome-icon) - 단색 아이콘 패키지에요. 일반 아이콘, 카테고리 아이콘, 서비스 아이콘이 포함되어 있어요. - 이 패키지에서 제공되는 서비스 아이콘은 검은색으로만 사용할 수 있어요. - codemod 실행 시, 기존 패키지들의 아이콘은 모두 이 패키지의 아이콘으로 대체돼요. - [`@karrotmarket/react-multicolor-icon`](https://github.com/daangn/seed-icon-v3/pkgs/npm/react-multicolor-icon) - 멀티컬러 아이콘 패키지에요. 카테고리 아이콘과 서비스 아이콘이 포함되어 있어요. - 이 패키지에서 제공되는 카테고리 아이콘과 서비스 아이콘은 패키지에서 제공되는 색상 그대로만 사용할 수 있어요. - 기존에 SVG로 사용하던 멀티컬러 아이콘들을 이 패키지로 직접 대체할 수 있어요. 따라서, 필요한 경우에만 설치해도 좋아요. #### Codemod 스크립트 실행 `replace-react-icon` transform을 실행해요. ```shell npx @seed-design/codemod@latest replace-react-icon ``` 해당 transform에 대해 자세히 알아봅니다. #### 결과 확인 문제 없이 모든 변환이 완료된 경우 다음과 같은 결과가 표시돼요. ``` 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](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-3.html#import-attributes)과 같은, deprecated된 문법이 있는 경우 - `package`와 같은 예약어를 변수 이름으로 사용한 경우 등 #### 코드 포맷 프로젝트에서 사용하는 포매터를 사용해서 코드를 포맷해요. #### 이전 패키지 제거 이전 아이콘이 모두 대체된 것을 확인하고, 이전 패키지를 제거해요. - npm: npm uninstall @seed-design/icon @seed-design/react-icon @karrotmarket/karrot-ui-icon - pnpm: pnpm remove @seed-design/icon @seed-design/react-icon @karrotmarket/karrot-ui-icon - yarn: yarn remove @seed-design/icon @seed-design/react-icon @karrotmarket/karrot-ui-icon - bun: bun remove @seed-design/icon @seed-design/react-icon @karrotmarket/karrot-ui-icon #### 사이드 이펙트 확인 - [사이드 이펙트](#발생-가능한-사이드-이펙트)가 발생했는지 확인하여 의도한 대로 변경이 이루어졌는지 검토해요. - 디자인 QA 과정에서, 자동으로 변경된 아이콘이 아닌 새로운 아이콘을 사용하도록 결정되었을 수 있어요. 이러한 경우, Figma 디자인 파일을 참고하여 코드에 반영해요. - 멀티컬러 아이콘 사용이 필요한 곳에는 [멀티컬러 아이콘 패키지](https://github.com/daangn/seed-icon-v3/pkgs/npm/react-multicolor-icon)를 사용해주세요. ### 수동 업그레이드 #### 이전 패키지 제거 이전 아이콘 패키지들을 제거해요. - npm: npm uninstall @seed-design/icon @seed-design/react-icon @karrotmarket/karrot-ui-icon @seed-design/vue2-icon @seed-design/vue3-icon - pnpm: pnpm remove @seed-design/icon @seed-design/react-icon @karrotmarket/karrot-ui-icon @seed-design/vue2-icon @seed-design/vue3-icon - yarn: yarn remove @seed-design/icon @seed-design/react-icon @karrotmarket/karrot-ui-icon @seed-design/vue2-icon @seed-design/vue3-icon - bun: bun remove @seed-design/icon @seed-design/react-icon @karrotmarket/karrot-ui-icon @seed-design/vue2-icon @seed-design/vue3-icon #### 리뉴얼된 패키지 설치 ##### React - npm: npm install @karrotmarket/react-monochrome-icon @karrotmarket/react-multicolor-icon - pnpm: pnpm add @karrotmarket/react-monochrome-icon @karrotmarket/react-multicolor-icon - yarn: yarn add @karrotmarket/react-monochrome-icon @karrotmarket/react-multicolor-icon - bun: bun add @karrotmarket/react-monochrome-icon @karrotmarket/react-multicolor-icon ##### Vue 2 - npm: npm install @daangn/vue2-monochrome-icon @daangn/vue2-multicolor-icon - pnpm: pnpm add @daangn/vue2-monochrome-icon @daangn/vue2-multicolor-icon - yarn: yarn add @daangn/vue2-monochrome-icon @daangn/vue2-multicolor-icon - bun: bun add @daangn/vue2-monochrome-icon @daangn/vue2-multicolor-icon ##### Vue 3 - npm: npm install @daangn/vue3-monochrome-icon @daangn/vue3-multicolor-icon - pnpm: pnpm add @daangn/vue3-monochrome-icon @daangn/vue3-multicolor-icon - yarn: yarn add @daangn/vue3-monochrome-icon @daangn/vue3-multicolor-icon - bun: bun add @daangn/vue3-monochrome-icon @daangn/vue3-multicolor-icon 2개 패키지 중 필요한 패키지만 설치해요. - `@daangn/*-monochrome-icon` - 단색 아이콘 패키지에요. 일반 아이콘, 카테고리 아이콘, 서비스 아이콘이 포함되어 있어요. - 이 패키지에서 제공되는 서비스 아이콘은 검은색으로만 사용할 수 있어요. - codemod 실행 시, 기존 패키지들의 아이콘은 모두 이 패키지의 아이콘으로 대체돼요. - `@daangn/*-multicolor-icon` - 멀티컬러 아이콘 패키지에요. 카테고리 아이콘과 서비스 아이콘이 포함되어 있어요. - 이 패키지에서 제공되는 카테고리 아이콘과 서비스 아이콘은 패키지에서 제공되는 색상 그대로만 사용할 수 있어요. - 기존에 SVG로 사용하던 멀티컬러 아이콘들을 이 패키지로 직접 대체할 수 있어요. 따라서, 필요한 경우에만 설치해도 좋아요. #### 아이콘 이름 변경 [아이콘 마이그레이션 레퍼런스](/docs/migration/migration-reference#iconography) 문서를 참고하여 리뉴얼된 패키지를 사용하도록 코드를 수정해요. - 기존 아이콘의 `IconHome*`은 신규 아이콘에서 `IconHouse*`로 이름이 바뀌었어요. - 기존 아이콘의 `IconHouse*`는 신규 아이콘에서 `IconWindow4House*`로 이름이 바뀌었어요. 따라서, 수동 마이그레이션 시 `IconHome*`이 `IconWindow4House*`로 잘못 변경되지 않게 주의해야 해요. **`IconHouse*`를 먼저 마이그레이션**하고, `IconHome*`을 마이그레이션하는 것을 추천해요. #### 사이드 이펙트 확인 - [사이드 이펙트](#발생-가능한-사이드-이펙트)가 발생했는지 확인하여 의도한 대로 변경이 이루어졌는지 검토해요. - 디자인 QA 과정에서, [아이콘 마이그레이션 레퍼런스](/docs/migration/migration-reference#iconography)에 따른 아이콘이 아닌 새로운 아이콘을 사용하도록 결정되었을 수 있어요. 이러한 경우, Figma 디자인 파일을 참고하여 코드에 반영해요. - 멀티컬러 아이콘 사용이 필요한 곳에는 [멀티컬러 아이콘 패키지](https://github.com/daangn/seed-icon-v3/pkgs/npm/react-multicolor-icon)를 사용해주세요. ## 발생 가능한 사이드 이펙트 ### 정확히 대응되는 리뉴얼된 아이콘이 없는 경우 - 이전 아이콘 중 아래 5개 아이콘(총 15개 variant)은 리뉴얼된 아이콘 패키지에 시각적으로 정확히 대응되는 항목이 없어요. - codemod 스크립트 실행 시 추천되는 아이콘으로 변환되지만, 시각적인 차이가 크기 때문에 변경 후 확인이 필요해요. | 이전 아이콘 이름 | 리뉴얼된 아이콘 이름 | | --------- | ----------- | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | - 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: 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`](/foundations/iconography/library?icon=icon_arrow_right_line)으로 대체돼요. - 이전 아이콘의 `Fill` variant는 리뉴얼된 아이콘에서도 `Fill` variant로 대체돼요. - 여러 개의 이전 아이콘이 하나의 리뉴얼된 아이콘으로 대체되는 경우도 있어요. - 예를 들면, `IconHeadphoneRegular`, `IconHelpcenterRegular`, `IconHelperRegular`는 모두 [`IconHeadsetLine`](/foundations/iconography/library?icon=icon_headset_line)으로 대체돼요.