### Develop Built-in Example

Source: https://github.com/extension-js/extension.js/blob/main/docs/CONTRIBUTING.md

Run the development server against a specific built-in example extension located in the extensions directory.

```sh
pnpm extension dev ./extensions/browser-extension
```

--------------------------------

### Install extension-develop

Source: https://github.com/extension-js/extension.js/blob/main/programs/develop/README.md

Install the extension-develop package using pnpm. This is the first step to start developing Extension.js projects.

```bash
pnpm add extension-develop
```

--------------------------------

### Create a React Extension and Install Dependencies

Source: https://github.com/extension-js/extension.js/blob/main/programs/create/README.md

Scaffold a new extension project using a specific template (React) and automatically install its dependencies. Dependency installation is optional and defaults to false.

```javascript
await extensionCreate('my-react-extension', {
  template: 'react',
  install: true
})
```

--------------------------------

### Install Managed Browser Binaries

Source: https://github.com/extension-js/extension.js/blob/main/programs/extension/README.md

Use these commands to install specific browser binaries or all available ones. The `--where` flag shows the installation directory.

```bash
npx extension@latest install firefox
```

```bash
npx extension@latest install --browser=all
```

```bash
npx extension@latest install --where
```

--------------------------------

### Install Playwright Browsers

Source: https://github.com/extension-js/extension.js/blob/main/docs/CONTRIBUTING.md

If the first end-to-end test run prompts for browser installation, use this command to install the necessary browsers for Playwright.

```sh
pnpm exec playwright install
```

--------------------------------

### Usage Example

Source: https://github.com/extension-js/extension.js/blob/main/programs/develop/plugin-web-extension/feature-web-resources/README.md

Example of how to integrate the WebResourcesPlugin into your Rspack or Webpack configuration.

```APIDOC
## Usage

### Standalone (manual lists)

```ts
import * as path from 'path'
import {WebResourcesPlugin} from '@/webpack/plugin-extension/feature-web-resources'

export default {
  // ...your rspack/webpack configuration
  plugins: [
    new WebResourcesPlugin({
      manifestPath: path.resolve(__dirname, 'manifest.json'),
      includeList: {
        // Tell the plugin which content script entries to associate
        // The key is the logical entry name; the value(s) are absolute file paths
        'content_scripts:content/scripts': [
          path.resolve(__dirname, 'content/scripts.js')
        ]
      }
    })
  ]
}
```
```

--------------------------------

### Install Managed Browser Binaries

Source: https://github.com/extension-js/extension.js/blob/main/programs/extension/README.md

Download and install a managed browser binary, such as Firefox, for isolated builds using the Extension.js CLI.

```bash
extension install firefox
```

--------------------------------

### Install extension-create CLI

Source: https://github.com/extension-js/extension.js/blob/main/programs/create/README.md

Install the extension-create package using npm. This command is used to add the scaffolding tool to your project dependencies.

```bash
npm install extension-create
```

--------------------------------

### Develop Extension from Chrome Sample

Source: https://github.com/extension-js/extension.js/blob/main/programs/extension/README.md

Start developing an extension by pulling a sample from Chrome Extension Samples and running it with a specified browser.

```bash
npx extension@latest dev https://github.com/GoogleChrome/chrome-extensions-samples/tree/main/functional-samples/sample.page-redder --browser=edge
```

--------------------------------

### Create and Run a New Extension

Source: https://github.com/extension-js/extension.js/blob/main/programs/extension/README.md

Use this command to create a new extension project and start the development server. Works with npm, pnpm, yarn, and bun.

```bash
npx extension@latest create my-extension
cd my-extension
npm run dev
```

--------------------------------

### Install Dependencies

Source: https://github.com/extension-js/extension.js/blob/main/docs/CONTRIBUTING.md

Install project dependencies using PNPM, the package manager specified for this workspace.

```sh
pnpm install
```

--------------------------------

### ManifestPlugin Usage Example

Source: https://github.com/extension-js/extension.js/blob/main/programs/develop/plugin-web-extension/feature-manifest/README.md

Demonstrates how to integrate the ManifestPlugin into your Webpack configuration.

```APIDOC
## ManifestPlugin Usage

Standalone:

```ts
import * as path from 'path'
import {ManifestPlugin} from '@/webpack/plugin-extension/feature-manifest'

export default {
  // ...your (R)Webpack configuration
  plugins: [
    new ManifestPlugin({
      manifestPath: path.resolve(__dirname, 'manifest.json'),
      browser: 'chrome',
      includeList: {
        // Map of feature keys to absolute file paths (string or string[])
        // e.g. 'content_scripts/content-0': ['/abs/project/content/script.ts']
      }
    })
  ]
}
```
```

--------------------------------

### Create a Basic Extension with extensionCreate

Source: https://github.com/extension-js/extension.js/blob/main/programs/create/README.md

Use the extensionCreate function to scaffold a new extension project. This example creates a basic JavaScript extension with default settings.

```javascript
import {extensionCreate} from 'extension-create'

// Create a basic extension (default template: javascript)
await extensionCreate('my-extension', {})
```

--------------------------------

### Run Extension in Development Mode

Source: https://github.com/extension-js/extension.js/blob/main/programs/create/templates/javascript/README.md

