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
  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
  Use the browser global instead of chrome
  Compare final manifest.json files, making sure permissions and host permissions are unchanged
  Extension output by wxt build works the same way as before the migration

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.

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.

plasmo ​

  1. Install wxt
  2. Move entrypoints into entrypoints/ directory, merging the named exports used to configure your JS entrypoints into WXT's default export
  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. 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.