Skip to content

WXT로 마이그레이션하기

WXT로 마이그레이션하는 데 문제가 있다면, GitHub에서 토론을 시작하거나 Discord에서 도움을 요청하세요!

개요

항상 새로운 바닐라 프로젝트를 생성하고, 파일 하나씩 프로젝트에 병합하는 방식으로 시작하세요.

sh
cd path/to/your/project
pnpm dlx wxt@latest init example-wxt --template vanilla

일반적으로 다음과 같은 작업이 필요합니다:

wxt 설치
프로젝트의 tsconfig.json에서 .wxt/tsconfig.json 확장
package.json 스크립트를 wxt를 사용하도록 업데이트/생성 (postinstall도 잊지 마세요)
엔트리포인트를 entrypoints/ 디렉토리로 이동
에셋을 assets/ 또는 public/ 디렉토리로 이동
manifest.json 내용을 wxt.config.ts로 이동
Vite와 호환되도록 커스텀 import 문법 변환
JS 엔트리포인트에 기본 내보내기 추가 (defineBackground, defineContentScript, 또는 defineUnlistedScript)
chrome 대신 browser 전역 변수 사용
최종 manifest.json 파일 비교하여 권한과 호스트 권한이 변경되지 않았는지 확인

WARNING

확장 프로그램이 이미 Chrome 웹 스토어에 출시된 경우, Google의 업데이트 테스트 도구를 사용하여 새로운 권한이 요청되지 않는지 확인하세요.

모든 프로젝트가 다르기 때문에, 프로젝트를 마이그레이션하는 데 한 가지 해결책이 통용되지는 않습니다. wxt dev가 실행되고, wxt build가 작동하는 확장 프로그램을 생성하며, manifest.json의 권한 목록이 변경되지 않았는지 확인하세요. 모든 것이 정상적으로 보인다면, 확장 프로그램 마이그레이션을 완료한 것입니다!

인기 있는 도구/프레임워크

다음은 다른 인기 있는 프레임워크/빌드 도구를 위한 구체적인 단계입니다.

Plasmo

  1. wxt 설치
  2. 엔트리포인트를 entrypoints/ 디렉토리로 이동
    • JS 엔트리포인트의 경우, JS 엔트리포인트를 구성하는 데 사용된 named exports를 WXT의 기본 export로 병합
    • HTML 엔트리포인트의 경우, JSX/Vue/Svelte 파일을 직접 사용할 수 없으므로 HTML 파일을 생성하고 앱을 수동으로 생성 및 마운트해야 함. React, Vue, Svelte 템플릿을 참고
  3. 공용 assets/*public/ 디렉토리로 이동
  4. CSUI를 사용하는 경우, WXT의 createContentScriptUi로 마이그레이션
  5. Plasmo의 커스텀 import 해결 방식을 Vite의 방식으로 변환
  6. URL을 통해 원격 코드를 import하는 경우, WXT와 호환되도록 url: 접두사를 추가
  7. Plasmo 태그 (--tag)를 WXT 빌드 모드 (--mode)로 교체
  8. 마이그레이션 전후의 manifest.json 파일을 비교. 내용이 동일해야 함. 그렇지 않은 경우, 엔트리포인트와 설정을 조정하여 최대한 비슷하게 맞춤

vite-plugin-web-extension

여러분이 이미 Vite를 사용하고 있다면, 간단히 리팩토링할 수 있습니다.

  1. wxt 설치
  2. 엔트리포인트를 WXT 스타일로 이동 및 리팩토링 (기본 내보내기 사용)
  3. package.json 스크립트를 wxt 사용하도록 업데이트
  4. "postinstall": "wxt prepare" 스크립트 추가
  5. manifest.jsonwxt.config.ts로 이동
  6. vite.config.ts의 커스텀 설정을 wxt.config.ts로 이동
  7. dist/manifest.json.output/*/manifest.json을 비교하여 이전과 동일한 내용인지 확인. 다르다면 엔트리포인트와 설정을 조정하여 최대한 비슷하게 맞춤