Starts the extension in development mode. You can specify the target browser using the --browser flag.

```bash
npm run dev                 # Chromium (default)
npm run dev -- --browser=chrome
npm run dev -- --browser=edge
npm run dev -- --browser=firefox
```

--------------------------------

### ExtensionPlugin Usage

Source: https://github.com/extension-js/extension.js/blob/main/programs/develop/plugin-web-extension/README.md

Example of how to integrate the ExtensionPlugin into your Rspack configuration.

```APIDOC
## ExtensionPlugin Usage

### Description

This snippet demonstrates how to import and use the `ExtensionPlugin` within your Rspack configuration file to build web extensions.

### Code

```ts
import {ExtensionPlugin} from '@/webpack/plugin-extension'

export default {
  plugins: [
    new ExtensionPlugin({
      manifestPath: '/abs/path/to/manifest.json',
      browser: 'chrome'
    })
  ]
}
```
```

--------------------------------

### extensionCreate(projectName, options)

Source: https://github.com/extension-js/extension.js/blob/main/programs/create/README.md

Creates a new extension project with the specified configuration. It takes the project name and an options object to customize the creation process, such as specifying a template or installing dependencies.

```APIDOC
## extensionCreate(projectName, options)

### Description
Creates a new extension project with the specified configuration.

### Parameters
#### Path Parameters
- `projectName` (string, required) - The name of your extension project

#### Query Parameters
- `options` (object) - Configuration options
  - `template` (string, optional) - Template name or URL. Defaults to `'javascript'` (`init` is an alias)
  - `install` (boolean, optional) - Whether to install dependencies after scaffolding. Defaults to `false` so project creation is fast and users see the familiar `npm install` output on their own.
  - `cliVersion` (string, optional) - CLI version for package.json

### Request Example
```javascript
import {extensionCreate} from 'extension-create'

// Create a basic extension (default template: javascript)
await extensionCreate('my-extension', {})

// Create a React extension and install its dependencies
await extensionCreate('my-react-extension', {
  template: 'react',
  install: true
})
```
```

--------------------------------

### Watch Builds

Source: https://github.com/extension-js/extension.js/blob/main/docs/CONTRIBUTING.md

Start a process that continuously watches for changes in all programs and rebuilds them as needed.

```sh
pnpm watch
```

--------------------------------

### Typical HtmlPlugin Usage

Source: https://github.com/extension-js/extension.js/blob/main/programs/develop/plugin-web-extension/feature-html/README.md

Configure the HtmlPlugin with the path to your manifest file for typical extension setups.

```typescript
import {HtmlPlugin} from '@/webpack/plugin-extension/feature-html'

export default {
  plugins: [
    new HtmlPlugin({
      manifestPath: '/abs/path/to/manifest.json'
    })
  ]
}
```

--------------------------------

### Force-Clean Repository

Source: https://github.com/extension-js/extension.js/blob/main/docs/CONTRIBUTING.md

Perform a deep clean of the repository, reinstall dependencies, and recompile all workspaces. Use this for troubleshooting setup issues.

```sh
git clean -xfd && pnpm install && pnpm compile
```

--------------------------------

### CssPlugin Usage

Source: https://github.com/extension-js/extension.js/blob/main/programs/develop/plugin-css/README.md

Example of how to import and use the CssPlugin in your Rspack configuration.

```APIDOC
## CssPlugin Usage

### Description

This section shows how to integrate the `CssPlugin` into your Rspack build configuration.

### Code Example

```ts
import {CssPlugin} from '@/webpack/plugin-css'

export default {
  plugins: [
    new CssPlugin({
      manifestPath: '/abs/path/to/manifest.json'
    })
  ]
}
```
```

--------------------------------

### Add Extension.js as Dev Dependency

Source: https://github.com/extension-js/extension.js/blob/main/programs/extension/README.md

Install Extension.js as a development dependency in your project using npm.

```bash
npm install extension@latest --save-dev
```

--------------------------------

### Configure ExtensionPlugin in Rspack

Source: https://github.com/extension-js/extension.js/blob/main/programs/develop/plugin-web-extension/README.md

Example of how to integrate the ExtensionPlugin into your Rspack configuration. Ensure the manifestPath is an absolute path to your extension's manifest file.

```typescript
import {ExtensionPlugin} from '@/webpack/plugin-extension'

export default {
  plugins: [
    new ExtensionPlugin({
      manifestPath: '/abs/path/to/manifest.json',
      browser: 'chrome'
    })
  ]
}
```

--------------------------------

### Initialize LocalesPlugin in Webpack Configuration

Source: https://github.com/extension-js/extension.js/blob/main/programs/develop/plugin-web-extension/feature-locales/README.md

Import and instantiate the LocalesPlugin in your webpack configuration. Provide the absolute path to your manifest.json file. This setup ensures that localization files are correctly processed and included in the build.

```typescript
import {LocalesPlugin} from '@/webpack/plugin-extension/feature-locales'

export default {
  context: __dirname,
  plugins: [
    new LocalesPlugin({
      manifestPath: require('path').resolve(__dirname, 'manifest.json')
    })
  ]
}
```

--------------------------------

### Create New Extension

