WXT

https://github.com/wxt-dev/wxt
Admin
WXT is a next-generation framework for developing web extensions, offering features like HMR,...
Tokens:150,115
Snippets:945
Trust Score:6.9
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install unreleased versions with pkg.pr.new shorthands

Source: https://github.com/wxt-dev/wxt/blob/main/CONTRIBUTING.md

Shorthand examples for installing unreleased versions: from a PR number, from a branch, or from a specific commit.

```sh
# Install the latest build of `wxt` from a PR:
npm i https://pkg.pr.new/wxt@1283

# Install the latest build of `@wxt-dev/module-react` on the `main` branch
npm i https://pkg.pr.new/@wxt-dev/module-react@main

# Install `@wxt-dev/storage` from a specific commit:
npm i https://pkg.pr.new/@wxt-dev/module-react@426f907
```

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

### Run extension in dev mode (Bun, PNPM, NPM, Yarn)

Source: https://github.com/wxt-dev/wxt/blob/main/docs/guide/installation.md

Step 5 of setting up from scratch: run the dev command to start the extension in development mode. WXT will automatically open a browser window with your extension installed.

```sh
bun run dev
```

```sh
pnpm dev
```

```sh
npm run dev
```

```sh
yarn dev
```

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

### Start docs website

Source: https://github.com/wxt-dev/wxt/blob/main/CONTRIBUTING.md

Starts the VitePress documentation website locally for development.

```sh
# Start the docs website locally
bun run docs:dev
```

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

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

Source: https://github.com/wxt-dev/wxt/blob/main/packages/i18n/README.md

Install the package using pnpm. This is the first step for both WXT and non-WXT setups.

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

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

### Install webextension-polyfill with pnpm

Source: https://github.com/wxt-dev/wxt/blob/main/packages/webextension-polyfill/README.md

Install the required packages using pnpm.

```sh
pnpm i @wxt-dev/webextension-polyfill webextension-polyfill
```

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

### Install and use @wxt-dev/analytics without WXT

Source: https://github.com/wxt-dev/wxt/blob/main/packages/analytics/README.md

Install the @wxt-dev/analytics package, create an analytics instance with createAnalytics, import it in the background to initialize the message listener, and use the instance to report events. The example uses a placeholder providers array.

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

```ts
// utils/analytics.ts
import { createAnalytics } from '@wxt-dev/analytics';

export const analytics = createAnalytics({
  providers: [
    // ...
  ],
});
```

```ts
// background.ts
import './utils/analytics';
```

```ts
import { analytics } from './utils/analytics';

await analytics.track('some-event');
await analytics.page();
await analytics.identify('some-user-id');
analytics.autoTrack(document.body);
```

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

### Install web-ext to enable browser opening

Source: https://github.com/wxt-dev/wxt/blob/main/docs/guide/resources/upgrading.md

Install web-ext as a dev dependency to continue automatically opening the browser during dev mode.

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

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

### Example messages.json for English

Source: https://github.com/wxt-dev/wxt/blob/main/docs/guide/essentials/i18n.md

Example messages.json file with a helloWorld message.

```jsonc
// public/_locales/en/messages.json
{
  "helloWorld": {
    "message": "Hello world!",
  },
}
```

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

### Install React and @wxt-dev/module-react

Source: https://github.com/wxt-dev/wxt/blob/main/packages/module-react/README.md

Install React and the module as a dev dependency.

```sh
pnpm i react react-dom
pnpm i -D @wxt-dev/module-react
```

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

### Install Vue and module

Source: https://github.com/wxt-dev/wxt/blob/main/packages/module-vue/README.md

Install Vue and the module as a dev dependency.

```sh
pnpm i vue
pnpm i -D @wxt-dev/module-vue
```

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

### Install webextension-polyfill and @wxt-dev/webextension-polyfill

Source: https://github.com/wxt-dev/wxt/blob/main/docs/guide/resources/upgrading.md

To continue using the polyfill, install the webextension-polyfill package and WXT's new polyfill module.

```sh
pnpm i webextension-polyfill @wxt-dev/webextension-polyfill
```

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

### Install and use @wxt-dev/analytics with WXT

