WXT

Appearance

배포 ​

WXT는 여러분의 확장 프로그램을 ZIP 파일로 압축하고, 다양한 스토어에 리뷰를 위해 제출하거나 자체 호스팅할 수 있습니다.

첫 출시하기 ​

스토어에 확장 프로그램을 처음 출시할 때는 수동으로 과정을 진행해야 합니다. WXT는 리스팅 생성에 도움을 주지 않으며, 각 스토어마다 고유한 단계와 요구사항이 있으므로 이를 숙지해야 합니다.

각 스토어에 대한 구체적인 내용은 아래 섹션을 참고하세요.

자동화 ​

WXT는 새 버전을 검토 및 출시하기 위한 자동화를 도와주는 두 가지 커맨드를 제공합니다:

  • wxt submit init: wxt submit 커맨드에 필요한 모든 비밀값과 옵션을 설정
  • wxt submit: 확장 프로그램의 새 버전을 검토 요청 (승인 후 자동 출시)

시작하려면 wxt submit init을 실행하고 안내에 따라 진행하세요. 완료되면 .env.submit 파일이 생성됩니다. WXT는 이 파일을 사용해 업데이트를 제출합니다.

CI 환경에서는 제출 단계에 모든 환경 변수를 추가해야 합니다.

새 버전을 출시하려면, 출시할 모든 ZIP 파일을 빌드하세요:

sh
wxt zip
wxt zip -b firefox

그런 다음 출시할 모든 ZIP 파일을 인자로 전달하여 wxt submit 커맨드를 실행하세요. 이 예제에서는 Chrome 웹 스토어, Edge 애드온, Firefox 애드온 스토어 등 3개의 주요 스토어에 출시합니다.

커맨드를 처음 실행하거나 출시 프로세스를 최근에 변경한 경우, --dry-run 플래그를 사용해 비밀값을 테스트하는 것이 좋습니다.

sh
wxt submit --dry-run \
  --chrome-zip .output/{your-extension}-{version}-chrome.zip \
  --firefox-zip .output/{your-extension}-{version}-firefox.zip --firefox-sources-zip .output/{your-extension}-{version}-sources.zip \
  --edge-zip .output/{your-extension}-{version}-chrome.zip

드라이 런이 성공하면 플래그를 제거하고 실제 출시를 진행하세요:

sh
wxt submit \
  --chrome-zip .output/{your-extension}-{version}-chrome.zip \
  --firefox-zip .output/{your-extension}-{version}-firefox.zip --firefox-sources-zip .output/{your-extension}-{version}-sources.zip \
  --edge-zip .output/{your-extension}-{version}-chrome.zip

WARNING

--firefox-sources-zip 옵션에 대한 자세한 내용은 Firefox 애드온 스토어 섹션을 참고하세요.

GitHub Action ​

확장 프로그램의 새 버전을 검토를 위해 제출하는 GitHub Action 예제입니다. 워크플로우에서 사용하는 모든 필수 비밀 정보를 저장소 설정에 추가했는지 확인하세요.

yml
name: Release

on:
  workflow_dispatch:

