vite-plugin-web-extension

The plugin automatically discovers and merges configuration files. If multiple files are found, they are merged in order of priority (higher priority files override lower priority ones).

Important: Array fields are overwritten, not combined.

Configuration Priority (Highest to Lowest)

1. webExtConfig option in vite.config.ts
2. <viteRoot>/.webextrc
3. <viteRoot>/.webextrc.(json|json5|yml|yaml)
4. <cwd>/.webextrc
5. <cwd>/.webextrc.(json|json5|yml|yaml)
6. ~/.webextrc
7. ~/.webextrc.(json|json5|yml|yaml)

Using a file in your home directory (~/.webextrc) allows you to set global preferences (like specific browser binaries) for all your projects.

// ~/.webextrc
{
  "chromiumBinary": "/Applications/Google Chrome Beta.app/Contents/MacOS/Google Chrome Beta",
  "firefox": "firefoxdeveloperedition"
}

IMPORTANT

vite-plugin-web-extension is entering maintenance mode and will soon be deprecated in favor of WXT (wxt.dev).

• New Projects: It is highly recommended to use WXT instead.
• Existing Projects: Once WXT v1.0 is released, a migration guide will be provided. WXT supports all current features of this plugin and is the intended successor.

For standardizing the behavior of multiple browsers at runtime (e.g., using browser.* instead of chrome.*), use the webextension-polyfill package. Simply import it wherever you need to use extension APIs.

// Works on Chrome, Edge, Firefox, Safari... every browser
import browser from "webextension-polyfill";

browser.runtime.getURL("/popup.html");

To publish your extension to a web store, you must zip the contents of your output directory (typically dist/). You can do this manually or automate the process using a utility like zip-a-folder.

import { zip } from "zip-a-folder";

await zip("dist", "extension.zip");

When bootstrapping a project, you can choose from several templates based on your preferred language and framework:

If you prefer to maintain completely distinct manifest files for different browsers (e.g., manifest.chrome.json and manifest.firefox.json), you can use a conditional expression within the manifest option of the webExtension plugin.

import defineConfig from "vite";
import webExtension from "vite-plugin-web-extension";

const target = process.env.TARGET || "chrome";

export default defineConfig({
  plugins: [
    webExtension({
      manifest: target == "chrome" ? "manifest.chrome.json" : "manifest.firefox.json",
    }),
  ],
});

Upgrading from version 2 to version 3 primarily requires updating your project to use Vite 4.

To perform the upgrade:

1. Install the latest version of Vite using your package manager.
2. Ensure all other Vite plugins in your project are updated to versions compatible with Vite 4.

Note for v1 users: If you are migrating from version 1, you must first complete the migration steps for version 2 before proceeding to version 3.

pnpm i vite@latest

If you prefer using the SWC-based React plugin for faster builds, install @vitejs/plugin-react-swc and add it to your vite.config.ts.

// vite.config.ts
import { defineConfig } from "vite";
import webExtension from "vite-plugin-web-extension";
import react from "@vitejs/plugin-react-swc";

export default defineConfig({
  plugins: [
    react(),
    webExtension({
      // ...
    }),
  ],
});

Use the create-vite-plugin-web-extension command to bootstrap a new project using vite-plugin-web-extension. This will guide you through setting up a new extension project using available templates.

npm create vite-plugin-web-extension
pnpm create vite-plugin-web-extension
yarn create vite-plugin-web-extension

Templates are consumed by the create command by cloning the main branch of the repository. To add or fix a template, you do not need to publish to NPM; simply merge your changes into the main branch.

How templates are processed:

1. The tool clones the repo.
2. It retrieves a list of templates from templates/templates.json via the raw GitHub URL.
3. It copies the templates/shared folder into the target project folder.
4. It copies the specific templates/<template-name> folder into the project folder, overwriting any files from the shared folder.

To add a new template:

Create a new folder inside the templates/ directory named after your template and place the template files inside it. Ensure the template results in a functional extension similar to existing examples.