WXT

Appearance

Installation ​

Bootstrap a new project, start from scratch, or migrate an existing project.

Bootstrap Project ​

sh
pnpx wxt@latest init <project-name>
sh
npx wxt@latest init <project-name>

There are several starting templates available.

TypeScript
TypeScript Logo vanilla
Vue Logo vue
React Logo react
Svelte Logo svelte
Solid Logo solid

INFO

All templates default to TypeScript. Rename the file extensions to .js to use JavaScript instead.

From Scratch ​

Create a new NPM project:

sh
mkdir project-name
cd project-name
pnpm init
echo 'shamefully-hoist=true' >> .npmrc
sh
mkdir project-name
cd project-name
npm init
sh
mkdir project-name
cd project-name
yarn init

Then install wxt:

sh
pnpm add -D wxt
sh
npm i --save-dev wxt
sh
yarn add --dev wxt

Add your first entrypoint:

ts
// entrypoints/background.ts
export default defineBackground(() => {
  console.log(`Hello from ${browser.runtime.id}!`);
});

Finally, add scripts to your package.json:

json
{
  "scripts": {
    "dev": "wxt", 
    "dev:firefox": "wxt --browser firefox", 
    "build": "wxt build", 
    "build:firefox": "wxt build --browser firefox", 
    "zip": "wxt zip", 
    "zip:firefox": "wxt zip --browser firefox", 
    "postinstall": "wxt prepare"
  }
}

Migrate an Existing Project ​

Before starting the migration, it is recommended to run pnpx wxt@latest init to see what a basic project looks like. Once you have an understanding of how WXT projects are structured, you're ready to convert the project, using the initialized project as a reference.

Migrating a project to WXT comes down to a few steps:

  1. Install WXT and remove any old build tools: pnpm i -D wxt
  2. Refactoring/move your entrypoints to the entrypoints directory
  3. Moving public assets to the public directory
  4. Update the dev and build scripts to use WXT
  5. Ensure project is compatible with Vite, which is used under the hood to bundle your extension

INFO

Since projects vary greatly in setup, start a discussion on GitHub if you need help migrating your project to WXT.

Development ​

Once you've installed WXT, you can start the development server using the dev script.

sh
pnpm dev

🎉 Well done!

The dev command will build the extension for development, open the browser, and reload the different parts of the extension when you save changes.

Development Manifest

When running the dev command, WXT will make several changes to your manifest.json to improve your development experience:

  • If missing, add a background script/service worker to enable fast reloads
  • Add several permissions and host_permissions to enable HMR and fast reloads
  • Modify the CSP to allow connections with the dev server
  • Remove content_scripts and register them at runtime so they can be easily reloaded when you save a file

If you're an experienced web extension developer and think the dev manifest looks wrong, this is why. Run a production build with wxt build to see the unmodified manifest.json.

Next Steps ​

You're ready to build your web extension!