Source: https://github.com/extension-js/extension.js/blob/main/docs/CONTRIBUTING.md

Scaffold a new extension project using the provided templates, then navigate into the new directory and run the development server.

```sh
pnpm extension create my-extension
cd my-extension && pnpm dev
```

--------------------------------

### Create JavaScript Starter Extension

Source: https://github.com/extension-js/extension.js/blob/main/programs/create/templates/javascript/README.md

Use this command to create a new JavaScript-based extension project using the latest template.

```bash
npx extension@latest create my-javascript --template javascript
cd my-javascript
npm install
npm run dev
```

--------------------------------

### Production Build

Source: https://github.com/extension-js/extension.js/blob/main/programs/extension/README.md

Create a production-ready bundle for extension deployment. Use the --zip flag to package the build into a ZIP file.

```bash
npx extension@latest build
```

```bash
npx extension@latest build --zip
```

--------------------------------

### Preview Production Build

Source: https://github.com/extension-js/extension.js/blob/main/programs/create/templates/javascript/README.md

Previews the production build of the extension with the bundled browser.

```bash
npm run preview
```

--------------------------------

### Create Playwright Metadata Writer for Run-Only Flows

Source: https://github.com/extension-js/extension.js/blob/main/programs/develop/plugin-playwright/README.md

Utilize createPlaywrightMetadataWriter for run-only command flows like preview or start. This reusable writer allows for writing starting, ready, or error states.

```typescript
const metadata = createPlaywrightMetadataWriter({
  packageJsonDir,
  browser,
  command: 'preview',
  distPath,
  manifestPath,
  port: null
})

metadata.writeStarting()
// ... command work ...
metadata.writeReady()
// ... or on failure ...
metadata.writeError('preview_manifest_missing', 'Expected manifest at ...')
```

--------------------------------

### Run GitHub Sample Directly

Source: https://github.com/extension-js/extension.js/blob/main/programs/extension/README.md

Execute a browser extension sample directly from a GitHub repository using the Extension.js CLI.

```bash
extension dev https://github.com/.../sample
```

--------------------------------

### CompilationPlugin Usage

Source: https://github.com/extension-js/extension.js/blob/main/programs/develop/plugin-compilation/README.md

Demonstrates how to instantiate and use the CompilationPlugin with its available options.

```APIDOC
## CompilationPlugin

### Description
Initializes the CompilationPlugin with specified options.

### Constructor
`new CompilationPlugin(options: {
  manifestPath: string
  browser?: 'chrome' | 'edge' | 'firefox' | 'safari' | 'chromium-based' | 'gecko-based'
  clean?: boolean
})`

### Parameters
#### Options
- **manifestPath** (string) - Required - Path to the manifest file.
- **browser** (string) - Optional - Specifies the target browser (e.g., 'chrome', 'firefox').
- **clean** (boolean) - Optional - If true, deletes the `dist/<browser>` folder at the start of compilation.
```

--------------------------------

### Development with Browser Selection

Source: https://github.com/extension-js/extension.js/blob/main/programs/extension/README.md

Run the development server and select a specific browser to test against. Supports Chrome, Edge, and Firefox.

```bash
npx extension@latest dev --browser=chrome
```

```bash
npx extension@latest dev --browser=edge
```

--------------------------------

### Build Production Zip for Stores

Source: https://github.com/extension-js/extension.js/blob/main/programs/extension/README.md

Create a production-ready zip archive for browser extension stores using the Extension.js CLI.

```bash
extension build --zip
```

--------------------------------

### Standalone Usage of WebResourcesPlugin

Source: https://github.com/extension-js/extension.js/blob/main/programs/develop/plugin-web-extension/feature-web-resources/README.md

Configure the WebResourcesPlugin in your Rspack/Webpack setup to specify the manifest path and include lists for content script entries.

```typescript
import * as path from 'path'
import {WebResourcesPlugin} from '@/webpack/plugin-extension/feature-web-resources'

export default {
  // ...your rspack/webpack configuration
  plugins: [
    new WebResourcesPlugin({
      manifestPath: path.resolve(__dirname, 'manifest.json'),
      includeList: {
        // Tell the plugin which content script entries to associate
        // The key is the logical entry name; the value(s) are absolute file paths
        'content_scripts:content/scripts': [
          path.resolve(__dirname, 'content/scripts.js')
        ]
      }
    })
  ]
}
```

--------------------------------

### Build Extension for Production

Source: https://github.com/extension-js/extension.js/blob/main/programs/create/templates/javascript/README.md

Builds the extension for production. Convenience scripts are available for different browsers.

```bash
npm run build           # Chrome (default)
npm run build:firefox
npm run build:edge
```

--------------------------------

### Clone the Repository

Source: https://github.com/extension-js/extension.js/blob/main/docs/CONTRIBUTING.md

Clone the Extension.js repository and navigate into the project directory.

```sh
git clone https://github.com/extension-js/extension.js.git
cd extension.js
```

--------------------------------

### Build Browser Extensions with Extension.js

Source: https://github.com/extension-js/extension.js/blob/main/extensions/extension-js-devtools/README.md

Run these commands to build your Extension.js project for different browsers.

```bash
pnpm run build:chrome

```

