WXT

Appearance

Upgrading WXT ​

개요 ​

WXT를 최신 버전으로 업그레이드하려면... 그냥 설치하면 됩니다!

sh
pnpm i wxt@latest

아래는 WXT의 새 버전으로 업그레이드할 때 반드시 확인해야 하는 주요 변경 사항들입니다.

현재 WXT는 프리릴리스 상태입니다. 이는 두 번째 자릿수인 v0.X의 변경이 주요 변경으로 간주되고, 호환성이 깨지는 변경이 있을 수 있음을 의미합니다. v1이 출시되면, 메이저 버전 업그레이드에서만 호환성이 깨지는 변경이 발생할 것입니다.

v0.18.5 → v0.19.0 ​

vite-node 엔트리포인트 로더 ​

기본 엔트리포인트 로더가 vite-node로 변경되었습니다. webextension-polyfill에 의존하는 NPM 패키지를 사용하는 경우, 이를 Vite의 ssr.noExternal 옵션에 추가해야 합니다:

ts
export default defineConfig({
  vite: () => ({ 
    ssr: { 
      noExternal: ['@webext-core/messaging', '@webext-core/proxy-service'], 
    }, 
  }), 
});

자세한 내용은 전체 문서를 참고하세요.

이 변경 사항은 다음과 같은 기능을 가능하게 합니다:

엔트리포인트 옵션에서 변수를 가져와 사용할 수 있습니다:

ts
// entrypoints/content.ts
import { GOOGLE_MATCHES } from '~/utils/constants'

export default defineContentScript({
  matches: [GOOGLE_MATCHES],
  main: () => ...,
})

import.meta.glob과 같은 Vite 특정 API를 사용하여 엔트리포인트 옵션을 정의할 수 있습니다:

ts
// entrypoints/content.ts
const providers: Record<string, any> = import.meta.glob('../providers/*', {
  eager: true,
});

export default defineContentScript({
  matches: Object.values(providers).flatMap(
    (provider) => provider.default.paths,
  ),
  async main() {
    console.log('Hello content.');
  },
});

기본적으로, 이제 엔트리포인트의 main 함수 외부에서도 import와 작업을 수행할 수 있습니다. 이전에는 불가능했던 기능입니다. 하지만 여전히 주의가 필요합니다. 빌드 속도를 빠르게 유지하기 위해 main 함수 외부에서 코드를 실행하는 것은 피하는 것이 좋습니다.

이전 방식을 계속 사용하려면 wxt.config.ts 파일에 다음을 추가하세요:

ts
export default defineConfig({
  entrypointLoader: 'jiti', 
});

WARNING

entrypointLoader: "jiti"는 더 이상 사용되지 않으며 다음 주요 버전에서 제거될 예정입니다.

CJS 지원 중단 ​

WXT는 더 이상 Common JS(CJS)를 지원하지 않습니다. CJS를 사용 중이라면 다음 단계를 따라 마이그레이션하세요:

  1. package.json에 "type": "module"을 추가하세요.
  2. CJS 문법을 사용하는 .js 파일의 확장자를 .cjs로 변경하거나, ESM 문법으로 업데이트하세요.

Vite에서도 ESM으로 마이그레이션하는 방법을 제공하고 있습니다. 자세한 내용은 다음 링크를 참고하세요: https://vitejs.dev/guide/migration#deprecate-cjs-node-api

v0.18.0 → v0.18.5 ​

이 버전이 출시되었을 때는 주요 변경 사항으로 간주되지 않았지만, 그렇게 여겨졌어야 했습니다.

새로운 modules/ 디렉토리 ​

WXT는 이제 modules/ 디렉토리를 WXT 모듈을 포함하는 폴더로 인식합니다.

이미 <srcDir>/modules 또는 <srcDir>/Modules 디렉토리가 존재한다면, wxt prepare 및 다른 명령어들이 실패할 수 있습니다.

두 가지 선택지가 있습니다:

  1. [권장] 파일을 현재 위치에 유지하고 WXT가 다른 폴더를 찾도록 설정:
    ts
    // wxt.config.ts
export default defineConfig({
  modulesDir: 'wxt-modules', // 기본값은 "modules"
});
  2. modules 디렉토리를 다른 이름으로 변경.

