WXT

Appearance

확장 API ​

Chrome 문서 • Firefox 문서

각 브라우저는 확장 API에 접근하기 위해 서로 다른 전역 변수를 제공합니다 (Chrome은 chrome, Firefox는 browser 등을 제공).

WXT는 이를 단순화합니다. 항상 browser를 사용하세요:

ts
browser.action.onClicked.addListener(() => {
  // ...
});

이 외에는 특정 API를 사용하는 방법에 대해 Chrome과 Mozilla의 문서를 참조하세요. 일반 확장 프로그램이 할 수 있는 모든 것은 WXT에서도 가능하며, 단지 chrome 대신 browser를 사용합니다.

웹 익스텐션 폴리필 ​

v0.1.0부터 지원

기본적으로 WXT는 Mozilla의 webextension-polyfill을 사용하여 브라우저 간에 익스텐션 API를 일관되게 만듭니다.

타입에 접근하려면 wxt/browser에서 관련 네임스페이스를 임포트해야 합니다:

ts
import { Runtime } from 'wxt/browser';

function handleMessage(message: any, sender: Runtime.Sender) {
  // ...
}

폴리필 비활성화 ​

v0.19.0 이후

2024년 6월 MV3 출시와 함께 Chrome이 MV2를 공식적으로 지원 중단하면서, 폴리필은 더 이상 유용한 역할을 하지 않습니다.

다음과 같이 한 줄로 폴리필을 비활성화할 수 있습니다:

ts
// wxt.config.ts
export default defineConfig({
  extensionApi: 'chrome',
});

이 설정은 wxt/browser가 런타임에 브라우저에 따라 browser 또는 chrome 전역 변수를 그대로 내보내도록 변경합니다:

ts
export const browser: WxtBrowser =
  // @ts-expect-error
  globalThis.browser?.runtime?.id == null
    ? globalThis.chrome
    : // @ts-expect-error
      globalThis.browser;

폴리필이 비활성화된 상태에서는 타입에 접근하는 방식이 조금 다릅니다. 타입을 임포트할 필요 없이 browser 객체 자체에서 사용할 수 있습니다:

ts
function handleMessage(message: any, sender: browser.runtime.Sender) {
  // ...
}

기능 탐지 ​

매니페스트 버전과 브라우저에 따라 일부 API는 런타임에 사용할 수 없습니다. API가 사용 불가능한 경우 undefined가 됩니다.

WARNING

타입은 여기서 도움이 되지 않습니다. WXT가 제공하는 browser 타입은 모든 API가 존재한다고 가정합니다. API의 사용 가능 여부를 확인하는 것은 여러분의 책임입니다.

API가 사용 가능한지 확인하려면 기능 탐지를 사용하세요:

ts
if (browser.runtime.onSuspend != null) {
  browser.runtime.onSuspend.addListener(() => {
    // ...
  });
}

여기서 옵셔널 체이닝이 가장 유용합니다:

ts
browser.runtime.onSuspend?.addListener(() => {
  // ...
});

또는 MV2와 MV3를 모두 지원하기 위해 다른 이름의 유사한 API를 사용하려는 경우 다음과 같이 할 수 있습니다:

ts
(browser.action ?? browser.browser_action).onClicked.addListener(() => {
  //
});