Skip to content


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

Bootstrap Project

pnpm dlx wxt@latest init <project-name>
npx wxt@latest init <project-name>
bunx wxt@latest init <project-name>

There are several starting templates available.

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


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

From Scratch

Create a new NPM project:

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

Then install wxt:

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

Add your first entrypoint:

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

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


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


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!