Quick Start

Environment Preparation

Node.js >= 16, and the Node.js LTS version is recommended.

Automatic Installation

It is recommended to use web-extend for creating a project automatically. Just run the following command on the CLI:

npx web-extend@latest init

The web-extend tool provides the following templates, which all use TypeScript. If you want to use JavaScript, please modify the file extension names.

• Vanilla
• React
• Vue
• Svelte

WebExtend is compatible with any frontend framework. For other frameworks, you might need manual installation.

Manual Installtion

Install dependencies

Create a project and install dependencies. WebExtend uses Rsbuild under the hood, which and the @web-extend/rsbuild-plugin plugin are also needed to be installed.

npm

mkdir my-extension-app
cd my-extension-app

npm init -y
npm add -D web-extend @rsbuild/core @web-extend/rsbuild-plugin

pnpm

mkdir my-extension-app
cd my-extension-app

npm init -y
pnpm add -D web-extend @rsbuild/core @web-extend/rsbuild-plugin

yarn

mkdir my-extension-app
cd my-extension-app

npm init -y
yarn add -D web-extend @rsbuild/core @web-extend/rsbuild-plugin

It is also recommended to install TypeScript、React/Vue、Eslint/Prettier/Biome etc, for enhancing the development experience (Optional).

Add scripts

Add the "type": "module" field and the following scripts into package.json.

package.json

{
  "type": "module",
  "scripts": {
    "dev": "web-extend rsbuild:dev --open",
    "build": "web-extend rsbuild:build",
    "preview": "web-extend preview",
    "zip": "web-extend zip"
  }
}

The meanings of the commands above are as follows:

• dev: use Rsbuild for developing the extension. --open is used to open a browser automatically for running it.
• build: use Rsbuild for building the extension for production.
• preview: preview the extension for production.
• zip: package the extension for production into a .zip file.

The feature of running the extension in a browser is based on web-ext. If you want to use the feature, please install it additionally.

npm

npm add -D web-ext

pnpm

pnpm add -D web-ext

yarn

yarn add -D web-ext

Add Rsbuild config

Create the rsbuild.config.ts file and add the following content.

rsbuild.config.ts

import { defineConfig } from "@rsbuild/core";
import { pluginWebExtend } from "@web-extend/rsbuild-plugin";

export default defineConfig({
  plugins: [pluginWebExtend()],
});

Add entry files

Create the src/popup.js file whose content is as follows. WebExtend will parse the entrypoint automatically based on the file system.

src/popup.js

const rootEl = document.querySelector("#root");
if (rootEl) {
  rootEl.innerHTML = `
  <div class="content">
    <h1>Vanilla WebExtend</h1>
    <p>This is a popup page.</p>
  </div>
  `;
}

Alternatively, you can use the web-extend tool to generate entry files. Run the following command.

npx web-extend generate popup

Add extra manifest.json fields if necessary, such as name, permissions, and so on (Optional).

rsbuild.config.ts

import { defineConfig } from "@rsbuild/core";
import { pluginWebExtend } from "@web-extend/rsbuild-plugin";

export default defineConfig({
  plugins: [pluginWebExtend({
    manifest: {...} 
  })],
});

Run & Build

Execute npm run dev for development, or npm run build for production.

If you prefer to run the extension manually, please remove the --open option in the dev command, enable the deveoplment mode in the browser, and then load the dist/chrome-mv3-dev or dist/chrome-mv3-prod artifact directory.

Publishing

Execute npm run zip for packaging the extension, and then publish it on browser stores. More information about publish refers to:

• Chrome Docs
• Firefox Docs
• Safari Docs
• Microsoft Docs