```bash
pnpm run build:edge

```

```bash
pnpm run build:firefox

```

--------------------------------

### Configure Development Environment

Source: https://github.com/extension-js/extension.js/blob/main/docs/CONTRIBUTING.md

Create a .env file at the repository root to enable verbose development logs and local behaviors.

```dotenv
EXTENSION_AUTHOR_MODE=development
```

--------------------------------

### Run Extension.js Development Commands

Source: https://github.com/extension-js/extension.js/blob/main/programs/develop/README.md

Import and use development commands like extensionDev, extensionBuild, extensionStart, and extensionPreview. Configure browser targets and build options.

```typescript
import {
  extensionDev,
  extensionBuild,
  extensionStart,
  extensionPreview,
  type DevOptions,
  type BuildOptions,
  type StartOptions,
  type PreviewOptions
} from 'extension-develop'

async function run() {
  // Development server
  await extensionDev(undefined, {
    browser: 'chrome',
    open: true
  } satisfies DevOptions)

  // Production build + zip
  await extensionBuild(undefined, {
    browser: 'firefox',
    zip: true
  } satisfies BuildOptions)

  // Build then preview from dist/<browser>
  await extensionStart(undefined, {browser: 'edge'} satisfies StartOptions)

  // Preview using an existing output folder or project path
  await extensionPreview(undefined, {
    browser: 'chrome',
    mode: 'production'
  } satisfies PreviewOptions)
}

run()
```

--------------------------------

### Per-Browser Production Build

Source: https://github.com/extension-js/extension.js/blob/main/programs/extension/README.md

Generate a production build specifically for a target browser, packaged as a ZIP file. This is useful for submitting to different browser stores.

```bash
npx extension@latest build --browser=firefox --zip
```

--------------------------------

### Initialize CompilationPlugin

Source: https://github.com/extension-js/extension.js/blob/main/programs/develop/plugin-compilation/README.md

Instantiate the CompilationPlugin with options for manifest path, browser target, and whether to clean the distribution folder.

```typescript
new CompilationPlugin({
  manifestPath,
  browser, // e.g. 'chrome' | 'firefox'
  clean: true // whether to remove dist/<browser> at start
})
```

--------------------------------

### Configure Extension Scripts

Source: https://github.com/extension-js/extension.js/blob/main/programs/extension/README.md

Add these scripts to your package.json to enable build, development, and preview commands for your extension.

```json
{
  "scripts": {
    "build": "extension build",
    "dev": "extension dev",
    "preview": "extension preview"
  }
}
```

--------------------------------

### WebResourcesPlugin Constructor

Source: https://github.com/extension-js/extension.js/blob/main/programs/develop/plugin-web-extension/feature-web-resources/README.md

Initializes the WebResourcesPlugin with configuration options, including the manifest file path and a list of content script entries to monitor for imported assets.

```APIDOC
## WebResourcesPlugin

### Description
Initializes the plugin with options to manage web accessible resources.

### Constructor
`new WebResourcesPlugin(options: PluginInterface)`

### Parameters
#### options (PluginInterface) - Required
An object containing the plugin configuration.

- **manifestPath** (string) - Required - The absolute path to the `manifest.json` file.
- **includeList** (Record<string, string | string[]>) - Optional - A map where keys are logical content script entry names (e.g., `content_scripts:content/scripts`) and values are absolute file paths or arrays of file paths to be scanned for imported assets.
```

--------------------------------

### CompatibilityPlugin Constructor

Source: https://github.com/extension-js/extension.js/blob/main/programs/develop/plugin-compatibility/README.md

Initializes the CompatibilityPlugin with options to configure manifest path, target browser, and polyfill behavior.

```APIDOC
## new CompatibilityPlugin(options)

### Description
Initializes the plugin with configuration options.

### Parameters
#### constructor Parameters
- **options** (object) - Required - Configuration options for the plugin.
  - **manifestPath** (string) - Required - The absolute path to the extension's manifest.json file.
  - **browser** (string) - Optional - Specifies the target browser. Can be 'chrome', 'edge', 'firefox', 'safari', 'chromium-based', or 'gecko-based'.
  - **polyfill** (boolean) - Optional - If true, provides the `browser` global using `webextension-polyfill` for Chromium-based browsers.
```

--------------------------------

### Configure Companion Extensions

Source: https://github.com/extension-js/extension.js/blob/main/programs/develop/README.md

Use this configuration to specify directories and explicit paths for companion extensions to be loaded during development and preview. Companion extensions are loaded before your main extension.

```javascript
// extension.config.mjs
export default {
  // Applies to dev/start/preview unless overridden per-command
  extensions: {
    dir: './extensions',
    paths: ['./vendor/some-unpacked-extension']
  },
  commands: {
    dev: {
      // Override only for dev
      extensions: ['./extensions/debug-helper']
    }
  }
}
```

--------------------------------

### Typical IconsPlugin Usage

Source: https://github.com/extension-js/extension.js/blob/main/programs/develop/plugin-web-extension/feature-icons/README.md

Use this snippet for typical integration within an Extension.js project. It requires the path to your manifest.json file.

