Skip to content

API > wxt/client > ContentScriptContext

Class: ContentScriptContext

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/client';

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

new ContentScriptContext(contentScriptName, options)

new ContentScriptContext(contentScriptName, options?): ContentScriptContext

Parameters

contentScriptName: string

options?: Omit<ContentScriptDefinition, "main">

Source

src/client/content-scripts/content-script-context.ts:44

Properties

options

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

Source

src/client/content-scripts/content-script-context.ts:46

Accessors

isInvalid

get isInvalid(): boolean

Source

src/client/content-scripts/content-script-context.ts:66


isValid

get isValid(): boolean

Source

src/client/content-scripts/content-script-context.ts:73


signal

get signal(): AbortSignal

Source

src/client/content-scripts/content-script-context.ts:58

Methods

abort()

abort(reason?): void

Parameters

reason?: any

Implementation of

AbortController.abort

Source

src/client/content-scripts/content-script-context.ts:62


addEventListener()

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

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

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 extends EventTarget

TType extends keyof WxtContentScriptEventMap

Parameters

target: TTarget

type: TType

handler: (event) => void

options?: AddEventListenerOptions

Returns

Example

ts
ctx.addEventListener(document, "visibilitychange", () => {
  // ...
});
ctx.addEventListener(document, "wxt:locationchange", () => {
  // ...
});

Source

src/client/content-scripts/content-script-context.ts:180


block()

block<T>(): Promise<T>

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

Returns

Example

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

  // ...
}

Source

src/client/content-scripts/content-script-context.ts:106


onInvalidated()

onInvalidated(cb): () => void

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

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

Returns

A function to remove the listener.

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

src/client/content-scripts/content-script-context.ts:90

Example

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

Source

src/client/content-scripts/content-script-context.ts:90


requestAnimationFrame()

requestAnimationFrame(callback): number

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

Parameters

callback: FrameRequestCallback

Source

src/client/content-scripts/content-script-context.ts:138


requestIdleCallback()

requestIdleCallback(callback, options?): number

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

Parameters

callback: IdleRequestCallback

options?: IdleRequestOptions

Source

src/client/content-scripts/content-script-context.ts:151


setInterval()

setInterval(handler, timeout?): number

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

Parameters

handler: () => void

timeout?: number

Source

src/client/content-scripts/content-script-context.ts:115


setTimeout()

setTimeout(handler, timeout?): number

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

Parameters

handler: () => void

timeout?: number

Source

src/client/content-scripts/content-script-context.ts:126


Generated using typedoc-plugin-markdown and TypeDoc