Source: https://github.com/wxt-dev/wxt/blob/main/packages/analytics/README.md

Install the @wxt-dev/analytics package, add the WXT module to wxt.config.ts, configure a provider in app.config.ts, and use the #analytics module to report events. The app.config.ts example uses the umami provider and enables debug mode.

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

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

```ts
// <srcDir>/app.config.ts
import { umami } from '@wxt-dev/analytics/providers/umami';

export default defineAppConfig({
  analytics: {
    debug: true,
    providers: [
      // ...
    ],
  },
});
```

```ts
import { analytics } from '#analytics';

await analytics.track('some-event');
await analytics.page();
await analytics.identify('some-user-id');
analytics.autoTrack(document.body);
```

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

### Install dependencies with bun install

Source: https://github.com/wxt-dev/wxt/blob/main/CONTRIBUTING.md

Install project dependencies using Bun, the package manager used by WXT for development.

```sh
bun install
```

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

### Install @wxt-dev/browser

Source: https://github.com/wxt-dev/wxt/blob/main/packages/browser/README.md

Installs the package from NPM using pnpm. Not needed when using WXT as it is already installed.

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

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

### Run template dev/build commands

Source: https://github.com/wxt-dev/wxt/blob/main/CONTRIBUTING.md

Commands to run inside a template directory (e.g., templates/vue) to install dependencies with npm and start the dev server or build. Use npm, not bun, as stated in the source.

```sh
cd templates/vue
npm i
npm run dev
npm run build
```

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

### Install WXT as dev dependency (Bun, PNPM, NPM, Yarn)

Source: https://github.com/wxt-dev/wxt/blob/main/docs/guide/installation.md

Step 2 of setting up from scratch: install WXT as a dev dependency using your package manager.

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

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

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

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

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

### Add wxt prepare to postinstall script

Source: https://github.com/wxt-dev/wxt/blob/main/docs/guide/essentials/config/auto-imports.md

Add wxt prepare to the postinstall script in package.json so your editor has type information after installing dependencies.

```jsonc
// package.json
{
  "scripts": {
    "postinstall": "wxt prepare", // [!code ++]
  },
}
```

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

### Bootstrap a new project with bunx

Source: https://github.com/wxt-dev/wxt/blob/main/README.md

Initializes a new WXT project using bun's bunx command. Requires bun to be installed.

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

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

### Install Svelte and module

Source: https://github.com/wxt-dev/wxt/blob/main/packages/module-svelte/README.md

Install Svelte and the module as a dev dependency using pnpm.

```sh
pnpm i svelte
pnpm i -D @wxt-dev/module-svelte
```

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

### File structure for injectScript example

Source: https://github.com/wxt-dev/wxt/blob/main/docs/guide/essentials/content-scripts.md

Shows the required entrypoints: a content script and an unlisted script for the main world.

```Plain Text
📂 entrypoints/
   📄 example.content.ts
   📄 example-main-world.ts
```

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

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

Source: https://github.com/wxt-dev/wxt/blob/main/packages/is-background/README.md

Use pnpm to add the `@wxt-dev/is-background` package to your project.

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

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

### Install solid-js and @wxt-dev/module-solid

Source: https://github.com/wxt-dev/wxt/blob/main/packages/module-solid/README.md

Install the SolidJS runtime and the module as a dev dependency. Run these commands in your project root before adding the module to your config.

```sh
pnpm i solid-js
pnpm i -D @wxt-dev/module-solid
```

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

### Run demo extension in dev mode

Source: https://github.com/wxt-dev/wxt/blob/main/CONTRIBUTING.md

Builds workspace dependencies and starts the demo extension in development mode.

```sh
# Build workspace dependencies, then start the demo extension in dev mode
bun run --filter wxt-demo dev
```

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

### Sources configuration example (wxt.config.ts)

Source: https://github.com/wxt-dev/wxt/blob/main/docs/guide/resources/upgrading.md

Example configuration for the new allowlist behavior of includeSources/excludeSources. Set dotSources to true to include hidden files, specify base folders and files in includeSources, and exclude unwanted patterns in excludeSources. Run 'wxt zip -b firefox' to verify the output.