```typescript
import {IconsPlugin} from '@/webpack/plugin-extension/feature-icons'

export default {
  plugins: [
    new IconsPlugin({
      manifestPath: '/abs/path/to/manifest.json'
    })
  ]
}
```

--------------------------------

### Development with Custom Browser Binary

Source: https://github.com/extension-js/extension.js/blob/main/programs/extension/README.md

Use a custom browser binary for development testing. Specify the path to the executable for Chromium-based browsers or Firefox.

```bash
npx extension@latest dev --chromium-binary "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
```

```bash
npx extension@latest dev --gecko-binary "/Applications/Firefox.app/Contents/MacOS/firefox"
```

--------------------------------

### Use Custom Chromium Binary

Source: https://github.com/extension-js/extension.js/blob/main/programs/extension/README.md

Specify a custom Chromium binary path for development or building browser extensions with Extension.js.

```bash
--chromium-binary
```

--------------------------------

### LocalesPlugin Constructor

Source: https://github.com/extension-js/extension.js/blob/main/programs/develop/plugin-web-extension/feature-locales/README.md

Initializes the LocalesPlugin with configuration options. It requires the path to the manifest.json file and optionally accepts a list of files to include.

```APIDOC
## Class: LocalesPlugin

### Description

Initializes the LocalesPlugin with configuration options. It requires the path to the manifest.json file and optionally accepts a list of files to include.

### Constructor

```ts
constructor(options: {manifestPath: string; includeList?: string[]})
```

### Parameters

- **options** (object) - Required - Configuration options for the plugin.
  - **manifestPath** (string) - Required - Absolute path to your `manifest.json`.
  - **includeList** (string[]) - Optional - File path list to include. Non-`.json` files are skipped automatically.
```

--------------------------------

### Output Mapping

Source: https://github.com/extension-js/extension.js/blob/main/programs/develop/plugin-web-extension/feature-json/README.md

Illustrates how manifest fields map to output file paths.

```APIDOC
## Output Mapping

This table shows how JSON files referenced in the `manifest.json` are mapped to output paths.

| Manifest field                             | Example input path                       | Output path example                      |
| ------------------------------------------ | ---------------------------------------- | ---------------------------------------- |
| `declarative_net_request.rule_resources[]` | `declarative_net_request/ruleset_1.json` | `declarative_net_request/ruleset_1.json` |
| `storage.managed_schema`                   | `storage/managed_schema.json`            | `storage/managed_schema.json`            |

**Notes:**
- Keys in `includeList` directly correspond to output paths (without the `.json` suffix, which is appended by the plugin).
- Files within the `public/` directory are watched and validated for critical JSON features but are not emitted by this plugin.
```

--------------------------------

### Run Local CLI

Source: https://github.com/extension-js/extension.js/blob/main/docs/CONTRIBUTING.md

Execute the local CLI, mirroring the functionality of the released 'extension' command, with support for commands, arguments, and flags.

```sh
pnpm extension <command> [args] [flags]
```

--------------------------------

### IconsPlugin Constructor and Apply Method

Source: https://github.com/extension-js/extension.js/blob/main/programs/develop/plugin-web-extension/feature-icons/README.md

The IconsPlugin is designed to be used within a build system like Rspack. It requires a manifest path and optionally accepts a list of files to include. The `apply` method integrates the plugin into the compiler's lifecycle.

```APIDOC
## IconsPlugin

### Description

Manages and validates icon files for web extensions during the build process. It checks for missing icon files referenced in manifest fields and ensures correct paths.

### Constructor

`constructor(options: { manifestPath: string, includeList?: FilepathList | Record<string, unknown> })`

- **manifestPath** (string) - Required - The path to the extension's manifest file.
- **includeList** (FilepathList | Record<string, unknown>) - Optional - A list of file paths to include or a record of unknown type.

### Apply Method

`apply(compiler: import('@rspack/core').Compiler): void`

Integrates the plugin into the Rspack compiler's lifecycle. This method is called by the compiler to enable the plugin's functionality.
```

--------------------------------

### Initialize ManifestPlugin with Include List

Source: https://github.com/extension-js/extension.js/blob/main/programs/develop/plugin-web-extension/feature-manifest/README.md

Configure the ManifestPlugin with a manifest path and a map of feature keys to absolute source file paths. This is used to validate and rewrite paths for various extension features.

```typescript
import * as path from 'path'
import {ManifestPlugin} from '@/webpack/plugin-extension/feature-manifest'

new ManifestPlugin({
  manifestPath: path.resolve(__dirname, 'manifest.json'),
  includeList: {
    // map output keys to absolute source files
    'content_scripts/content-0': path.resolve(__dirname, 'content/scripts.ts'),
    'options_ui/page': path.resolve(__dirname, 'options.html')
  }
})
```

--------------------------------

### Run All Tests

Source: https://github.com/extension-js/extension.js/blob/main/docs/CONTRIBUTING.md

Execute all tests across all packages within the monorepo using Turbo.

```sh
pnpm test
```

--------------------------------

### Use Custom Gecko Binary

Source: https://github.com/extension-js/extension.js/blob/main/programs/extension/README.md

Specify a custom Gecko binary path for development or building browser extensions with Extension.js.

```bash
--gecko-binary
```

--------------------------------

### Configure IncludeList in JsonPlugin

