Gathering detailed insights and metrics for @samrum/vite-plugin-web-extension
Gathering detailed insights and metrics for @samrum/vite-plugin-web-extension
A vite plugin for generating cross browser platform, ES module based web extensions.
5.1.1
349
MIT
TypeScript
142.98 kB
Installations
npm install @samrum/vite-plugin-web-extensionDeveloper Guide
BETA
Typescript
Yes
Module System
ESM
Min. Node Version
>=16.0.0
Node Version
18.20.4
NPM Version
10.7.0
Releases
26
Languages
6
TypeScript
JavaScript
HTML
CSS
Shell
SCSS
TypeScript (91.17%)
JavaScript (4.16%)
HTML (3.7%)
CSS (0.86%)
Shell (0.06%)
SCSS (0.05%)
Developer
samrum
Download Statistics
Total Downloads
0
Last Day
0
Last Week
0
Last Month
0
Last Year
0
GitHub Statistics
MIT License
349 Stars
128 Commits
30 Forks
7 Watchers
2 Branches
10 Contributors
Updated on Jul 01, 2025
Maintainers
1
Package Meta Information
Latest Version
5.1.1
Package Id
@samrum/vite-plugin-web-extension@5.1.1
Unpacked Size
142.98 kB
Size
30.18 kB
File Count
12
NPM Version
10.7.0
Node Version
18.20.4
Published on
Sep 26, 2024
Total Downloads
Cumulative downloads
Total Downloads
NaN
Last Day
0%
NaN
Compared to previous day
Last Week
0%
NaN
Compared to previous week
Last Month
0%
NaN
Compared to previous month
Last Year
0%
NaN
Compared to previous year
Weekly Downloads
Monthly Downloads
Yearly Downloads
Peer Dependencies
1
@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!
- All Manifest entry points
Quick Start
Create a new Vite web extension project
1npm 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+
1npm install @samrum/vite-plugin-web-extension
Examples
Manifest V2
vite.config.js:
1import { defineConfig } from "vite"; 2import webExtension from "@samrum/vite-plugin-web-extension"; 3 4export default defineConfig({ 5 plugins: [ 6 webExtension({ 7 manifest: { 8 name: pkg.name, 9 description: pkg.description, 10 version: pkg.version, 11 manifest_version: 2, 12 background: { 13 scripts: ["src/background/script.js"], 14 }, 15 }, 16 }), 17 ], 18});
Manifest V3
vite.config.js:
1import { defineConfig } from "vite"; 2import webExtension from "@samrum/vite-plugin-web-extension"; 3 4export default defineConfig({ 5 plugins: [ 6 webExtension({ 7 manifest: { 8 name: pkg.name, 9 description: pkg.description, 10 version: pkg.version, 11 manifest_version: 3, 12 background: { 13 service_worker: "src/background/serviceWorker.js", 14 }, 15 }, 16 }), 17 ], 18});
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, setuseDynamicUrlWebAccessibleResourcesto false:1 webExtension({ 2 ... 3 useDynamicUrlWebAccessibleResources: false, 4 }),
Devtools
To add content to the browser dev tools, add `devtools_page` to your manifest1devtools_page: "src/entries/devtools/index.html",
Place a script devtools.js in public dir.
1var _browser; 2if (chrome) { 3 _browser = chrome; 4} else { 5 _browser = browser; 6} 7_browser.devtools.panels.create( 8 "My Panel", // title 9 "images/icon-16.png", // icon 10 "src/entries/devtools/index.html" // content 11);
Then load the script from your devtools html which placed in src/entries/devtools/index.html.
1<!DOCTYPE html> 2<html lang="en"> 3 <head> 4 <meta charset="UTF-8" /> 5 <title>Devtools</title> 6 </head> 7 <body> 8 <div id="app"></div> 9 <script type="module" src="./main.ts"></script> 10 <script src="/devtools.js"></script> 11 </body> 12</html>
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_urlproperty to web accessible resources generated by the plugin- Caution: In Chrome 130, with this option enabled, importing a generated resource using
chrome.runtime.getURLwill not work (Chromium Issue)l
- Caution: In Chrome 130, with this option enabled, importing a generated resource using
optimizeWebAccessibleResources (optional)
- Type:
boolean - Default:
true - On build, in Manifest V3, merge web accessible resource definitions that have matching non-
resourceproperties and dedupe and sortresources. In Manifest V2, sort web accessible resources.
additionalInputs (optional)
-
Type:
1 type AdditionalInput = 2 | string 3 | { 4 fileName: string; 5 webAccessible?: 6 | boolean 7 | { 8 matches: string[]; 9 extensionIds?: string[]; 10 excludeEntryFile?: boolean; 11 } 12 | { 13 matches?: string[]; 14 extensionIds: string[]; 15 excludeEntryFile?: boolean; 16 }; 17 }; 18 19 additionalInputs?: { 20 scripts?: AdditionalInput[]; 21 html?: AdditionalInput[]; 22 styles?: AdditionalInput[]; 23 }; -
Additional input files that should be processed and treated as web extension inputs.
-
Useful for dynamically injected scripts or dynamically opened HTML pages.
-
The webAccessible option configures whether the input file and its dependencies are included in the manifest
web_accessible_resourcesproperty. Defaults to true.- When set to
true, defaults to:1 { 2 matches: ['<all_urls>'], 3 excludeEntryFile: false, 4 } - The
excludeEntryFileoption prevents the entry file from being added as a web accessible resource. Defaults to false.
- When set to
-
Example
1 webExtension({ 2 manifest: ..., 3 additionalInputs: { 4 scripts: [ 5 'src/entries/webAccessibleScript.js', // defaults to webAccessible: true 6 { 7 fileName: 'src/entries/webAccessibleScript2.js', 8 webAccessible: true, 9 }, 10 { 11 fileName: 'src/entries/privateScript.js', // entry file and dependencies are not web accessible 12 webAccessible: false, 13 }, 14 { 15 fileName: 'src/entries/entryFileExcluded.js', // entry file is not web accessible and dependencies are 16 webAccessible: { 17 matches: ['<all_urls>'], 18 excludeEntryFile: true, 19 }, 20 }, 21 ], 22 }, 23 })
Content Scripts
-
For HMR style support within shadow DOMs, use the
addStyleTargetfunction to add the shadowRoot of your element as a style target:1if (import.meta.hot) { 2 const { addViteStyleTarget } = await import( 3 "@samrum/vite-plugin-web-extension/client" 4 ); 5 6 await addViteStyleTarget(appContainer); 7} -
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.
TypeScript
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:
1/// <reference types="@samrum/vite-plugin-web-extension/client" />
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.
For dev mode support in Manifest V3, Chromium version must be at least 110.
How it works
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.
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
1pnpm lint
Tests
1pnpm test
Build
1pnpm build
No vulnerabilities found.
No security vulnerabilities found.