@samrum/vite-plugin-web-extension weekly downloads statistics

@samrum/vite-plugin-web-extension

Generate cross browser platform, ES module based web extensions.

• Manifest V2 & V3 Support
• Completely ES module based extensions
  • Including in content scripts!
• Vite based html and static asset handling
  • Including in content scripts!
• HMR support
  • All Manifest entry points
    • Including content scripts when using a Chromium browser!
  • CSS styles in content scripts
    • Including shadow DOM rendered content!
  • Including Manifest V3 support since Chromium 110!

Quick Start

Create a new Vite web extension project

npm init @samrum/vite-plugin-web-extension@latest

Supports choice of Manifest version, TypeScript support, and framework (Preact, React, Solid, Svelte, Vanilla, Vue).

Check the README of the generated extension for usage information.

Usage

Requires Vite 3+

npm install @samrum/vite-plugin-web-extension

Examples

<details> <summary>Manifest V2</summary>

vite.config.js:

import { defineConfig } from "vite";
import webExtension from "@samrum/vite-plugin-web-extension";

export default defineConfig({
  plugins: [
    webExtension({
      manifest: {
        name: pkg.name,
        description: pkg.description,
        version: pkg.version,
        manifest_version: 2,
        background: {
          scripts: ["src/background/script.js"],
        },
      },
    }),
  ],
});

</details> <details> <summary>Manifest V3</summary>

vite.config.js:

import { defineConfig } from "vite";
import webExtension from "@samrum/vite-plugin-web-extension";

export default defineConfig({
  plugins: [
    webExtension({
      manifest: {
        name: pkg.name,
        description: pkg.description,
        version: pkg.version,
        manifest_version: 3,
        background: {
          service_worker: "src/background/serviceWorker.js",
        },
      },
    }),
  ],
});

</details> <details> <summary>Firefox Experimental Manifest V3 </summary> There are two configurations an extension needs to make for experimental manifest V3 support:

1. Background service workers are not supported, so you are required to use a background script.

2. The use_dynamic_url property is not supported for web accessible resources. In the plugin options, set useDynamicUrlWebAccessibleResources to false:

     webExtension({
       ...
       useDynamicUrlWebAccessibleResources: false,
     }),
   

</details> <details> <summary>Devtools</summary> To add content to the browser dev tools, add `devtools_page` to your manifest

devtools_page: "src/entries/devtools/index.html",

Place a script devtools.js in public dir.

var _browser;
if (chrome) {
  _browser = chrome;
} else {
  _browser = browser;
}
_browser.devtools.panels.create(
  "My Panel", // title
  "images/icon-16.png", // icon
  "src/entries/devtools/index.html" // content
);

Then load the script from your devtools html which placed in src/entries/devtools/index.html.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Devtools</title>
  </head>
  <body>
    <div id="app"></div>
    <script type="module" src="./main.ts"></script>
    <script src="/devtools.js"></script>
  </body>
</html>

</details>

Options

manifest

• The manifest definition for your extension
• All manifest property file names should be relative to the root of the project.

useDynamicUrlWebAccessibleResources (optional)

• Type: boolean
• Default: false
• Adds the use_dynamic_url property to web accessible resources generated by the plugin
  • Caution: In Chrome 130, with this option enabled, importing a generated resource using chrome.runtime.getURL will not work (Chromium Issue)l

optimizeWebAccessibleResources (optional)

• Type: boolean
• Default: true
• On build, in Manifest V3, merge web accessible resource definitions that have matching non-resource properties and dedupe and sort resources. In Manifest V2, sort web accessible resources.

additionalInputs (optional)

• Type:

    type AdditionalInput =
      | string
      | {
          fileName: string;
          webAccessible?:
            | boolean
            | {
                matches: string[];
                extensionIds?: string[];
                excludeEntryFile?: boolean;
              }
            | {
                matches?: string[];
                extensionIds: string[];
                excludeEntryFile?: boolean;
              };
        };
  
    additionalInputs?: {
      scripts?: AdditionalInput[];
      html?: AdditionalInput[];
      styles?: AdditionalInput[];
    };
  ```…