Source: https://github.com/extension-js/extension.js/blob/main/programs/develop/plugin-web-extension/feature-json/README.md

Demonstrates how to configure the `includeList` option when initializing the `JsonPlugin`. The `includeList` maps output paths to source JSON files or arrays of files. When a value is an array, the last entry overwrites previous ones.

```typescript
new JsonPlugin({
  manifestPath: '/abs/manifest.json',
  includeList: {
    'features/ruleset': '/abs/path/ruleset.json',
    'features/multiple': ['/abs/a.json', '/abs/b.json']
  }
})
```

--------------------------------

### CompatibilityPlugin.apply

Source: https://github.com/extension-js/extension.js/blob/main/programs/develop/plugin-compatibility/README.md

Applies the plugin to the Webpack compiler, enabling cross-browser compatibility features.

```APIDOC
## CompatibilityPlugin.apply(compiler)

### Description
Applies the plugin to the Webpack compiler instance.

### Parameters
#### compiler Parameters
- **compiler** (import('@rspack/core').Compiler) - Required - The Webpack compiler instance to which the plugin will be applied.
```

--------------------------------

### JsonPlugin Usage

Source: https://github.com/extension-js/extension.js/blob/main/programs/develop/plugin-web-extension/feature-json/README.md

Demonstrates how to import and configure the JsonPlugin in your Rspack configuration.

```APIDOC
## JsonPlugin Configuration

### Description
Configure the `JsonPlugin` to handle JSON assets referenced in your extension's `manifest.json`.

### Constructor
```typescript
new JsonPlugin(options: PluginInterface)
```

### Options
#### `manifestPath`
- **Type**: `string`
- **Required**: Yes
- **Description**: Absolute path to the `manifest.json` file.

#### `includeList`
- **Type**: `FilepathList` (Record<string, string | string[] | undefined>)
- **Required**: No
- **Description**: Optionally restrict or extend which JSON files are handled. Keys are output paths (without `.json`), and values are absolute file paths to the JSON files.

### Example
```typescript
import type {Configuration} from '@rspack/core'
import {JsonPlugin} from '@/webpack/plugin-extension/feature-json'

const config: Configuration = {
  plugins: [
    new JsonPlugin({
      manifestPath: require('path').resolve(process.cwd(), 'manifest.json'),
      includeList: {
        // 'declarative_net_request/ruleset_1': '/abs/path/to/ruleset_1.json'
      }
    })
  ]
}

export default config
```
```

--------------------------------

### StaticAssetsPlugin Usage

Source: https://github.com/extension-js/extension.js/blob/main/programs/develop/plugin-static-assets/README.md

Demonstrates how to import and use the StaticAssetsPlugin in your webpack configuration.

```APIDOC
## StaticAssetsPlugin Usage

### Description
Import and instantiate the `StaticAssetsPlugin` in your webpack configuration to manage static assets.

### Method
```ts
new StaticAssetsPlugin({
  manifestPath: string,
  mode: 'development' | 'production'
})
```

### Parameters
#### Options
- **manifestPath** (string) - Required - The absolute path to the manifest file.
- **mode** (string) - Required - The environment mode, either 'development' or 'production'.

### Request Example
```ts
import {StaticAssetsPlugin} from '@/webpack/plugin-static-assets'

export default {
  plugins: [
    new StaticAssetsPlugin({
      manifestPath: '/abs/path/to/manifest.json',
      mode: process.env.NODE_ENV === 'production' ? 'production' : 'development'
    })
  ]
}
```
```

--------------------------------

### Standalone IconsPlugin Usage with Manual Include List

Source: https://github.com/extension-js/extension.js/blob/main/programs/develop/plugin-web-extension/feature-icons/README.md

Use this snippet when integrating the IconsPlugin standalone, providing a manual `includeList` for icon files. This allows explicit control over which icons are emitted and to which subfolders.

```typescript
import * as path from 'path'
import {IconsPlugin} from '@/webpack/plugin-extension/feature-icons'

export default {
  // ...your rspack/webpack configuration
  plugins: [
    new IconsPlugin({
      manifestPath: path.resolve(__dirname, 'manifest.json'),
      includeList: {
        // Emits to dist/icons/
        icons: [
          path.resolve(__dirname, 'icons/extension_16.png'),
          path.resolve(__dirname, 'icons/extension_48.png')
        ],

        // Emits to dist/icons/
        'action/default_icon': [
          path.resolve(__dirname, 'icons/extension_16.png')
        ],

        // Emits to dist/icons/
        'browser_action/default_icon': [
          path.resolve(__dirname, 'icons/extension_16.png')
        ],

        // Emits to dist/browser_action/
        'browser_action/theme_icons': [
          path.resolve(__dirname, 'icons/extension_16.png'),
          path.resolve(__dirname, 'icons/extension_48.png')
        ],

        // Emits to dist/icons/
        'page_action/default_icon': [
          path.resolve(__dirname, 'icons/extension_16.png')
        ],

        // Emits to dist/icons/
        'sidebar_action/default_icon': [
          path.resolve(__dirname, 'icons/extension_16.png')
        ]
      }
    })
  ]
}
```

--------------------------------

### Run Single Package Script with Turbo