v0.17.0 → v0.18.0 ​

MV3 host_permissions를 MV2 permissions로 자동 변환 ​

주의를 기울여, 이 변경 사항은 권한 생성 방식이 다르기 때문에 주요 변경 사항으로 표시되었습니다.

wxt.config.ts의 매니페스트에 host_permissions를 나열하고 확장 프로그램을 출시한 경우, .output/*/manifest.json 파일에서 타겟 브라우저의 permissions와 host_permissions가 변경되지 않았는지 다시 확인하세요. 권한 변경은 확장 프로그램이 업데이트 시 비활성화되거나 사용자 수가 감소할 수 있으므로, 이전 매니페스트 버전과의 차이점을 꼼꼼히 확인해야 합니다.

v0.16.0 → v0.17.0 ​

Storage - defineItem에 defaultValue 옵션이 필요합니다 ​

버전 관리를 사용하면서 기본값이 없는 defineItem을 사용했다면, defaultValue: null을 옵션에 추가하고 첫 번째 타입 매개변수를 업데이트해야 합니다:

ts
const item = storage.defineItem<number>("local:count", { 
const item = storage.defineItem<number | null>("local:count", { 
defaultValue: null, 
  version: ...,
  migrations: ...,
})

두 번째 옵션 인자를 전달할 경우, 이제 defaultValue 속성이 필수입니다.

두 번째 옵션 인자를 생략하면, 이전과 마찬가지로 기본적으로 nullable로 설정됩니다.

ts
const item: WxtStorageItem<number | null> =
  storage.defineItem<number>('local:count');
const value: number | null = await item.getValue();

Storage - watch 콜백의 타입 수정 ​

TypeScript를 사용하지 않는다면, 이 변경은 호환성을 깨뜨리지 않습니다. 단순히 타입 변경일 뿐입니다.

ts
const item = storage.defineItem<number>('local:count', { defaultValue: 0 });
item.watch((newValue: number | null, oldValue: number | null) => { 
item.watch((newValue: number, oldValue: number) => { 
  // ...
});

v0.15.0 → v0.16.0 ​

출력 디렉토리 구조 변경 ​

출력 디렉토리의 JS 진입점(entrypoint)이 이동되었습니다. 빌드 후 작업에서 파일을 참조하는 경우가 아니라면, 아무런 변경이 필요하지 않습니다.

.output/
  <target>/
    chunks/
      some-shared-chunk-<hash>.js
      popup-<hash>.js
    popup.html
    popup.html
    popup.js

v0.14.0 → v0.15.0 ​

zip.ignoredSources를 zip.excludeSources로 변경 ​

ts
// wxt.config.ts
export default defineConfig({
  zip: {
    ignoredSources: [
      /*...*/
    ], 
    excludeSources: [
      /*...*/
    ], 
  },
});

문서화되지 않은 상수 이름 변경 ​

런타임에서 빌드 설정을 감지하기 위해 사용되던 문서화되지 않은 상수들의 이름이 #380에서 변경되었습니다. 이제 이 내용은 https://wxt.dev/guide/multiple-browsers.html#runtime에 문서화되어 있습니다.

  • __BROWSER__ → import.meta.env.BROWSER
  • __COMMAND__ → import.meta.env.COMMAND
  • __MANIFEST_VERSION__ → import.meta.env.MANIFEST_VERSION
  • __IS_CHROME__ → import.meta.env.CHROME
  • __IS_FIREFOX__ → import.meta.env.FIREFOX
  • __IS_SAFARI__ → import.meta.env.SAFARI
  • __IS_EDGE__ → import.meta.env.EDGE
  • __IS_OPERA__ → import.meta.env.OPERA

v0.13.0 → v0.14.0 ​

콘텐츠 스크립트 UI API 변경 사항 ​

createContentScriptUi와 createContentScriptIframe, 그리고 이들의 일부 옵션 이름이 변경되었습니다:

  • createContentScriptUi({ ... }) → createShadowRootUi({ ... })
  • createContentScriptIframe({ ... }) → createIframeUi({ ... })
  • type: "inline" | "overlay" | "modal"은 position: "inline" | "overlay" | "modal"로 변경되었습니다.
  • onRemove는 이제 UI가 DOM에서 제거되기 **전**에 호출됩니다. 이전에는 UI가 제거된 후에 호출되었습니다.
  • mount 옵션은 관련 옵션인 onRemove와 더 잘 맞추기 위해 onMount로 이름이 변경되었습니다.

