WXT

https://wxt.dev/
Admin
WXT is a next-gen web extension framework that accelerates development with fast HMR, file-based...
Tokens:134,874
Snippets:1,428
Trust Score:8.1
Update:1 week ago
Show doc for...
Tokens:
Raw
### start()

Source: https://wxt.dev/api/reference/wxt/interfaces/wxtdevserver

Starts the development server.

```APIDOC
## start()

### Description
Starts the development server.

### Method
start

### Parameters
None

### Returns
`Promise<void>`

```

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

### createServer() usage example

Source: https://wxt.dev/api/reference/wxt/functions/createserver

Creates a dev server and pre-builds all the files that need to exist before loading the extension. The example shows how to call `createServer` with an inline config and then start the server.

```ts
const server = await wxt.createServer({
    // Enter config...
  });
  await server.start();
```

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

### Add a runtime plugin with addWxtPlugin

Source: https://wxt.dev/api/reference/wxt/modules/functions/addwxtplugin

Use this example to register a runtime plugin inside a module's setup function. The plugin argument is an import from an NPM module or an absolute file path. The wxt instance is provided by the module's setup function.

```ts
export default defineWxtModule((wxt) => {
    addWxtPlugin(wxt, 'wxt-module-analytics/client-plugin');
  });
```

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

### Install @wxt-dev/is-background with pnpm

Source: https://wxt.dev/is-background.html

Install the package using pnpm.

```sh
pnpm add @wxt-dev/is-background
```

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

### listen()

Source: https://wxt.dev/api/reference/wxt/interfaces/wxtbuilderserver

Starts the development server.

```APIDOC
## listen()

### Description
Starts the development server.

### Method
listen()

### Returns
`Promise<void>`

### Source
[packages/wxt/src/types.ts:1281](https://github.com/wxt-dev/wxt/blob/c89749b30fb61745d174c77b19a0d7ca3bd14992/packages/wxt/src/types.ts#L1281)
```

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

### addEntrypoint usage example

Source: https://wxt.dev/api/reference/wxt/modules/functions/addentrypoint

Adds a TS/JS file as an entrypoint to the project. Use this in a module's setup function to register an entrypoint that will be bundled with the extension. The example shows a content-script entrypoint with a custom name and input path.

```ts
export default defineWxtModule(async (wxt, options) => {
    const entrypointPath = '/path/to/my-entrypoint.ts';
    addEntrypoint(wxt, {
      type: 'content-script',
      name: 'some-name',
      inputPath: entrypointPath,
      outputDir: entrypointPath,
    });
  });
```

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

### Install WXT with Bun

Source: https://wxt.dev/guide/installation.html

Installs WXT as a dev dependency using Bun.

```sh
bun add -D wxt
```

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

### outBaseDir Example

Source: https://wxt.dev/api/reference/wxt/interfaces/resolvedconfig

Example value for the outBaseDir property, showing an absolute path to the .output directory.

```typescript
'/path/to/project/.output';
```

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

### server:started

Source: https://wxt.dev/api/reference/wxt/interfaces/wxthooks

Called when the dev server is started. Provides the WXT object and the dev server instance.

```APIDOC
## server:started

### Description
Called when the dev server is started.

### Signature
`(wxt: Wxt, server: WxtDevServer) => HookResult`

### Parameters
- **wxt** (Wxt) - Required - The configured WXT object
- **server** (WxtDevServer) - Required - Same as `wxt.server`, the object WXT uses to control the dev server.

### Returns
HookResult

### Source
[packages/wxt/src/types.ts:1504](https://github.com/wxt-dev/wxt/blob/c89749b30fb61745d174c77b19a0d7ca3bd14992/packages/wxt/src/types.ts#L1504)
```

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

### Install web-ext to enable browser opening

Source: https://wxt.dev/guide/resources/upgrading

Install `web-ext` as a devDependency to continue opening the browser automatically during dev mode; it is now an optional peer dependency.

```sh
pnpm add -D web-ext
```

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

### Install WXT with pnpm

Source: https://wxt.dev/guide/installation.html

Installs WXT as a dev dependency using pnpm.

```sh
pnpm i -D wxt
```

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

### Install WXT with --ignore-scripts

Source: https://wxt.dev/guide/resources/upgrading

Install the latest WXT version while skipping scripts so that `wxt prepare` does not run, as it may throw an error after a major version change.

```sh
pnpm i wxt@latest --ignore-scripts
```

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