Source: https://github.com/extension-js/extension.js/blob/main/docs/CONTRIBUTING.md

Use Turbo filters to run a specific script within a single package, demonstrated here with the 'test' script for the './programs/cli' package.

```sh
pnpm -w turbo run test --filter=./programs/cli
```

--------------------------------

### ExtensionPlugin API

Source: https://github.com/extension-js/extension.js/blob/main/programs/develop/plugin-web-extension/README.md

Details the constructor and properties of the ExtensionPlugin class.

```APIDOC
## ExtensionPlugin API

### Description

This section outlines the `ExtensionPlugin` class, including its static name and constructor signature, which is used to configure the web extension build process.

### Class

`ExtensionPlugin`

### Constructor

`constructor(options: {
  manifestPath: string
  browser?:
    | 'chrome'
    | 'edge'
    | 'firefox'
    | 'safari'
    | 'chromium-based'
    | 'gecko-based'
})`

- **options.manifestPath** (string) - Required - The absolute path to the extension's manifest file.
- **options.browser** (string) - Optional - Specifies the target browser for compatibility. Can be one of 'chrome', 'edge', 'firefox', 'safari', 'chromium-based', or 'gecko-based'.

### Static Properties

- **`name`**: `'plugin-extension'` (string) - The static name of the plugin.
```

--------------------------------

### StaticAssetsPlugin API

Source: https://github.com/extension-js/extension.js/blob/main/programs/develop/plugin-static-assets/README.md

Defines the constructor options and apply method for the StaticAssetsPlugin. The plugin requires a manifest path and a mode ('development' or 'production').

```typescript
export class StaticAssetsPlugin {
  static readonly name: 'plugin-static-assets'
  constructor(options: {
    manifestPath: string
    mode: 'development' | 'production'
  })
  apply(compiler: import('@rspack/core').Compiler): Promise<void>
}
```

--------------------------------

### Run Linter

Source: https://github.com/extension-js/extension.js/blob/main/docs/CONTRIBUTING.md

Enforce code style and catch potential errors using ESLint.

```sh
pnpm lint
```

--------------------------------

### JsFrameworksPlugin Usage

Source: https://github.com/extension-js/extension.js/blob/main/programs/develop/plugin-js-frameworks/README.md

Demonstrates how to import and use the JsFrameworksPlugin in your Rspack configuration file. It shows the required options for initializing the plugin.

```APIDOC
## JsFrameworksPlugin

### Description

This plugin automatically wires JS frameworks and TypeScript into the Rspack build. It detects frameworks, configures SWC parsing, adds necessary loaders and plugins, and sets up `tsconfig` resolution.

### Constructor

- `options` (object) - Required
  - `manifestPath` (string) - Required - The absolute path to the manifest.json file.
  - `mode` ('development' | 'production') - Required - The build mode, typically derived from `process.env.NODE_ENV`.

### Example Usage

```ts
import {JsFrameworksPlugin} from '@/webpack/plugin-js-frameworks'

export default {
  plugins: [
    new JsFrameworksPlugin({
      manifestPath: '/abs/path/to/manifest.json',
      mode: process.env.NODE_ENV === 'production' ? 'production' : 'development'
    })
  ]
}
```
```

--------------------------------

### Environment Variables in Extension.js Config

Source: https://github.com/extension-js/extension.js/blob/main/programs/develop/README.md

Configure browser settings and command-specific options using environment variables within `extension.config.js`. Environment files are loaded in a specific order, and only explicitly read variables are used.

```javascript
// extension.config.js (Node-based)
export default {
  browser: {
    chrome: {
      startingUrl:
        process.env.EXTENSION_PUBLIC_START_URL || 'https://example.com'
    }
  },
  commands: {
    dev: {
      // Unified logger defaults for `extension dev`
      logLevel: 'off',
      // omit or set to undefined to include all
      logContexts: ['background', 'content'],
      logFormat: 'pretty',
      logTimestamps: true,
      logColor: true,
      // Optional filters
      logUrl: '/example\\.com/i',
      logTab: 123
    }
  },
  // Either a function
  config: (config) => config
  // Or a plain object to merge
  // config: { resolve: { alias: { react: 'preact/compat' } } }
}
```

--------------------------------

### SpecialFoldersPlugin Usage

Source: https://github.com/extension-js/extension.js/blob/main/programs/develop/plugin-special-folders/README.md

Demonstrates how to import and use the SpecialFoldersPlugin in your Rspack/Webpack configuration.

```APIDOC
## SpecialFoldersPlugin Usage

### Description
Import and configure the `SpecialFoldersPlugin` in your build tool's configuration file.

### Method
```ts
import {SpecialFoldersPlugin} from '@/plugin-special-folders'
```

### Endpoint
N/A (This is a plugin configuration)

### Parameters
#### Request Body
- **options** (object) - Required - Options for the plugin.
  - **manifestPath** (string) - Required - The absolute path to your `manifest.json` file.

### Request Example
```ts
// ... your Rspack/Webpack config
plugins: [
  new SpecialFoldersPlugin({
    // Absolute path to your manifest.json
    manifestPath: '/absolute/path/to/manifest.json'
  })
]
```

### Response
N/A (This is a plugin configuration)
```

