Installation

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

Bootstrap Project

pnpm

pnpm dlx wxt@latest init <project-name>

npm

npx wxt@latest init <project-name>

bun

bunx wxt@latest init <project-name>

There are several starting templates available.

TypeScript
vanilla
vue
react
svelte
solid

INFO

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

From Scratch

Create a new NPM project:

pnpm

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

npm

mkdir project-name
cd project-name
npm init

yarn

mkdir project-name
cd project-name
yarn init

bun

mkdir project-name
cd project-name
bun init

Then install wxt:

pnpm

pnpm add -D wxt

npm

npm i --save-dev wxt

yarn

yarn add --dev wxt

bun

bun add --dev wxt

Add your first entrypoint:

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

Finally, add scripts to your package.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 pnpm dlx 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.

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!

• Learn how to add entrypoints like the popup, options page, or content scripts
• Configure your entrypoints to use ESM at runtime
• Configure WXT by creating a wxt.config.ts file
• Checkout example projects to see how to perform common tasks with WXT