```ts
// wxt.config.ts
export default defineConfig({
  srcDir: 'src',
  zip: {
    // Say I have a .tool-versions file I want to include
    dotSources: true,
    // Specify base folders and files to include
    includeSources: [
      'src',
      'public',
      'package.json',
      'bun.lock',
      'README.md',
      '.tool-versions',
    ],
    // Exclude any folders inside the base folders that are not needed, like test data
    excludeSources: ['**/__fixtures__'],
  },
});
```

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

### Bootstrap a new project with pnpm dlx

Source: https://github.com/wxt-dev/wxt/blob/main/README.md

Initializes a new WXT project using pnpm's dlx command. Requires pnpm to be installed.

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

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

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

Source: https://github.com/wxt-dev/wxt/blob/main/docs/guide/resources/faq.md

Install the PostCSS plugin as a dev dependency to convert rem units to px at build time, fixing UI scaling issues in Shadow DOM content scripts.

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

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

### Install WXT latest version without scripts

Source: https://github.com/wxt-dev/wxt/blob/main/docs/guide/resources/upgrading.md

Install the latest WXT version while skipping scripts to avoid running wxt prepare prematurely, which may throw an error after a major version change.

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

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

### Use import.meta.glob in entrypoint options

Source: https://github.com/wxt-dev/wxt/blob/main/docs/guide/resources/upgrading.md

Vite-specific APIs like import.meta.glob can now be used to define entrypoint options, as shown in this content script example.

```ts
const providers: Record<string, any> = import.meta.glob('../providers/*', {
  eager: true,
});

export default defineContentScript({
  matches: Object.values(providers).flatMap(
    (provider) => provider.default.paths,
  ),
  async main() {
    console.log('Hello content.');
  },
});
```

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

### Create a new project (Bun, PNPM, NPM, Yarn)

Source: https://github.com/wxt-dev/wxt/blob/main/docs/guide/installation.md

Step 1 of setting up from scratch: create a new project directory and initialize it with the package manager of your choice.

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

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

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

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

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

### Bootstrap a new project with npm, pnpm, and bunx

Source: https://github.com/wxt-dev/wxt/blob/main/packages/wxt/README.md

Quick Start commands to initialize a new WXT project. Each command uses a different package manager: npm, pnpm, and bun.

```sh
# npm
npx wxt@latest init

# pnpm
pnpm dlx wxt@latest init

# bun
bunx wxt@latest init
```

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

### Bootstrap project with init command (Bun, PNPM, NPM, Yarn)

Source: https://github.com/wxt-dev/wxt/blob/main/docs/guide/installation.md

Run the init command to bootstrap a new WXT project. Follow the instructions. For Yarn, use NPM initially but select Yarn when prompted.

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

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

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

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

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

### Add entrypoint background.ts

Source: https://github.com/wxt-dev/wxt/blob/main/docs/guide/installation.md

Step 3 of setting up from scratch: create an entrypoint file at my-project/entrypoints/background.ts with a basic background script.

```ts
export default defineBackground(() => {
  console.log('Hello world!');
});
```

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

### Initialize a new vanilla WXT project

Source: https://github.com/wxt-dev/wxt/blob/main/docs/guide/resources/migrate.md

Run this command in your project directory to scaffold a new vanilla WXT project, which you can then merge into your existing codebase file by file.

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

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

### Add Vite Plugin in wxt.config.ts

Source: https://github.com/wxt-dev/wxt/blob/main/docs/guide/essentials/config/vite.md

Install the plugin's NPM package and add it to the plugins array in the vite function. This example adds unplugin-vue-router.

```TypeScript
import { defineConfig } from 'wxt';
import VueRouter from 'unplugin-vue-router/vite';

export default defineConfig({
  vite: () => ({
    plugins: [
      VueRouter({
        /* ... */
      }),
    ],
  }),
});
```

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

### Bootstrap a new project with npx

Source: https://github.com/wxt-dev/wxt/blob/main/README.md

Initializes a new WXT project using npm's npx command. Run this in your terminal to scaffold a new extension project.

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

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

### Add scripts to package.json

Source: https://github.com/wxt-dev/wxt/blob/main/docs/guide/installation.md