v0.12.0 → v0.13.0 ​

새로운 wxt/storage API ​

wxt/storage는 더 이상 unstorage에 의존하지 않습니다. prefixStorage와 같은 일부 unstorage API는 제거되었고, snapshot과 같은 다른 API는 새로운 storage 객체의 메서드로 변경되었습니다. 대부분의 표준 사용법은 동일하게 유지됩니다. 자세한 내용은 https://wxt.dev/guide/storage와 https://wxt.dev/api/reference/wxt/storage/를 참고하세요 (#300)

v0.11.0 → v0.12.0 ​

API 내보내기 변경 사항 ​

defineContentScript와 defineBackground가 이제 wxt/client 대신 wxt/sandbox에서 내보내집니다. (#284)

  • 자동 임포트를 사용 중이라면 변경할 필요가 없습니다.
  • 자동 임포트를 비활성화했다면, 수동으로 임포트 문을 업데이트해야 합니다:
    ts
    import { defineBackground, defineContentScript } from 'wxt/client'; 
import { defineBackground, defineContentScript } from 'wxt/sandbox';

v0.10.0 → v0.11.0 ​

Vite 5 ​

여러분은 Vite 5를 지원하는 버전으로 다른 Vite 플러그인들을 업데이트해야 합니다.

v0.9.0 → v0.10.0 ​

확장 프로그램 아이콘 탐색 ​

WXT는 이제 .png 파일 외의 아이콘을 탐색하지 않습니다. 이전에 .jpg, .jpeg, .bmp, .svg 파일을 사용했다면, 아이콘을 .png 파일로 변환하거나 wxt.config.ts 파일 내 매니페스트에 수동으로 추가해야 합니다.

v0.8.0 → v0.9.0 ​

기본적으로 WebWorker 타입 제거 ​

.wxt/tsconfig.json에서 "WebWorker" 타입을 제거했습니다. 이 타입은 서비스 워커를 사용하는 MV3 프로젝트에 유용합니다.

프로젝트에 이 타입을 다시 추가하려면, 프로젝트의 TSConfig에 다음을 추가하세요:

json
{
  "extends": "./.wxt/tsconfig.json",
  "compilerOptions": {

    "lib": ["ESNext", "DOM", "WebWorker"] 
  } 
}

v0.7.0 → v0.8.0 ​

defineUnlistedScript ​

이제 비공개 스크립트는 export default defineUnlistedScript(...)를 사용해야 합니다.

BackgroundDefinition 타입 ​

BackgroundScriptDefinition을 BackgroundDefinition으로 이름을 변경합니다.

v0.6.0 → v0.7.0 ​

콘텐츠 스크립트 CSS 출력 위치 변경 ​

이전에는 콘텐츠 스크립트 CSS가 assets/<name>.css로 출력되었지만, 이제는 문서와 일치하도록 content-scripts/<name>.css로 변경되었습니다.

v0.5.0 → v0.6.0 ​

vite 설정에 함수가 필요합니다 ​

이제 vite 설정 옵션은 반드시 함수여야 합니다. 이전에 객체를 사용했다면, vite: { ... }에서 vite: () => ({ ... })로 변경해야 합니다.

v0.4.0 → v0.5.0 ​

공용 디렉터리 위치 되돌리기 ​

기본 publicDir를 <rootDir>/public에서 <srcDir>/public으로 변경합니다.

v0.3.0 → v0.4.0 ​

기본 경로 별칭 업데이트 ​

.wxt/tsconfig.json 파일 내부에서 상대 경로 별칭을 사용하세요.

v0.2.0 → v0.3.0 ​

Public 디렉토리 이동 ​

기본 publicDir를 <srcDir>/public에서 <rootDir>/public으로 변경합니다.

타입 안전성 개선 ​

browser.runtime.getURL에 타입 안전성을 추가합니다.

v0.1.0 → v0.2.0 ​

defineBackground로 이름 변경 ​

defineBackgroundScript를 defineBackground로 이름을 변경합니다.