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:

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
• Constructors
  • new ContentScriptContext(contentScriptName, options)
• Properties
  • abortController
  • contentScriptName
  • isTopFrame
  • locationWatcher
  • options
  • SCRIPT_STARTED_MESSAGE_TYPE
• Accessors
  • isInvalid
  • isValid
  • signal
• Methods
  • abort()
  • addEventListener()
  • block()
  • listenForNewerScripts()
  • notifyInvalidated()
  • onInvalidated()
  • requestAnimationFrame()
  • requestIdleCallback()
  • setInterval()
  • setTimeout()
  • stopOldScripts()

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:46

Properties

abortController

private abortController: AbortController

Source

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

---

contentScriptName

private readonly contentScriptName: string

Source

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

---

isTopFrame

private isTopFrame: boolean

Source

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

---

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:44

---

options

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

Source

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

---

SCRIPT_STARTED_MESSAGE_TYPE

private static SCRIPT_STARTED_MESSAGE_TYPE: string

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:68

---

isValid

get isValid(): boolean

Source

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

---

signal

get signal(): AbortSignal

Source

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

Methods

abort()

abort(reason?): void

Parameters

▪ reason?: any

Implementation of

AbortController.abort

Source

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

---

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

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

Source

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

---

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

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

  // ...
}

Source

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

---

listenForNewerScripts()

listenForNewerScripts(options?): void

Parameters

▪ options?: object

▪ options.ignoreFirstEvent?: boolean

Source

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

---

notifyInvalidated()

notifyInvalidated(): void

Abort the abort controller and execute all onInvalidated listeners.

Source

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

---

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

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:92

Example

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:92

---

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:140

---

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:153

---

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:117

---

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:128

---

stopOldScripts()

stopOldScripts(): void

Source

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

---

Generated using typedoc-plugin-markdown and TypeDoc