Step 4 of setting up from scratch: add the dev, build, zip, and postinstall scripts to your package.json. The lines marked with // [!code ++] are the ones to add.

```json
{
  "scripts": {
    "dev": "wxt", // [!code ++]
    "dev:firefox": "wxt -b firefox", // [!code ++]
    "build": "wxt build", // [!code ++]
    "build:firefox": "wxt build -b firefox", // [!code ++]
    "zip": "wxt zip", // [!code ++]
    "zip:firefox": "wxt zip -b firefox", // [!code ++]
    "postinstall": "wxt prepare" // [!code ++]
  }
}
```

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

### Install @wxt-dev/auto-icons

Source: https://github.com/wxt-dev/wxt/blob/main/packages/auto-icons/README.md

Commands to install the package as a development dependency using various package managers.

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

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

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

Source: https://github.com/wxt-dev/wxt/blob/main/docs/storage.md

Install the @wxt-dev/storage package and import the storage module 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';
```

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

### Install UnoCSS packages

Source: https://github.com/wxt-dev/wxt/blob/main/packages/unocss/README.md

Install the @wxt-dev/unocss and unocss packages as dev dependencies using your preferred package manager.

```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
```

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

### Prepare for profiling

Source: https://github.com/wxt-dev/wxt/blob/main/CONTRIBUTING.md

Builds the latest WXT version and changes to the demo directory for profiling.

```sh
# Build the latest version
bun run --filter wxt build

# CD to the demo directory
cd packages/wxt-demo
```

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

### Install @wxt-dev/browser

Source: https://github.com/wxt-dev/wxt/blob/main/docs/guide/essentials/extension-apis.md

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

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

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

### Install unreleased package from pkg.pr.new

Source: https://github.com/wxt-dev/wxt/blob/main/CONTRIBUTING.md

Install an unreleased version of a package published by pkg.pr.new using the package name and reference.

```sh
npm i https://pkg.pr.new/[package-name]@[ref]
```

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

### Install @wxt-dev/storage package

Source: https://github.com/wxt-dev/wxt/blob/main/packages/storage/README.md

Install the @wxt-dev/storage package when not using WXT. The package can be added with npm, pnpm, yarn, or bun.

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

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

### Open start URLs with 'chromiumArgs' and 'firefoxArgs'

Source: https://github.com/wxt-dev/wxt/blob/main/packages/runner/README.md

Pass URLs as CLI arguments to open them in the browser on startup. Use 'chromiumArgs' for Chrome and 'firefoxArgs' for Firefox.

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

await run({
  extensionDir: 'path/to/extension',
  chromiumArgs: ['https://example.com'],
  firefoxArgs: ['https://example.com'],
});
```

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

### Get Unlisted Script URL at Runtime

Source: https://github.com/wxt-dev/wxt/blob/main/docs/guide/essentials/entrypoints.md

TypeScript code to get the runtime URL of an unlisted script using browser.runtime.getURL(). Logs the URL.

```ts
const url = browser.runtime.getURL('/{name}.js');

console.log(url); // "chrome-extension://{id}/{name}.js"
```

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

### Install @webext-core/isolated-element v1

Source: https://github.com/wxt-dev/wxt/blob/main/docs/guide/resources/upgrading.md

If your styles are broken after the update, you can continue using the full <html> structure by installing v1 of @webext-core/isolated-element. WXT will respect the version listed in your package.json.

```sh
pnpm add @webext-core/isolated-element@^1
```

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

### Recommended folder structure for multiple apps

Source: https://github.com/wxt-dev/wxt/blob/main/docs/guide/essentials/frontend-frameworks.md

Each entrypoint should be a directory with its own index.html, main.tsx, and related files. Shared assets go in the assets folder, and components in the components folder.

```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
```

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

### Get Unlisted Page URL at Runtime

Source: https://github.com/wxt-dev/wxt/blob/main/docs/guide/essentials/entrypoints.md

TypeScript code to get the runtime URL of an unlisted page using browser.runtime.getURL(). Logs the URL and opens it in a new tab.

