WXT

Appearance

Manifest ​

WXT에서는 소스 코드에 manifest.json 파일이 없습니다. 대신 WXT는 여러 소스에서 매니페스트를 생성합니다:

wxt build를 실행하면 확장 프로그램의 manifest.json 파일이 .output/{target}/manifest.json에 출력됩니다.

전역 옵션 ​

매니페스트에 속성을 추가하려면 wxt.config.ts 파일 내부의 manifest 설정을 사용하세요:

ts
export default defineConfig({
  manifest: {
    // 여기에 수동으로 변경할 내용을 추가하세요
  },
});

매니페스트를 함수로 정의하고, 대상 브라우저, 모드 등을 기반으로 JS를 사용해 생성할 수도 있습니다.

ts
export default defineConfig({
  manifest: ({ browser, manifestVersion, mode, command }) => {
    return {
      // ...
    };
  },
});

MV2와 MV3 호환성 ​

manifest에 속성을 추가할 때는 가능한 경우 MV3 형식으로 속성을 정의하세요. MV2를 대상으로 할 때, WXT는 이러한 속성을 자동으로 MV2 형식으로 변환합니다.

예를 들어, 다음 설정을 보겠습니다:

ts
export default defineConfig({
  manifest: {
    action: {
      default_title: 'Some Title',
    },
    web_accessible_resources: [
      {
        matches: ['*://*.google.com/*'],
        resources: ['icon/*.png'],
      },
    ],
  },
});

WXT는 다음과 같은 manifest를 생성합니다:

json
{
  "manifest_version": 2,
  // ...
  "browser_action": {
    "default_title": "Some Title"
  },
  "web_accessible_resources": ["icon/*.png"]
}
json
{
  "manifest_version": 3,
  // ...
  "action": {
    "default_title": "Some Title"
  },
  "web_accessible_resources": [
    {
      "matches": ["*://*.google.com/*"],
      "resources": ["icon/*.png"]
    }
  ]
}

또한 특정 manifest 버전에만 해당하는 속성을 지정할 수 있으며, 다른 manifest 버전을 대상으로 할 때는 해당 속성이 제거됩니다.

이름 ​

Chrome Docs

manifest 설정을 통해 제공되지 않으면, manifest의 name 속성은 package.json의 name 속성을 기본값으로 사용합니다.

버전과 버전 이름 ​

Chrome Docs

여러분의 확장 프로그램의 version과 version_name은 package.json의 version을 기반으로 합니다.

  • version_name은 명시된 문자열 그대로 사용됩니다.
  • version은 문자열에서 유효하지 않은 접미사를 제거한 후 정리된 값입니다.

예제:

json
// package.json
{
  "version": "1.3.0-alpha2"
}
json
// .output/<target>/manifest.json
{
  "version": "1.3.0",
  "version_name": "1.3.0-alpha2"
}

만약 package.json에 버전이 명시되어 있지 않다면, 기본값으로 "0.0.0"이 사용됩니다.

아이콘 ​

WXT는 public/ 디렉토리에 있는 파일을 확인하여 확장 프로그램의 아이콘을 자동으로 찾습니다:

public/
├─ icon-16.png
├─ icon-24.png
├─ icon-48.png
├─ icon-96.png
└─ icon-128.png

구체적으로, 아이콘은 다음 정규식 중 하나와 일치해야 발견됩니다:

ts
const iconRegex = [
  /^icon-([0-9]+)\.png$/,                 // icon-16.png
  /^icon-([0-9]+)x[0-9]+\.png$/,          // icon-16x16.png
  /^icon@([0-9]+)w\.png$/,                // icon@16w.png
  /^icon@([0-9]+)h\.png$/,                // icon@16h.png
  /^icon@([0-9]+)\.png$/,                 // icon@16.png
  /^icons?[/\\]([0-9]+)\.png$/,          // icon/16.png | icons/16.png
  /^icons?[/\\]([0-9]+)x[0-9]+\.png$/,   // icon/16x16.png | icons/16x16.png
];

이 파일명이 마음에 들지 않거나 WXT로 마이그레이션 중이고 파일 이름을 바꾸고 싶지 않다면, 매니페스트에서 icon을 수동으로 지정할 수 있습니다:

ts
export default defineConfig({
  manifest: {
    icons: {
      16: '/extension-icon-16.png',
      24: '/extension-icon-24.png',
      48: '/extension-icon-48.png',
      96: '/extension-icon-96.png',
      128: '/extension-icon-128.png',
    },
  },
});

또는 @wxt-dev/auto-icons를 사용하여 WXT가 필요한 크기로 아이콘을 생성하도록 할 수 있습니다.

권한 ​

Chrome 문서

대부분의 경우, 여러분은 매니페스트에 권한을 수동으로 추가해야 합니다. 몇 가지 특정 상황에서만 권한이 자동으로 추가됩니다:

  • 개발 중: 핫 리로딩을 활성화하기 위해 tabs와 scripting 권한이 추가됩니다.
  • sidepanel 엔트리포인트가 있을 때: sidepanel 권한이 추가됩니다.
ts
export default defineConfig({
  manifest: {
    permissions: ['storage', 'tabs'],
  },
});

호스트 권한 ​

Chrome 문서

ts
export default defineConfig({
  manifest: {
    permissions: ['storage', 'tabs'],
  },
});

WARNING

호스트 권한을 사용하고 MV2와 MV3를 모두 대상으로 하는 경우, 각 버전에 필요한 호스트 권한만 포함해야 합니다:

ts
export default defineConfig({
  manifest: ({ manifestVersion }) => ({
    host_permissions: manifestVersion === 2 ? [...] : [...],
  }),
});

기본 로케일 ​

ts
export default defineConfig({
  manifest: {
    name: '__MSG_extName__',
    description: '__MSG_extDescription__',
    default_locale: 'en',
  },
});

확장 프로그램을 국제화하는 전체 가이드는 I18n 문서를 참고하세요.

Actions ​

MV2에서는 browser_action과 page_action 두 가지 옵션이 있습니다. MV3에서는 이 두 가지가 단일 action API로 통합되었습니다.

기본적으로 action이 생성될 때, WXT는 MV2를 타겟팅할 경우 browser_action으로 대체합니다.

액션과 팝업 ​

아이콘을 클릭한 후 UI가 나타나는 매니페스트를 생성하려면 팝업 진입점을 생성하면 됩니다. MV2에서 page_action을 사용하려면 HTML 문서의 head에 다음 메타 태그를 추가하세요:

html
<meta name="manifest.type" content="page_action" />

팝업 없이 액션 사용하기 ​

activeTab 권한이나 browser.action.onClicked 이벤트를 사용하면서 팝업을 표시하지 않으려면:

  1. 팝업 엔트리포인트가 있다면 삭제
  2. 매니페스트에 action 키 추가:
    ts
    export default defineConfig({
  manifest: {
    action: {},
  },
});

팝업이 있는 액션과 마찬가지로, WXT는 MV2에서 browser_action을 대체로 사용합니다. 대신 page_action을 사용하려면 해당 키도 추가하세요:

ts
export default defineConfig({
  manifest: {
    action: {},
    page_action: {},
  },
});