WXT

Appearance

Migrate to WXT ​

If you have problems migrating to WXT, feel free to ask for help in GitHub by starting a discussion or in Discord!

Overview ​

Always start by generating a new vanilla project and merging it into your project one file at a time.

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

In general, you'll need to:

  Install wxt
  Extend .wxt/tsconfig.json in your project's tsconfig.json
  Update/create package.json scripts to use wxt (don't forget about postinstall)
  Move entrypoints into entrypoints/ directory
  Move assets into either the assets/ or public/ directories
  Move manifest.json content into wxt.config.ts
  Convert custom import syntax to be compatible with Vite
  Add a default export to JS entrypoints (defineBackground, defineContentScript, or defineUnlistedScript)
  Use the browser global instead of chrome
  Compare final manifest.json files, making sure permissions and host permissions are unchanged

WARNING

If your extension is already live on the Chrome Web Store, use Google's update testing tool to make sure no new permissions are being requested.

Every project is different, so there's no one-solution-fits-all to migrating your project. Just make sure wxt dev runs, wxt build results in a working extension, and the list of permissions in the manifest.json hasn't changed. If all that looks good, you've finished migrating your extension!

Here's specific steps for other popular frameworks/build tools.

Plasmo ​

  1. Install wxt
  2. Move entrypoints into entrypoints/ directory
    • For JS entrypoints, merge the named exports used to configure your JS entrypoints into WXT's default export
    • For HTML entrypoints, you cannot use JSX/Vue/Svelte files directly, you need to create an HTML file and manually create and mount your app. Refer to the React, Vue, and Svelte templates as an example.
  3. Move public assets/* into the public/ directory
  4. If you use CSUI, migrate to WXT's createContentScriptUi
  5. Convert Plasmo's custom import resolutions to Vite's
  6. If importing remote code via a URL, add a url: prefix so it works with WXT
  7. Replace your Plasmo tags (--tag) with WXT build modes (--mode)
  8. Compare your output manifest.json files from before the migration to after the migration. They should have the same content. If not, tweak your entrypoints and config to get as close as possible.

vite-plugin-web-extension ​

Since you're already using Vite, it's a simple refactor.

  1. Install wxt
  2. Move and refactor your entrypoints to WXT's style (with a default export)
  3. Update package.json scripts to use wxt
  4. Add "postinstall": "wxt prepare" script
  5. Move the manifest.json into wxt.config.ts
  6. Move any custom settings from vite.config.ts into wxt.config.ts's
  7. Compare dist/manifest.json to .output/*/manifest.json, they should have the same content as before. If not, tweak your entrypoints and config to get as close as possible.