### outDir Example

Source: https://wxt.dev/api/reference/wxt/interfaces/resolvedconfig

Example value for the outDir property, showing an absolute path to the target output directory.

```typescript
'/path/to/project/.output/chrome-mv3';
```

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

### outDirTemplate example

Source: https://wxt.dev/api/reference/wxt/interfaces/inlineconfig

Example template string for customizing the output directory structure. Available variables include {{browser}}, {{manifestVersion}}, {{mode}}, {{modeSuffix}}, and {{command}}.

```ts
'{{browser}}-mv{{manifestVersion}}';
```

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

### plugins Array Example

Source: https://wxt.dev/api/reference/wxt/interfaces/resolvedconfig

Example value for the plugins property; each path should be resolvable by Vite and export a default defineWxtPlugin.

```typescript
['@wxt-dev/module-vue/plugin', 'wxt-module-google-analytics/plugin'];
```

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

### Install WXT with NPM

Source: https://wxt.dev/guide/installation.html

Installs WXT as a dev dependency using NPM.

```sh
npm i -D wxt
```

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

### Install @wxt-dev/i18n with pnpm

Source: https://wxt.dev/i18n.html

Install the @wxt-dev/i18n package using pnpm.

```sh
pnpm i @wxt-dev/i18n
```

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

### Install WXT with Yarn

Source: https://wxt.dev/guide/installation.html

Installs WXT as a dev dependency using Yarn.

```sh
yarn add --dev wxt
```

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

### Install @wxt-dev/analytics with pnpm

Source: https://wxt.dev/analytics.html

Install the NPM package using pnpm. Run this in your project root before configuring the WXT module.

```bash
pnpm i @wxt-dev/analytics
```

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

### Install and import @wxt-dev/storage without WXT

Source: https://wxt.dev/storage.html

Install the @wxt-dev/storage package and import it when not using WXT.

```sh
npm i @wxt-dev/storage
pnpm add @wxt-dev/storage
yarn add @wxt-dev/storage
bun add @wxt-dev/storage
```

```ts
import { storage } from '@wxt-dev/storage';
```

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

### zip:extension:start

Source: https://wxt.dev/api/reference/wxt/interfaces/wxthooks

Called before zipping the extension files.

```APIDOC
## zip:extension:start

### Description
Called before zipping the extension files.

### Signature
`(wxt: Wxt) => HookResult`

### Parameters
- **wxt** (Wxt) - Required - The configured WXT object

### Returns
HookResult

### Source
[packages/wxt/src/types.ts:1460](https://github.com/wxt-dev/wxt/blob/c89749b30fb61745d174c77b19a0d7ca3bd14992/packages/wxt/src/types.ts#L1460)
```

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

### Example configuration for zip.includeSources and zip.excludeSources

Source: https://wxt.dev/guide/resources/upgrading

Configuration example for wxt.config.ts showing how to set zip.includeSources and zip.excludeSources after the v0.21 behavior change. Set zip.dotSources to true if hidden files are needed. Run `wxt zip -b firefox` to verify the zipped file list.

```ts
// wxt.config.ts
export default defineConfig({
  zip: {
    includeSources: [...],
    excludeSources: [...],
    dotSources: true,
  },
});
```

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

### Configure WXT with Solid module

Source: https://wxt.dev/guide/essentials/frontend-frameworks

Install @wxt-dev/module-solid and add it to the modules array in wxt.config.ts to enable Solid support.

```ts
import { defineConfig } from 'wxt';

export default defineConfig({
  modules: ['@wxt-dev/module-solid'],
});
```

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

### Configure WXT with React module

Source: https://wxt.dev/guide/essentials/frontend-frameworks

Install @wxt-dev/module-react and add it to the modules array in wxt.config.ts to enable React support.

```ts
import { defineConfig } from 'wxt';

export default defineConfig({
  modules: ['@wxt-dev/module-react'],
});
```

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

### Bootstrap with NPM

Source: https://wxt.dev/guide/installation.html

Run the init command with NPM to bootstrap a new WXT project and follow the prompts.

```sh
npx wxt@latest init
```

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

### Bootstrap with Bun

Source: https://wxt.dev/guide/installation.html

Run the init command with Bun to bootstrap a new WXT project and follow the prompts.

```sh
bunx wxt@latest init
```

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

### zip:start

Source: https://wxt.dev/api/reference/wxt/interfaces/wxthooks

Called before the zip process starts.

