WXT

Appearance

API / wxt/utils/content-script-context / ContentScriptContext

Class: ContentScriptContext ​

Source: packages/wxt/src/utils/content-script-context.ts:45

Implements AbortController. Used to detect and stop content script code when the script is invalidated.

It also provides several utilities like ctx.setTimeout and ctx.setInterval that should be used in content scripts instead of window.setTimeout or window.setInterval.

To create context for testing, you can use the class's constructor:

ts
import { ContentScriptContext } from 'wxt/utils/content-scripts-context';

test('storage listener should be removed when context is invalidated', () => {
  const ctx = new ContentScriptContext('test');
  const item = storage.defineItem('local:count', { defaultValue: 0 });
  const watcher = vi.fn();

  const unwatch = item.watch(watcher);
  ctx.onInvalidated(unwatch); // Listen for invalidate here

  await item.setValue(1);
  expect(watcher).toBeCalledTimes(1);
  expect(watcher).toBeCalledWith(1, 0);

  ctx.notifyInvalidated(); // Use this function to invalidate the context
  await item.setValue(2);
  expect(watcher).toBeCalledTimes(1);
});

Contents ​

Implements ​

  • AbortController

Constructors ​

Constructor ​

new ContentScriptContext(contentScriptName, options?): ContentScriptContext

Source: packages/wxt/src/utils/content-script-context.ts:54

Parameters ​

contentScriptName ​

string

options? ​

Omit<ContentScriptDefinition, "main">

Returns ​

ContentScriptContext

Properties ​

options? ​

readonly optional options?: Omit<ContentScriptDefinition, "main">

Source: packages/wxt/src/utils/content-script-context.ts:56

Accessors ​

isInvalid ​

Get Signature ​

get isInvalid(): boolean

Source: packages/wxt/src/utils/content-script-context.ts:73

Returns ​

boolean

isValid ​

Get Signature ​

get isValid(): boolean

Source: packages/wxt/src/utils/content-script-context.ts:80

Returns ​

boolean

signal ​

Get Signature ​

get signal(): AbortSignal

Source: packages/wxt/src/utils/content-script-context.ts:65

The signal read-only property of the AbortController interface returns an AbortSignal object instance, which can be used to communicate with/abort an asynchronous operation as desired.

MDN Reference

Returns ​

AbortSignal

Implementation of ​

AbortController.signal

Methods ​

abort() ​

abort(reason?): void

Source: packages/wxt/src/utils/content-script-context.ts:69

The abort() method of the AbortController interface aborts an asynchronous operation before it has completed. This is able to abort fetch requests, the consumption of any response bodies, or streams.

MDN Reference

Parameters ​

reason? ​

any

Returns ​

void

Implementation of ​

AbortController.abort

addEventListener() ​

Call Signature ​

addEventListener<TType>(target, type, handler, options?): void

Source: packages/wxt/src/utils/content-script-context.ts:205

Call target.addEventListener and remove the event listener when the context is invalidated.

Listeners can be canceled by calling the normal removeEventListener function.

Includes additional events useful for content scripts:

  • "wxt:locationchange" - Triggered when HTML5 history mode is used to change URL. Content scripts are not reloaded when navigating this way, so this can be used to reset the content script state on URL change, or run custom code.
Type Parameters ​
TType ​

TType extends keyof WxtWindowEventMap

Parameters ​
target ​

Window

type ​

TType

handler ​

(event) => void

options? ​

AddEventListenerOptions

Returns ​

void

Example ​
ts
ctx.addEventListener(document, 'visibilitychange', () => {
    // ...
  });
  ctx.addEventListener(window, 'wxt:locationchange', () => {
    // ...
  });

Call Signature ​

addEventListener<TType>(target, type, handler, options?): void

Source: packages/wxt/src/utils/content-script-context.ts:211

Call target.addEventListener and remove the event listener when the context is invalidated.

Listeners can be canceled by calling the normal removeEventListener function.

Includes additional events useful for content scripts:

  • "wxt:locationchange" - Triggered when HTML5 history mode is used to change URL. Content scripts are not reloaded when navigating this way, so this can be used to reset the content script state on URL change, or run custom code.
Type Parameters ​
TType ​

