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

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

Properties

#abortController

private #abortController: AbortController

Source

packages/wxt/src/client/content-scripts/content-script-context.ts:41


#isTopFrame

private #isTopFrame: boolean

Source

packages/wxt/src/client/content-scripts/content-script-context.ts:40


#locationWatcher

private #locationWatcher: object

Type declaration

run()

Ensure the location watcher is actively looking for URL changes. If it's already watching, this is a noop.

Source

packages/wxt/src/client/content-scripts/content-script-context.ts:42


contentScriptName

private readonly contentScriptName: string

Source

packages/wxt/src/client/content-scripts/content-script-context.ts:45


options

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

Source

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


SCRIPT_STARTED_MESSAGE_TYPE

private static SCRIPT_STARTED_MESSAGE_TYPE: string = 'wxt:content-script-started'

Source

packages/wxt/src/client/content-scripts/content-script-context.ts:38

Accessors

isInvalid

get isInvalid(): boolean

Source

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


isValid

get isValid(): boolean

Source

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


signal

get signal(): AbortSignal

Source

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

Methods

#listenForNewerScripts()

private #listenForNewerScripts(options?): void

Parameters

options?: object

options.ignoreFirstEvent?: boolean

Source

packages/wxt/src/client/content-scripts/content-script-context.ts:227


#stopOldScripts()

private #stopOldScripts(): void

Source

packages/wxt/src/client/content-scripts/content-script-context.ts:216


abort()

abort(reason?): void

Parameters

reason?: any

Implementation of

AbortController.abort

Source

packages/wxt/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

packages/wxt/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

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


notifyInvalidated()

notifyInvalidated(): void

Abort the abort controller and execute all onInvalidated listeners.

Source

packages/wxt/src/client/content-scripts/content-script-context.ts:209


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

packages/wxt/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

packages/wxt/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

packages/wxt/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

packages/wxt/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

packages/wxt/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

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


Generated using typedoc-plugin-markdown and TypeDoc