web-extend

web-extend is a useful tool set for creating a project, and generating entry files, etc.

CLI

Usage:

npx web-extend [options] [command]

# or
npm add -D web-extend
npx we [options] [command]

we is a shortened form for web-extend. They are equal in function, but the we command only can be used after the web-extend tool installed.

web-extend init

The init command is used to create a project.

Usage:

npx web-extend@latest init [options] [dir]

Options:

Options:
  -t, --template <name>  specify the template name
  -e, --entry <name...>  specify entrypoints
  -h, --help             display help for command

web-extend generate

The generate command is used to generate entry files.

Usage:

npx web-extend generate|g [options] [entry...]

Options:

Options:
  -r, --root <dir>       specify the project root directory
  -t, --template <name>  specify the template name or path
  --size <size...>       specify sizes of output icons
  -h, --help             display help for command

web-extend dev

The dev command uses Rsbuild to build and run the extension in the development environment.

Usage:

npx web-extend dev [options]

Options:

Options:
  -r, --root <root>      specify the project root directory
  -m, --mode <mode>      specify the build mode, can be `development`, `production` or `none`
  --env-mode <mode>      specify the env mode to load the `.env.[mode]` file
  --env-dir <dir>        specify the directory to load `.env` files
  -t, --target <target>  specify the extension target
  --open [url]           open the extension in browser on startup
  --port <port>          specify a port number for server to listen
  -h, --help             display help for command

web-extend build

The dev command uses Rsbuild to build the extension in the production environment.

Usage:

npx web-extend build [options]

Options:

Options:
  -r, --root <root>      specify the project root directory
  -m, --mode <mode>      specify the build mode, can be `development`, `production` or `none`
  --env-mode <mode>      specify the env mode to load the `.env.[mode]` file
  --env-dir <dir>        specify the directory to load `.env` files
  -t, --target <target>  specify the extension target
  -w, --watch            watch for changes and rebuild
  -z, --zip              package the built extension
  -h, --help             display help for command

web-extend preview

The preview command is used to preview the extension for production.

Usage:

npx web-extend preview [options] [dir]

Options:

Options:
  -r, --root <root>      specify the project root directory
  -t, --target <target>  specify the extension target
  -h, --help             display help for command

web-extend zip

The zip command is used to package the extension for production.

Usage:

npx web-extend zip [options] [dir]

Options:

Options:
  -r, --root <root>          specify the project root directory
  -n, --filename <filename>  specify the output filename
  -t, --target <target>      specify the extension target
  -h, --help                 display help for command

Functions

defineConfig

defineConfig function help you to customize WebExtend's configuration options.

Options:

• manifest: Customize manifest configuration which defaults to {}. WebExtend will merge the manifest option and the fields parsed from entry files (the previous is prior), and generate manifest.json automatically.
• target: Customize browser target which suppports the following targets. -chrome-mv3 (default)
  • firefox-mv2 (recommended for Firefox)
  • firefox-mv3 (experimental, doesn't work in dev mode)
  • safari-mv3
  • edge-mv3
  • opera-mv3
• srcDir: Customize source directory which defaults to the ./src directory, falling back to the project root path if ./src doesn't exists.
• outDir: Customize dist path which defaults to the dist directory.
• publicDir: Customize public path which defaults to the public directory.
• webExt: web-ext configuration.
• rsbuild: Rsbuild configuration.

Usage:

web-extend.config.js

import { defineConfig } from 'web-extend';

export default defineConfig({
  srcDir: "src",
  outDir: "dist",
  manifest: {...},
  target: "firefox-mv2",
});

defineWebExtConfig

defineWebExtConfig function helps you to customize web-ext's configuration options.

Usage:

web-ext.config.js

import { defineWebExtConfig } from "web-extend";

export default defineWebExtConfig({
  run: {
    // ...
  },
});

Source: runner.ts.

Types

ContentScriptConfig

ContentScriptConfig is a TypeScript type that helps you define content script's config.

Type:

export interface ContentScriptConfig {
  matches: string[];
  exclude_matches?: string[];
  css?: string[];
  run_at?: "document_start" | "document_end" | "document_idle";
  all_frames?: boolean;
  match_about_blank?: boolean;
  include_globs?: string[];
  exclude_globs?: string[];
  world?: "ISOLATED" | "MAIN";
}

Usage:

src/content/index.ts

import type { ContentScriptConfig } from "web-extend";

export const config: ContentScriptConfig = {
  matches: ["https://www.google.com/*"],
};