```APIDOC
## zip:start

### Description
Called before the zip process starts.

### Signature
`(wxt: Wxt) => HookResult`

### Parameters
- **wxt** (Wxt) - Required - The configured WXT object

### Returns
HookResult

### Source
[packages/wxt/src/types.ts:1454](https://github.com/wxt-dev/wxt/blob/c89749b30fb61745d174c77b19a0d7ca3bd14992/packages/wxt/src/types.ts#L1454)
```

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

### Create a new project with Bun

Source: https://wxt.dev/guide/installation.html

Initializes a new project directory with Bun.

```sh
cd my-project
bun init
```

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

### Bootstrap with PNPM

Source: https://wxt.dev/guide/installation.html

Run the init command with PNPM to bootstrap a new WXT project and follow the prompts.

```sh
pnpm dlx wxt@latest init
```

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

### Install UnoCSS packages with npm, pnpm, yarn, or bun

Source: https://wxt.dev/unocss.html

Install the @wxt-dev/unocss and unocss packages using your preferred package manager. The same two packages are installed in all four commands.

```sh
npm i --save-dev @wxt-dev/unocss unocss
pnpm i -D @wxt-dev/unocss unocss
yarn add --dev @wxt-dev/unocss unocss
bun add -D @wxt-dev/unocss unocss
```

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

### Create a new project with NPM

Source: https://wxt.dev/guide/installation.html

Initializes a new project directory with npm.

```sh
cd my-project
npm init
```

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

### createServer()

Source: https://wxt.dev/api/reference/wxt/functions/createserver

Creates a dev server and pre-builds all the files that need to exist before loading the extension.

```APIDOC
## Function: createServer()

### Description
Creates a dev server and pre-builds all the files that need to exist before loading the extension.

### Signature
`createServer(inlineConfig?: InlineConfig): Promise<WxtDevServer>`

### Parameters
- **inlineConfig** (InlineConfig) - Optional. Configuration for the dev server.

### Returns
`Promise<WxtDevServer>` - A promise that resolves to a WxtDevServer instance.

### Example
```ts
const server = await wxt.createServer({
    // Enter config...
  });
  await server.start();
```

### Source
[packages/wxt/src/create-server.ts:31](https://github.com/wxt-dev/wxt/blob/c89749b30fb61745d174c77b19a0d7ca3bd14992/packages/wxt/src/create-server.ts#L31)
```

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

### Create a new project with pnpm

Source: https://wxt.dev/guide/installation.html

Initializes a new project directory with pnpm.

```sh
cd my-project
pnpm init
```

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

### Disable WXT runner to install extension manually

Source: https://wxt.dev/guide/resources/faq

Alternative approach: disable the WXT runner and install the extension in a regular Chrome profile manually. This is useful when you prefer to manage the extension installation yourself.

```TypeScript
// wxt.config.ts
export default defineConfig({
  webExt: {
    disabled: true,
  },
});
```

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

### Create a new project with Yarn

Source: https://wxt.dev/guide/installation.html

Initializes a new project directory with Yarn.

```sh
cd my-project
yarn init
```

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

### Install @wxt-dev/browser

Source: https://wxt.dev/guide/essentials/extension-apis

Installs @wxt-dev/browser as a direct dependency, required before augmenting the Browser type with Firefox-specific APIs.

```sh
pnpm add @wxt-dev/browser
```

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

### Generate a new vanilla WXT project

Source: https://wxt.dev/guide/resources/migrate

Run this command to scaffold a new vanilla WXT project, which is the recommended starting point for migrating an existing project. The command uses pnpm dlx to run the latest wxt init with the vanilla template.

```sh
cd path/to/your/project
pnpm dlx wxt@latest init example-wxt --template vanilla
```

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

### Bootstrap with Yarn

Source: https://wxt.dev/guide/installation.html

Use NPM initially, but select Yarn when prompted.

```sh
# Use NPM initially, but select Yarn when prompted
npx wxt@latest init
```

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

### suppressWarnings example

Source: https://wxt.dev/api/reference/wxt/interfaces/inlineconfig

Example of suppressing the firefoxDataCollection warning during the build process. The suppressWarnings option accepts an object with boolean properties for firefoxDataCollection and firefoxId.

```ts
export default defineConfig({
    suppressWarnings: {
      firefoxDataCollection: true,
    },
  });
```

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

### Run wxt prepare after upgrade

Source: https://wxt.dev/guide/resources/upgrading