--------------------------------

### SpecialFoldersPlugin Class

Source: https://github.com/extension-js/extension.js/blob/main/programs/develop/plugin-special-folders/README.md

Details about the SpecialFoldersPlugin class, including its constructor and static properties.

```APIDOC
## SpecialFoldersPlugin Class

### Description
Provides the core functionality for handling special folders in an extension project.

### Class Definition
```ts
export declare class SpecialFoldersPlugin {
  static readonly name: string
  constructor(options: SpecialFoldersPluginOptions)
}

export interface SpecialFoldersPluginOptions {
  manifestPath: string
}
```

### Properties
#### Static Properties
- **name** (string) - The static name of the plugin.

### Constructor
- **constructor(options: SpecialFoldersPluginOptions)**: Initializes the plugin with the provided options.
  - **options** (object) - Required - Configuration options for the plugin.
    - **manifestPath** (string) - Required - The absolute path to the `manifest.json` file.
```

--------------------------------

### WasmPlugin Usage

Source: https://github.com/extension-js/extension.js/blob/main/programs/develop/plugin-wasm/README.md

Demonstrates how to import and use the WasmPlugin in your webpack configuration.

```APIDOC
## WasmPlugin Usage

### Description
Import and instantiate the `WasmPlugin` in your webpack configuration to enable WebAssembly support.

### Method
```ts
new WasmPlugin(options: {
  manifestPath: string
  mode: 'development' | 'production'
})
```

### Parameters
#### Options
- **manifestPath** (string) - Required - The absolute path to the manifest JSON file.
- **mode** (string) - Required - The build mode, either 'development' or 'production'.

### Request Example
```ts
import {WasmPlugin} from '@/webpack/plugin-wasm'

export default {
  plugins: [
    new WasmPlugin({
      manifestPath: '/abs/path/to/manifest.json',
      mode: process.env.NODE_ENV === 'production' ? 'production' : 'development'
    })
  ]
}
```
```

--------------------------------

### StaticAssetsPlugin Class

Source: https://github.com/extension-js/extension.js/blob/main/programs/develop/plugin-static-assets/README.md

Details of the StaticAssetsPlugin class, including its constructor and apply method.

```APIDOC
## StaticAssetsPlugin Class

### Description
Provides the core functionality for emitting static assets. It includes a constructor for configuration and an `apply` method that integrates with the webpack compiler.

### Class
```ts
export class StaticAssetsPlugin {
  static readonly name: 'plugin-static-assets'
  constructor(options: {
    manifestPath: string
    mode: 'development' | 'production'
  })
  apply(compiler: import('@rspack/core').Compiler): Promise<void>
}
```

### Constructor Parameters
- **options** (object) - Required - Configuration options for the plugin.
  - **manifestPath** (string) - Required - The absolute path to the manifest file.
  - **mode** (string) - Required - The environment mode, either 'development' or 'production'.

### Methods
#### apply
- **compiler** (import('@rspack/core').Compiler) - The webpack compiler instance.
- **Returns**: Promise<void>
```

--------------------------------

### Configure WasmPlugin in Webpack

Source: https://github.com/extension-js/extension.js/blob/main/programs/develop/plugin-wasm/README.md

Import and instantiate the WasmPlugin in your webpack configuration. Provide the manifestPath and mode options.

```typescript
import {WasmPlugin} from '@/webpack/plugin-wasm'

export default {
  plugins: [
    new WasmPlugin({
      manifestPath: '/abs/path/to/manifest.json',
      mode: process.env.NODE_ENV === 'production' ? 'production' : 'development'
    })
  ]
}
```

--------------------------------

### Configure Static Assets Plugin

Source: https://github.com/extension-js/extension.js/blob/main/programs/develop/plugin-static-assets/README.md

Import and configure the StaticAssetsPlugin in your webpack configuration. Set the manifest path and mode based on the environment.

```typescript
import {StaticAssetsPlugin} from '@/webpack/plugin-static-assets'

export default {
  plugins: [
    new StaticAssetsPlugin({
      manifestPath: '/abs/path/to/manifest.json',
      mode: process.env.NODE_ENV === 'production' ? 'production' : 'development'
    })
  ]
}
```

--------------------------------

### CompatibilityPlugin API Definition

Source: https://github.com/extension-js/extension.js/blob/main/programs/develop/plugin-compatibility/README.md

This defines the constructor options for the CompatibilityPlugin. The `browser` option can specify the target browser, and `polyfill` enables the `webextension-polyfill` for Chromium-based browsers. Note that the polyfill is not injected for Firefox.

```typescript
export class CompatibilityPlugin {
  constructor(options: {
    manifestPath: string
    browser?:
      | 'chrome'
      | 'edge'
      | 'firefox'
      | 'safari'
      | 'chromium-based'
      | 'gecko-based'
    polyfill?: boolean
  })
  apply(compiler: import('@rspack/core').Compiler): Promise<void>
}
```

--------------------------------

### Run Focused Test Groups

Source: https://github.com/extension-js/extension.js/blob/main/docs/CONTRIBUTING.md

Execute specific groups of tests, such as CLI, development, or build-related tests.

```sh
pnpm test:cli | pnpm test:dev | pnpm test:build
```