TType extends keyof DocumentEventMap

Parameters ​
target ​

Document

type ​

TType

handler ​

(event) => void

options? ​

AddEventListenerOptions

Returns ​

void

Example ​
ts
ctx.addEventListener(document, 'visibilitychange', () => {
    // ...
  });
  ctx.addEventListener(window, 'wxt:locationchange', () => {
    // ...
  });

Call Signature ​

addEventListener<TTarget>(target, ...params): void

Source: packages/wxt/src/utils/content-script-context.ts:217

Call target.addEventListener and remove the event listener when the context is invalidated.

Listeners can be canceled by calling the normal removeEventListener function.

Includes additional events useful for content scripts:

  • "wxt:locationchange" - Triggered when HTML5 history mode is used to change URL. Content scripts are not reloaded when navigating this way, so this can be used to reset the content script state on URL change, or run custom code.
Type Parameters ​
TTarget ​

TTarget extends EventTarget

Parameters ​
target ​

TTarget

params ​

...Parameters<TTarget["addEventListener"]>

Returns ​

void

Example ​
ts
ctx.addEventListener(document, 'visibilitychange', () => {
    // ...
  });
  ctx.addEventListener(window, 'wxt:locationchange', () => {
    // ...
  });

block() ​

block<T>(): Promise<T>

Source: packages/wxt/src/utils/content-script-context.ts:114

Return a promise that never resolves. Useful if you have an async function that shouldn't run after the context is expired.

Type Parameters ​

T ​

T

Returns ​

Promise<T>

Example ​

ts
const getValueFromStorage = async () => {
    if (ctx.isInvalid) return ctx.block();

    // ...
  };

listenForNewerScripts() ​

listenForNewerScripts(): void

Source: packages/wxt/src/utils/content-script-context.ts:285

Returns ​

void

notifyInvalidated() ​

notifyInvalidated(): void

Source: packages/wxt/src/utils/content-script-context.ts:246

Internal

Abort the abort controller and execute all onInvalidated listeners.

Returns ​

void

onInvalidated() ​

onInvalidated(cb): () => void

Source: packages/wxt/src/utils/content-script-context.ts:98

Add a listener that is called when the content script's context is invalidated.

Parameters ​

cb ​

() => void

Returns ​

A function to remove the listener.

() => void

Example ​

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

requestAnimationFrame() ​

requestAnimationFrame(callback): number

Source: packages/wxt/src/utils/content-script-context.ts:155

Wrapper around window.requestAnimationFrame that automatically cancels the request when invalidated.

Callbacks can be canceled by calling the normal cancelAnimationFrame function.

Parameters ​

callback ​

FrameRequestCallback

Returns ​

number

requestIdleCallback() ​

requestIdleCallback(callback, options?): number

Source: packages/wxt/src/utils/content-script-context.ts:171

Wrapper around window.requestIdleCallback that automatically cancels the request when invalidated.

Callbacks can be canceled by calling the normal cancelIdleCallback function.

Parameters ​

callback ​

IdleRequestCallback

options? ​

IdleRequestOptions

Returns ​

number

setInterval() ​

setInterval(handler, timeout?): number

Source: packages/wxt/src/utils/content-script-context.ts:126

Wrapper around window.setInterval that automatically clears the interval when invalidated.

Intervals can be cleared by calling the normal clearInterval function.

Parameters ​

handler ​

() => void

timeout? ​

number

Returns ​

number

setTimeout() ​

setTimeout(handler, timeout?): number

Source: packages/wxt/src/utils/content-script-context.ts:140

Wrapper around window.setTimeout that automatically clears the interval when invalidated.

Timeouts can be cleared by calling the normal setTimeout function.

Parameters ​

handler ​

() => void

timeout? ​

number

Returns ​

number

stopOldScripts() ​

stopOldScripts(): void

Source: packages/wxt/src/utils/content-script-context.ts:253

Returns ​

void

verifyScriptStartedEvent() ​

verifyScriptStartedEvent(event): boolean

Source: packages/wxt/src/utils/content-script-context.ts:277

Parameters ​

event ​

CustomEvent

Returns ​

boolean

Generated using typedoc-plugin-markdown and TypeDoc