Run `wxt prepare` after upgrading to fix type errors and ensure the project is ready for development.

```sh
pnpm wxt prepare
```

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

### Recommended folder structure for multiple apps

Source: https://wxt.dev/guide/essentials/frontend-frameworks

Shows the recommended directory layout for multiple entrypoints, each with its own index.html, app, and styles.

```html
📂 {srcDir}/
   📂 assets/          <---------- Put shared assets here
      📄 tailwind.css
   📂 components/
      📄 Button.tsx
   📂 entrypoints/
      📂 options/       <--------- Use a folder with an index.html file in it
         📁 pages/      <--------- A good place to put your router pages if you have them
         📄 index.html
         📄 App.tsx
         📄 main.tsx    <--------- Create and mount your app here
         📄 style.css   <--------- Entrypoint-specific styles
         📄 router.ts
```

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

### Install postcss-rem-to-responsive-pixel with bun

Source: https://wxt.dev/guide/resources/faq

Install the postcss-rem-to-responsive-pixel package as a dev dependency using bun. This is the first step to convert rem units to px at build time.

```sh
bun i -D postcss-rem-to-responsive-pixel
```

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

### getItems() example

Source: https://wxt.dev/api/reference/wxt/utils/storage/interfaces/wxtstorage

Retrieves multiple storage items in the order requested. The return order is guaranteed to match the order of the keys.

```ts
await storage.getItems(['local:installDate', 'session:someCounter']);
```

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

### MatchPattern usage example

Source: https://wxt.dev/api/reference/wxt/utils/match-patterns/classes/matchpattern

Creates a MatchPattern instance and tests whether a URL matches the pattern. The example checks a URL against the pattern and logs the boolean result.

```typescript
const pattern = new MatchPattern('https://example.com/*');
pattern.isHostPathMatch('https://example.com/path'); // true
```

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

### Install @wxt-dev/auto-icons with npm, pnpm, yarn, and bun

Source: https://wxt.dev/auto-icons.html

Install the @wxt-dev/auto-icons package using your preferred package manager. Choose one of the four commands based on your environment.

```sh
npm i --save-dev @wxt-dev/auto-icons
```

```sh
pnpm i -D @wxt-dev/auto-icons
```

```sh
yarn add --dev @wxt-dev/auto-icons
```

```sh
bun add -D @wxt-dev/auto-icons
```

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

### Add wxt prepare to postinstall script

Source: https://wxt.dev/guide/essentials/config/auto-imports.html

Adds `wxt prepare` to the `postinstall` script in package.json so that TypeScript and your editor recognize auto-imported variables after installing dependencies. This is required for type checking and editor support.

```jsonc
// package.json
{
  "scripts": {
    "postinstall": "wxt prepare", 
  },
}
```

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

### onInvalidated() usage example

Source: https://wxt.dev/api/reference/wxt/utils/content-script-context/classes/contentscriptcontext

Registers a listener for context invalidation and returns a cleanup function. The example shows adding and removing a runtime message listener inside the invalidation callback.

```ts
browser.runtime.onMessage.addListener(cb);
  const removeInvalidatedListener = ctx.onInvalidated(() => {
    browser.runtime.onMessage.removeListener(cb);
  });
  // ...
  removeInvalidatedListener();
```

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

### addViteConfig usage example

Source: https://wxt.dev/api/reference/wxt/modules/functions/addviteconfig

Example of using addViteConfig inside a wxt module to add Vite config. The function receives the wxt instance and a function returning the Vite config, same format as `vite` in `wxt.config.ts`.

```ts
export default defineWxtModule((wxt, options) => {
  addViteConfig(wxt, () => ({
  build: {
  sourceMaps: true,
  },
  });
  });
```

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

### Run a web extension with the JS API

Source: https://wxt.dev/runner.html

Use the `run` function from `@wxt-dev/runner` to programmatically open a browser and install a web extension from a local directory. Pass the path to the extension directory in `extensionDir` and any other options.

```typescript
import { run } from '@wxt-dev/runner';

await run({
  extensionDir: '/path/to/extension',
  // Other options...
});
```

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

### main()

Source: https://wxt.dev/api/reference/wxt/interfaces/mainworldcontentscriptdefinition

The main entry point method for the content script.

```APIDOC
## main()

### Description
Main entry point for the content script. This method is called when the content script is injected.

### Method
main

### Parameters
None

### Returns
void
```
Tokens:
Raw