```ts
const url = browser.runtime.getURL('/{name}.html');

console.log(url); // "chrome-extension://{id}/{name}.html"
window.open(url); // Open the page in a new tab
```

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

### Background entrypoint file patterns

Source: https://github.com/wxt-dev/wxt/blob/main/docs/guide/essentials/entrypoints.md

Illustrates the two valid file patterns for a background entrypoint: a single background.ts file or a background/ directory with an index.ts file.

```html
📂 entrypoints/
   📄 background.ts
```

```html
📂 entrypoints/
   📂 background/
      📄 index.ts
```

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

### Disable WXT runner for manual extension install

Source: https://github.com/wxt-dev/wxt/blob/main/docs/guide/resources/faq.md

Sets `webExt.disabled` to `true` in `wxt.config.ts` to prevent WXT from opening the browser, allowing manual installation in a regular Chrome profile.

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

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

### Show upgrade-deps script options

Source: https://github.com/wxt-dev/wxt/blob/main/CONTRIBUTING.md

Display all available options for the dependency upgrade script.

```sh
bun run scripts/upgrade-deps.ts --help
```

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

### Example debug output from @wxt-dev/runner

Source: https://github.com/wxt-dev/wxt/blob/main/packages/runner/README.md

Example output generated when the DEBUG env var is set to "@wxt-dev/runner". It shows resolved options, browser spawn commands, and CDP communication messages.

```plaintext
@wxt-dev/runner:options User options: { extensionDir: 'demo-extension', target: undefined }
@wxt-dev/runner:options Resolved options: {
  browserBinary: '/usr/bin/chromium',
  chromiumArgs: [
    '--disable-features=Translate,OptimizationHints,MediaRouter,DialMediaRouteProvider,CalculateNativeWinOcclusion,InterestFeedContentSuggestions,CertificateTransparencyComponentUpdater,AutofillServerCommunication,PrivacySandboxSettings4',
    '--disable-component-extensions-with-background-pages',
    '--disable-background-networking',
    '--disable-component-update',
    '--disable-client-side-phishing-detection',
    '--disable-sync',
    '--metrics-recording-only',
    '--disable-default-apps',
    '--no-default-browser-check',
    '--no-first-run',
    '--disable-background-timer-throttling',
    '--disable-ipc-flooding-protection',
    '--password-store=basic',
    '--use-mock-keychain',
    '--force-fieldtrials=*BackgroundTracing/default/',
    '--disable-hang-monitor',
    '--disable-prompt-on-repost',
    '--disable-domain-reliability',
    '--propagate-iph-for-testing',
    '--remote-debugging-port=0',
    '--remote-debugging-pipe',
    '--user-data-dir=/tmp/wxt-runner-pWXLO1',
    '--enable-unsafe-extension-debugging'
  ],
  dataDir: '/tmp/wxt-runner-pWXLO1',
  dataPersistence: 'none',
  chromiumRemoteDebuggingPort: 0,
  extensionDir: '/home/aklinker1/Development/github.com/wxt-dev/wxt/packages/runner/demo-extension',
  firefoxArgs: [
    '--new-instance',
    '--no-remote',
    '--profile',
    '/tmp/wxt-runner-pWXLO1',
    '--remote-debugging-port=0',
    'about:debugging#/runtime/this-firefox'
  ],
  firefoxRemoteDebuggingPort: 0,
  target: 'chrome'
}
@wxt-dev/runner:chrome:stderr DevTools listening on ws://127.0.0.1:38397/devtools/browser/93dc4de5-64cb-4e0b-a9d3-7549527015f0
@wxt-dev/runner:cdp Sending command: {
  id: 1,
  method: 'Extensions.loadUnpacked',
  params: {
    path: '/home/aklinker1/Development/github.com/wxt-dev/wxt/packages/runner/demo-extension'
  }
}
@wxt-dev/runner:cdp Received response: { id: 1, result: { id: 'hckhakegenefhikcfkaa' } }
```

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

### Get translation with browser.i18n.getMessage

Source: https://github.com/wxt-dev/wxt/blob/main/docs/guide/essentials/i18n.md

Retrieves the translation for the 'helloWorld' key.

```ts
browser.i18n.getMessage('helloWorld');
```
Tokens:
Raw