wxt/docs/guide/background.md

Background

Chrome Docs • Firefox Docs

For MV2, the background is added as a script to the background page. For MV3, the background becomes a service worker.

Filenames

entrypoints/background.ts is the only recoginzed filename for the background script.

Definition

:::warning The main function of the background CANNOT BE ASYNC. Event listeners must be added syncronously on background startup. If your main function returns a promise, WXT will log an error. :::

export default defineBackground(() => {
  // Executed when background is loaded
});

or

export default defineBackground({
  // Set manifest options
  persistent: undefined | true | false,
  type: undefined | 'module',

  // Executed when background is loaded
  main() {
    // ...
  },
});

All manifest options default to undefined.