CRXJS

This chaptor introduces how to migrate a CRXJS project to WebExtend. The main difference between WebExtend and CRXJS is WebExtend using Rsbuild as the bundler instead of Vite. Nevertheless, the migration process is simple and Rsbuild is really fast. Here is a migration example from-crxjs.

Installing dependencies

Install the following dependencies.

npm

npm add -D @rsbuild/core @web-extend/rsbuild-plugin web-extend web-ext

pnpm

pnpm add -D @rsbuild/core @web-extend/rsbuild-plugin web-extend web-ext

yarn

yarn add -D @rsbuild/core @web-extend/rsbuild-plugin web-extend web-ext

Updating npm scripts

Next, update scripts with the following WebExtend's CLI commands in package.json.

package.json

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

Migrate bundler

When migrating bundler from Vite to Rsbuild, the main changes are as follows.

1. Create rsbuild.config.ts in the root and import the@web-extend/rsbuild-plugin plugin.
2. Migrate plugins, see rsbuild-migrating-plugins.
3. Migrate configuration, see rsbuild-configuration-migration.

Example.

rsbuild.config.ts

import { resolve } from "node:path";
import { defineConfig } from "@rsbuild/core";
import { pluginReact } from "@rsbuild/plugin-react";
import { pluginWebExtend } from "@web-extend/rsbuild-plugin";
import manifest from "./manifest.config";

export default defineConfig({
  resolve: {
    alias: {
      "@": `${resolve(__dirname, "src")}`,
    },
  },
  plugins: [
    pluginReact(),
    pluginWebExtend({
      manifest,
    }),
  ],
});

Updating mainfest

The mainfest file in CRXJS is also supported in WebExtend. For adaption, you need to modify all *.html entry points to *.js entry points.

Example.

manifest.config.ts

import pkg from "./package.json"; 

export default {
  manifest_version: 3, // no more need
  name: pkg.name, // no more need
  version: pkg.version, // no more need
  action: {
    default_popup: "src/popup/index.html", 
    default_popup: "src/popup/main.tsx", 
  },
  content_scripts: [
    {
      js: ["src/content/main.ts"],
      matches: ["https://*/*"],
    },
  ],
};

Additionally, WebExend also supports declarative entrypoints, which parses entry files based on the file system and generates the corresponding fields for manifest.json, so you no longer need to define entrypoints manually.

Validating results

Congratulations 🎉 ! You have done the basic migration. Now you can run npm run dev or npm run build. The extension's artifact directory is dist/[target]-[mode].

If there is any omission or mistake, welcome to submit an issue or a PR from the Github page 🤝.