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!
- In Manifest V2:
- HMR support for all manifest properties
- Including content scripts when using a Chromium browser!
- HMR support for CSS styles in content scripts
- Including shadow DOM rendered content!
- HMR support for all manifest properties
Create a new Vite web extension project
npm init @samrum/vite-plugin-web-extension@latestSupports choice of Manifest version, TypeScript support, and framework (Vanilla, Vue, React, Preact, Svelte).
Check the README of the generated extension for usage information.
Requires Vite 3+
npm install @samrum/vite-plugin-web-extensionManifest V2
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"],
},
},
}),
],
});Manifest V3
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",
},
},
}),
],
});Firefox Experimental Manifest V3
There are two configurations an extension needs to make for experimental manifest V3 support:-
Background service workers are not supported, so you are required to use a background script.
-
The
use_dynamic_urlproperty is not supported for web accessible resources. In the plugin options, setuseDynamicUrlContentScriptsto false:webExtension({ ... useDynamicUrlContentScripts: false, }),
Devtools
To add content to the browser dev tools, add `devtools_page` to your manifestdevtools_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>manifest
- The manifest definition for your extension
- All manifest property file names should be relative to the root of the project.
useDynamicUrlContentScripts: boolean (optional)
- Adds the
use_dynamic_urlproperty to web accessible resources generated by the plugin - Default:
true
webAccessibleScripts: rollup filter (optional)
- A filter that will be applied to
web_accessible_resourcesentries in the provided manifest. When the filter matches a resource, it will be parsed by the plugin and treated as a content script. This can be useful to generate content scripts that will be manually injected at runtime. - Default:
{ include: /\.([cem]?js|ts)$/, exclude: "", }
-
For HMR style support within shadow DOMs, use the
addStyleTargetfunction to add the shadowRoot of your element as a style target:if (import.meta.hot) { const { addViteStyleTarget } = await import( "@samrum/vite-plugin-web-extension/client" ); await addViteStyleTarget(appContainer); }
-
For builds, use the
import.meta.PLUGIN_WEB_EXT_CHUNK_CSS_PATHSvariable to reference an array of CSS asset paths associated with the current output chunk.
In an env.d.ts file, add the following type reference to define the plugin specific import.meta variables as well as plugin client functions:
/// <reference types="@samrum/vite-plugin-web-extension/client" />The following requirements must be met by the browser:
- Must support dynamic module imports made by web extension content scripts.
- Must support
import.meta.url
A sample of supported browsers:
| Manifest V2 | Manifest V3 | |
|---|---|---|
| Chromium | 64 | 91 |
| Firefox | 89 | N/A (In development) |
The plugin will automatically default vite's build.target config option to these minimum browser versions if not already defined by the user.
The plugin will take the provided manifest, generate rollup input scripts for supported manifest properties, then output an ES module based web extension.
This includes:
- Generating and using a dynamic import wrapper script in place of original content scripts. Then, moving the original scripts to
web_accessible_resourcesso they are accessible by the wrapper script. Needed because content scripts are not able to be loaded directly as ES modules.- This may expose your extension to fingerprinting by other extensions or websites. Manifest V3 supports a
use_dynamic_urlproperty that will mitigate this. This option is set for manifest V3 web accessible resources generated by this plugin.
- This may expose your extension to fingerprinting by other extensions or websites. Manifest V3 supports a
- Modifying Vite's static asset handling to maintain
import.meta.urlusages instead of rewriting toself.location. Needed so content script static asset handling can function correctly. - Modifying Vite's HMR client to add support for targeting specific elements as style injection locations. Needed to support HMR styles in shadow DOM rendered content.
The plugin relies on Vite to parse and handle html files in addition to relying on Vite's manifest generation in order to map generated files to the eventual extension manifest.
This project uses pnpm for package management.
pnpm lintpnpm testpnpm build