Generate cross browser platform, ES module based web extensions.
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.
Requires Vite 3+
npm install @samrum/vite-plugin-web-extension
manifest
useDynamicUrlWebAccessibleResources (optional)
boolean
true
use_dynamic_url
property to web accessible resources generated by the pluginoptimizeWebAccessibleResources (optional)
boolean
true
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[];
};
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_resources
property. Defaults to true.
true
, defaults to:
{
matches: ['<all_urls>'],
excludeEntryFile: false,
}
excludeEntryFile
option prevents the entry file from being added as a web accessible resource. Defaults to false.Example
webExtension({
manifest: ...,
additionalInputs: {
scripts: [
'src/entries/webAccessibleScript.js', // defaults to webAccessible: true
{
fileName: 'src/entries/webAccessibleScript2.js',
webAccessible: true,
},
{
fileName: 'src/entries/privateScript.js', // entry file and dependencies are not web accessible
webAccessible: false,
},
{
fileName: 'src/entries/entryFileExcluded.js', // entry file is not web accessible and dependencies are
webAccessible: {
matches: ['<all_urls>'],
excludeEntryFile: true,
},
},
],
},
})
For HMR style support within shadow DOMs, use the addStyleTarget
function 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_PATHS
variable 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:
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.
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:
web_accessible_resources
so they are accessible by the wrapper script. Needed because content scripts are not able to be loaded directly as ES modules.
use_dynamic_url
property that will mitigate this. This option is set for manifest V3 web accessible resources generated by this plugin.import.meta.url
usages instead of rewriting to self.location
. Needed so content script static asset handling can function correctly.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 lint
pnpm test
pnpm build