Vite Plugin Web Extension

4.5.1 verified Mon Apr 27 auth: no javascript

Vite plugin (v4.5.1) for building web extensions with Vite, supporting all major browsers. It automatically builds inputs from manifest.json, enables HMR in dev mode, validates manifests, and integrates with frontend frameworks like React, Vue, or Svelte. Published weekly with active maintenance. Differentiators: zero-config manifest-based setup, built-in dev server launching and extension reloading, and comprehensive TypeScript types.

Common errors

error Error: The 'webExtendConfig' function is used as a plugin but is not a valid Vite plugin. ↓

cause Incorrect usage of webExtendConfig as a plugin instead of importing webExtension.

fix

Use import webExtension from 'vite-plugin-web-extension' as the plugin.

error TypeError: Cannot read properties of undefined (reading 'plugins') ↓

cause Missing or misconfigured manifest.json in the project root.

fix

Ensure manifest.json exists at the project root or provide the 'manifest' option.

error Module '"vite-plugin-web-extension"' does not export a named export 'plugin'. ↓

cause Named import 'plugin' does not exist; the default export is used.

fix

Use 'import webExtension from 'vite-plugin-web-extension''.

Warnings

deprecated 'firefox' option is deprecated. Use 'webExtConfig' instead. ↓

fix Replace 'firefox: { ... }' with 'webExtConfig: { firefox: ... }'.

gotcha manifest must be valid JSON or the build will fail silently. ↓

fix Run a JSON linter on manifest.json before building.

breaking Vite 4 support removed; requires Vite 5+. ↓

fix Upgrade Vite to version 5 or later.

gotcha Content scripts must be listed in manifest.json to be processed. ↓

fix Ensure content_scripts are defined in manifest.json, not just as separate entry points.

Install

npm install vite-plugin-web-extension

yarn add vite-plugin-web-extension

pnpm add vite-plugin-web-extension

Imports

webExtension

wrong

import { webExtension } from 'vite-plugin-web-extension'

correct

import webExtension from 'vite-plugin-web-extension'

Default export, not named.

WebExtConfig

wrong

import { WebExtConfig } from 'vite-plugin-web-extension'

correct

import type { WebExtConfig } from 'vite-plugin-web-extension'

Type only import v4.1+.

webExtendConfig

import { webExtendConfig } from 'vite-plugin-web-extension'

Named export for extending manifest config.

defineConfig

wrong

import { defineConfig } from 'vite-plugin-web-extension'

correct

import { defineConfig } from 'vite'

defineConfig is from Vite, not this plugin.

Quickstart

Basic setup with TypeScript, specifying manifest path and browser target.

// vite.config.ts
import { defineConfig } from 'vite';
import webExtension from 'vite-plugin-web-extension';

export default defineConfig({
  plugins: [
    webExtension({
      // optional: specify manifest path, defaults to 'manifest.json'
      manifest: 'src/manifest.json',
      // optional: web-ext options, e.g., browser, firefox
      webExtConfig: {
        browser: 'chromium',
      },
    }),
  ],
});