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

Input Pattern		Output Path
entrypoints/background.[jt]s		/background.js
entrypoints/background/index.[jt]s		/background.js

Definition

WARNING

The main function of the background CANNOT BE ASYNC. Event listeners must be added synchronously 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',

  // Set include/exclude if the background should be removed from some builds
  include: undefined | string[],
  exclude: undefined | string[],

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

All manifest options default to undefined.