jobs:
  submit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: pnpm/action-setup@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'pnpm'

      - name: Install dependencies
        run: pnpm install

      - name: Zip extensions
        run: |
          pnpm zip
          pnpm zip:firefox

      - name: Submit to stores
        run: |
          pnpm wxt submit \
            --chrome-zip .output/*-chrome.zip \
            --firefox-zip .output/*-firefox.zip --firefox-sources-zip .output/*-sources.zip
        env:
          CHROME_EXTENSION_ID: ${{ secrets.CHROME_EXTENSION_ID }}
          CHROME_CLIENT_ID: ${{ secrets.CHROME_CLIENT_ID }}
          CHROME_CLIENT_SECRET: ${{ secrets.CHROME_CLIENT_SECRET }}
          CHROME_REFRESH_TOKEN: ${{ secrets.CHROME_REFRESH_TOKEN }}
          FIREFOX_EXTENSION_ID: ${{ secrets.FIREFOX_EXTENSION_ID }}
          FIREFOX_JWT_ISSUER: ${{ secrets.FIREFOX_JWT_ISSUER }}
          FIREFOX_JWT_SECRET: ${{ secrets.FIREFOX_JWT_SECRET }}

위의 액션은 zip과 submit 단계를 포함한 기본 워크플로우의 기반을 제공합니다. GitHub Action을 더욱 향상시키고 복잡한 시나리오를 탐구하려면, 실제 프로젝트의 다음 예제들을 참고하세요. 이 예제들은 버전 관리, 변경 로그 생성, GitHub 릴리스와 같은 고급 기능을 다양한 요구에 맞게 소개합니다:

  • aklinker1/github-better-line-counts - 컨벤셔널 커밋, 자동 버전 업데이트 및 변경 로그 생성, 수동 트리거, 테스트를 위한 옵셔널 드라이 런
  • GuiEpi/plex-skipper - package.json 버전이 변경될 때 자동으로 트리거되며, 아티팩트를 생성하고 GitHub 릴리스에 업로드합니다.

이 예제들은 명확한 통찰을 제공하며, 여러분의 워크플로우를 커스터마이징하기 위한 좋은 출발점입니다. 프로젝트 요구에 맞게 자유롭게 탐색하고 적용해 보세요.

Stores ​

Chrome Web Store ​

✅ 지원됨 • 개발자 대시보드 • 게시 문서

Chrome용 ZIP 파일을 생성하려면:

sh
wxt zip

Firefox 애드온 스토어 ​

✅ 지원됨 • 개발자 대시보드 • 출시 문서

Firefox는 소스 코드를 ZIP 파일로 업로드해야 합니다. 이를 통해 Firefox는 확장 프로그램을 다시 빌드하고 코드를 검토할 수 있습니다. 자세한 내용은 Firefox 문서에서 확인할 수 있습니다.

wxt zip -b firefox를 실행하면 WXT는 확장 프로그램과 소스 코드를 모두 압축합니다. 설정 파일, 숨김 파일, 테스트, 제외된 진입점 등 특정 파일은 자동으로 소스에서 제외됩니다. 하지만 ZIP 파일에 확장 프로그램을 다시 빌드하는 데 필요한 파일만 포함되어 있는지 수동으로 확인하는 것이 중요합니다.

압축할 파일을 커스텀하려면 설정 파일에 zip 옵션을 추가하세요.

ts
// wxt.config.ts
import { defineConfig } from 'wxt';

export default defineConfig({
  zip: {
    // ...
  },
});

Firefox 애드온 스토어에 처음 제출하거나 프로젝트 레이아웃을 업데이트한 경우, 항상 소스 ZIP 파일을 테스트하세요! 아래 명령어를 사용하면 압축 해제된 ZIP 파일 내부에서 확장 프로그램을 다시 빌드할 수 있습니다.

sh
pnpm i
pnpm zip:firefox
sh
npm i
npm run zip:firefox
sh
yarn
yarn zip:firefox
sh
bun i
bun zip:firefox

Firefox 팀이 확장 프로그램을 빌드하는 방법을 알 수 있도록 README.md 또는 SOURCE_CODE_REVIEW.md 파일에 위 명령어를 포함시키세요.

메인 프로젝트에서 wxt build -b firefox를 실행한 결과와 압축된 소스 내부에서 빌드한 결과가 정확히 동일한지 확인하세요.

WARNING

.env 파일을 사용하는 경우, 출력 디렉토리의 청크 해시에 영향을 줄 수 있습니다. wxt zip -b firefox를 실행하기 전에 .env 파일을 삭제하거나, zip.includeSources 옵션을 사용하여 소스 ZIP에 포함시키세요. .env 파일에 비밀 정보가 포함되지 않도록 주의하세요.

자세한 내용은 이슈 #377를 참고하세요.

Private Packages ​

여러분이 비공개 패키지를 사용하고 있고, Firefox 팀에 리뷰 과정에서 인증 토큰을 제공하고 싶지 않다면, zip.downloadPackages를 사용하여 비공개 패키지를 다운로드하고 zip 파일에 포함시킬 수 있습니다.

ts
// wxt.config.ts
export default defineConfig({
  zip: {
    downloadPackages: [
      '@mycompany/some-package',
      //...
    ],
  },
});

패키지 매니저에 따라, 소스 zip 파일의 package.json은 overrides 또는 resolutions 필드를 통해 다운로드된 의존성을 사용하도록 수정됩니다.

WARNING

WXT는 npm pack <package-name> 커맨드를 사용하여 패키지를 다운로드합니다. 이는 여러분의 패키지 매니저와 관계없이 .npmrc 파일을 올바르게 설정해야 함을 의미합니다. NPM과 PNPM은 모두 .npmrc 파일을 지원하지만, Yarn과 Bun은 비공개 레지스트리 인증을 위해 각자의 방식을 사용하므로 .npmrc 파일을 추가해야 합니다.

Safari ​

🚧 아직 지원되지 않음

WXT는 현재 Safari 자동 배포를 지원하지 않습니다. Safari 확장 프로그램은 네이티브 MacOS 또는 iOS 앱 래퍼가 필요하지만, WXT는 아직 이를 생성하지 않습니다. Safari에 배포하려면 다음 가이드를 따르세요:

safari-web-extension-converter CLI 도구를 실행할 때, 소스 코드 디렉토리가 아닌 .output/safari-mv2 또는 .output/safari-mv3 디렉토리를 전달하세요.

sh
pnpm wxt build -b safari
xcrun safari-web-extension-converter .output/safari-mv2

Edge 애드온 ​

✅ 지원됨 • 개발자 대시보드 • 게시 문서

Edge 전용 ZIP 파일을 따로 만들 필요가 없습니다. 이미 Chrome 웹 스토어에 게시 중이라면 Chrome용 ZIP 파일을 그대로 재사용할 수 있습니다.

하지만 Edge 전용 기능이 있다면, 다음 명령어로 별도의 ZIP 파일을 생성하세요:

sh
wxt zip -b edge