vite-plugin-chrome-extension

HMR (Hot Module Replacement) state preservation is disabled by default in svelte-hmr and @sveltejs/vite-plugin-svelte due to unpredictable behavior. If you have component state that must be retained during development when files change, move that state into an external Svelte store. External stores are not replaced by HMR, allowing the state to persist.

// store.ts
// An extremely simple external store
import { writable } from 'svelte/store'
export default writable(0)

Because the plugin uses dynamic imports to support code-splitting, background script events might be lost if they trigger before modules are fully loaded. Use dynamicImportWrapper to manage this.

• wakeEvents (string[]): A list of events (e.g., 'chrome.runtime.onMessage') that the script loader will defer until all background modules have finished loading.
• eventDelay (number | boolean): A delay in milliseconds to wait after all modules have loaded before triggering wake events. Useful for asynchronous event listeners.

// Example: deferring specific events
chromeExtension({
  dynamicImportWrapper: {
    wakeEvents: ['chrome.contextMenus.onClicked'],
    eventDelay: 50,
  },
})

If a third-party module references a Chrome API that you do not want to include in your final manifest, prefix the permission with an exclamation mark (!) in your source manifest.json. The plugin will then exclude it from the output.

// source manifest.json
{
  "permissions": [
    "!alarms", // This permission will be excluded
    "storage"
  ]
}

Install the plugin as a development dependency using npm.

npm install -D vite-plugin-chrome-extension

To use the plugin, import chromeExtension from vite-plugin-chrome-extension and add it to the plugins array in your vite.config.ts.

Crucially, you must set the build.rollupOptions.input to point to your extension's manifest.json file so that the plugin can correctly process the extension structure.

// vite.config.ts
import { resolve } from "path";
import { defineConfig } from "vite";
import { chromeExtension } from "vite-plugin-chrome-extension";

export default defineConfig({
    resolve: {
        alias: {
            "@": resolve(__dirname, "src"),
        },
    },
    build: {
        rollupOptions: {
            input: "src/manifest.json"
        }
    },
    plugins: [
        chromeExtension()
    ],
})

The chromeExtension function accepts an optional configuration object. Below are the available properties:

• browserPolyfill (boolean): Adds the Mozilla promisified Browser API to your extension. If using TypeScript, install @types/firefox-webext-browser for Intellisense.
• dynamicImportWrapper (object | false): Configures how dynamic imports are handled to support ES modules and code-splitting in background/content scripts. Setting this to false disables code-splitting.
• verbose (boolean): Controls whether the "Detected permissions" message is shown. Defaults to true.
• pkg (object): Used to manually provide name, description, and version from a package.json if not running via npm scripts.
• publicKey (string): Sets the manifest.key to help stabilize the extension ID during development.

The extendManifest option in ChromeExtensionOptions provides two ways to modify your extension's manifest.json during the build process:

1. Partial Object: Provide a Partial<ChromeExtensionManifest> to merge new keys or override existing ones.
2. Transformation Function: Provide a function that receives the current manifest as an argument and returns a new, modified ChromeExtensionManifest object.

This is useful for dynamically injecting permissions, action settings, or version numbers based on environment variables or package metadata.

// Using a function to extend the manifest
extendManifest: (manifest) => ({
  ...manifest,
  permissions: [...manifest.permissions, 'storage', 'tabs'],
  host_permissions: ['https://*.google.com/*']
})

To allow external websites to access assets (like images, scripts, or styles) stored within your Chrome extension, you must define them in the web_accessible_resources object in your manifest.json. This object maps specific assets to the target domains allowed to access them.

Access Methods

1. Static Referencing: A website can access an asset by using the direct extension URL format: chrome-extension://<extension-id>/<image-path>

2. Dynamic Injection: You can inject assets into a page at runtime by using the chrome.runtime.getURL() API to resolve the correct extension URL for a specific file.

Example Configuration Logic

In this demo, assets are restricted so that:

• web-accessible-resources-1.glitch.me can only access test1.png and test2.png.
• web-accessible-resources-2.glitch.me can only access test3.png and test4.png.