vitesse-webext

Vitesse-webext is an awesome WebExtension starter template. We adapted it to WebExtend. You can use it to create a new project.

npx web-extend@latest init --template with-vitesse-webext

If you want to migrate an existing vitesse-webext project, just follow the steps below.

Installing dependencies

Install the following dependencies.

npm

npm add -D web-extend @rsbuild/core
npm add -D @rsbuild/plugin-vue @unocss/postcss

pnpm

pnpm add -D web-extend @rsbuild/core
pnpm add -D @rsbuild/plugin-vue @unocss/postcss

yarn

yarn add -D web-extend @rsbuild/core
yarn add -D @rsbuild/plugin-vue @unocss/postcss

Update the versions of the following dependencies, guaranteeing they can be integrated into Rsbuild.

npm

npm add -D unocss@latest @unocss/reset@latest
npm add -D unplugin-auto-import@latest unplugin-icons@latest unplugin-vue-components@latest

pnpm

pnpm add -D unocss@latest @unocss/reset@latest
pnpm add -D unplugin-auto-import@latest unplugin-icons@latest unplugin-vue-components@latest

yarn

yarn add -D unocss@latest @unocss/reset@latest
yarn add -D unplugin-auto-import@latest unplugin-icons@latest unplugin-vue-components@latest

Updating npm scripts

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

package.json

{
  "type": "module", 
  "scripts": {
    "dev": "npm run clear && cross-env NODE_ENV=development run-p dev:*", 
    "dev-firefox": "npm run clear && cross-env NODE_ENV=development EXTENSION=firefox run-p dev:*", 
    "dev:prepare": "esno scripts/prepare.ts", 
    "dev:background": "npm run build:background -- --mode development", 
    "dev:web": "vite", 
    "dev:js": "npm run build:js -- --mode development", 
    "dev": "web-extend dev --open", 
    "dev:firefox": "web-extend dev --open --target firefox-mv2", 

    "build": "cross-env NODE_ENV=production run-s clear build:web build:prepare build:background build:js", 
    "build:prepare": "esno scripts/prepare.ts", 
    "build:background": "vite build --config vite.config.background.mts", 
    "build:web": "vite build", 
    "build:js": "vite build --config vite.config.content.mts", 
    "build": "web-extend build", 
    "build:firefox": "web-extend build --target firefox-mv2", 

    "pack": "cross-env NODE_ENV=production run-p pack:*", 
    "pack:zip": "rimraf extension.zip && jszip-cli add extension/* -o ./extension.zip", 
    "pack:crx": "crx pack extension -o ./extension.crx", 
    "pack:xpi": "cross-env WEB_EXT_ARTIFACTS_DIR=./ web-ext build --source-dir ./extension --filename extension.xpi --overwrite-dest", 
    "zip": "web-extend zip", 
    "zip:firefox": "web-extend zip --target firefox-mv2", 

    "start:chromium": "web-ext run --source-dir ./extension --target=chromium", 
    "start:firefox": "web-ext run --source-dir ./extension --target=firefox-desktop", 
    "preview": "web-extend preview", 
    "preview:firefox": "web-extend preview --target firefox-mv2", 

    "clear": "rimraf --glob extension/dist extension/manifest.json extension.*"
  }
}

Migrating bundler

WebExtend uses Rsbuild under the hood, so you need to migrate the bundler from Vite to Rsbuild. Nevertheless, the migration process is easy, and the main changes are as follows.

1. Create web-extend.config.ts for WebExtend configuration.
2. Create rsbuild.config.ts for Rsbuild configuration.
3. Add the following plugins to Rsbuild.
   • @rsbuild/plugin-vue
   • unplugin-vue-components/rspack
   • unplugin-auto-import/rspack
   • unplugin-icons/rspack
4. Migrate the following config to Rsbuild.
   • resolve.alias -> resolve.alias
   • define -> source.define
   • set html.mountId: "app". Rsbuild will inject an HTML file for each entry file, so the original HTML files in source are useless.
5. Support UnoCSS.
   • Create postcss.config.mjs, and import the @unocss/postcss plugin.
   • Adjust the content of unocss.config.ts.
   • Remove import 'uno.css' from JS files, and insert @unocss; into the corresponding CSS files.

The full list of all config are as follows.

web-extend.config.ts

import { defineConfig } from 'web-extend';
import manifest from './src/manifest';

export default defineConfig({
  manifest,
});

rsbuild.config.ts

import { defineConfig } from '@rsbuild/core';
import { pluginVue } from '@rsbuild/plugin-vue';
import Components from 'unplugin-vue-components/rspack';
import AutoImport from 'unplugin-auto-import/rspack';
import Icons from 'unplugin-icons/rspack';
import IconsResolver from 'unplugin-icons/resolver';
import { isDev, r } from './scripts/utils';
import packageJson from './package.json';
import manifest from './src/manifest';

export default defineConfig({
  plugins: [pluginVue()],
  html: {
    mountId: 'app',
  },
  resolve: {
    alias: {
      '~/': './src/',
    },
  },
  source: {
    define: {
      __DEV__: isDev,
      __NAME__: JSON.stringify(packageJson.name),
    },
  },
  tools: {
    rspack: {
      plugins: [
        AutoImport({
          imports: [
            'vue',
            {
              'webextension-polyfill': [['=', 'browser']],
            },
          ],
          dts: r('src/auto-imports.d.ts'),
        }),

        Components({
          dirs: [r('src/components')],
          // generate `components.d.ts` for ts support with Volar
          dts: r('src/components.d.ts'),
          resolvers: [
            // auto import icons
            IconsResolver({
              prefix: '',
            }),
          ],
        }),

        Icons(),
      ],
    },
  },
});

postcss.config.mjs

import UnoCSS from '@unocss/postcss';

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

unocss.config.ts

import { defineConfig } from 'unocss/vite';
import { presetAttributify, presetIcons, presetWind3 } from 'unocss';

export default defineConfig({
  content: {
    filesystem: ['src/**/*.{html,js,ts,jsx,tsx,vue,svelte,astro}', '!src/**/*.d.ts'],
  },
  presets: [presetWind3(), presetAttributify(), presetIcons()],
});

To migrate other config in the project, please refer to the following documents:

• Rsbuild Vite
• UnoCSS

Updating source code

WebExtend uses the file system to parse entry files and generates the corresponding fields for manifest.json. So you don't need to define them explicitly any more. The main changes are as follows.

• Generate icons: run npx web-extend g icons --template ./extension/assets/icon-512.png to generate icon files under the src/assets directory.
• Change popup, options and sidepanel: remove index.html and rename main.ts to index.ts respectively.
• Change content: rename the contentScripts directory to content.
• Change background: rename main.ts to index.ts, and remove import.meta.hot related content in code.
• Remove useless code about entries in manifest.ts and retain the permissions, host_permissions, etc, fields.

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 🤝.