vite-plugin-web-extension
A vite plugin for generating cross browser platform, ES module based web extensions.
Features
- Manifest V2 & V3 Support
- Completely ES module based extensions
- Including content scripts!
- Vite based html and static asset handling
- Including content scripts!
- HMR support for all manifest properties
- Including content scripts!
- HMR support for CSS styles in content scripts
- Including shadow DOM rendered content!
Usage
Quick Start
Build an example extension that uses this plugin:
With npm
npx degit https://github.com/samrum/vite-vue-web-extension vue-web-extension
cd vue-web-extension
npm install
npm run build
npm run serve:chrome
With pnpm
pnpm dlx degit https://github.com/samrum/vite-vue-web-extension vue-web-extension
cd vue-web-extension
pnpm install
pnpm build
pnpm serve:chrome
Vite Config
- All manifest file names should be relative to the root of the project.
Manifest V2
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
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",
},
},
}),
],
});
Content Scripts
-
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 { addStyleTarget } = await import("/@vite/client"); addStyleTarget(shadowRoot); } -
For builds, use the
import.meta.CURRENT_CONTENT_SCRIPT_CSS_URLconstant to reference the first generated CSS file associated with the current content script chunk.
Browser Support
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.
How it works
The plugin will take the provided manifest, parse rollup input scripts from all 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.
Why this is a Vite specific plugin
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.
Development
This project uses pnpm for package management.
Lint
pnpm lint
Tests
pnpm test
Build
pnpm build
8.7k Jan 4, 2023
10 Aug 2, 2022
8.4k Jan 6, 2023
765 Dec 30, 2022
17 Nov 22, 2022
44 Nov 24, 2022
395 Jan 2, 2023
34 Dec 27, 2022
8 Dec 25, 2022
14 Dec 24, 2022
49 Nov 26, 2022
29 Oct 13, 2022
49 Dec 22, 2022
137 Dec 17, 2022
580 Jan 7, 2023
54 Nov 12, 2022
28 Dec 22, 2022
17 Aug 18, 2022