Skip to content

runtime.md

Latest commit

 

History

History
385 lines (252 loc) · 8.11 KB

runtime.md

File metadata and controls

385 lines (252 loc) · 8.11 KB
Raw

runtime

Documentation: Chrome Runtime API

A wrapper for the Chrome runtime API, including messaging, updates, and lifecycle events.

Methods

Events

isAvailableRuntime

isAvailableRuntime(): boolean

Returns true when the runtime namespace is present on the API selected by browser() in the current context. Returns false if the namespace or WebExtension environment is absent, or if accessing it throws. The check is synchronous, does not log, and reads the current API on every call without caching. It checks namespace presence only; it does not guarantee individual methods, permissions, or a successful operation.

import {isAvailableRuntime} from "@addon-core/browser";

if (isAvailableRuntime()) {
    // The namespace is present; handle operation-specific failures when using it.
}

connect

connect(extensionId: string, connectInfo?: object): chrome.runtime.Port

Opens a long-lived connection to another extension or app.

connectNative

connectNative(application: string): chrome.runtime.Port

Connects to a native application.

getContexts [MV3]

getContexts(filter: chrome.runtime.ContextFilter): Promise<chrome.runtime.ExtensionContext[]>

Retrieves extension contexts matching the filter (Manifest V3 only).

getManifest

getManifest(): chrome.runtime.Manifest

Returns the extension's manifest details.

getId

getId(): string

Returns the extension ID.

getManifestVersion

getManifestVersion(): 2 | 3

Retrieves the manifest version (2 or 3).

isManifestVersion3

isManifestVersion3(): boolean

Returns true only when Manifest V3 is confirmed. Returns false for other versions, unavailable APIs, or failures reading the manifest, without throwing or logging. Reads the manifest on every call. Use getManifestVersion() when the exact version is required and lookup errors must propagate.

getPackageDirectoryEntry

getPackageDirectoryEntry(): Promise<FileSystemDirectoryEntry>

Gets the root directory of the extension package.

getPlatformInfo

getPlatformInfo(): Promise<chrome.runtime.PlatformInfo>

Returns information about the current platform.

getBrowserInfo [Firefox]

getBrowserInfo(): Promise<{ name: string; vendor: string; version: string; buildID: string; }>

Returns information about the browser. Available only in Firefox.

getUrl

getUrl(path: string): string

Converts a relative path to an absolute extension URL.

openOptionsPage

openOptionsPage(): Promise<void>

Opens the extension's options page.

reload

reload(): void

Reloads the extension.

requestUpdateCheck

requestUpdateCheck(): Promise<{ status: chrome.runtime.RequestUpdateCheckStatus; details?: chrome.runtime.UpdateCheckDetails; }>

Checks for an update and returns status and details.

restart [MV3]

restart(): void

Restarts the browser to apply updates (Manifest V3 only).

restartAfterDelay [MV3]

restartAfterDelay(seconds: number): Promise<void>

Schedules a browser restart after the given delay in seconds (Manifest V3 only).

sendMessage

sendMessage<M = any, R = any>(message: M): Promise<R>

Sends a single message to the extension or app and awaits a response.

setUninstallUrl

setUninstallUrl(url: string): Promise<void>

Sets a URL to be opened upon uninstallation.

onConnect

onConnect(callback: (port: chrome.runtime.Port) => void): () => void

Fires when a connection is made by another extension or content script. Returns an unsubscribe function.

onConnectExternal

onConnectExternal(callback: (port: chrome.runtime.Port) => void): () => void

Fires when an external extension connects. Returns an unsubscribe function.

onInstalled

onInstalled(callback: (details: chrome.runtime.InstalledDetails) => void): () => void

Fires when the extension is installed or updated. Returns an unsubscribe function.

onMessage

onMessage(
  callback: (
    message: any,
    sender: chrome.runtime.MessageSender,
    sendResponse: (response?: any) => void
  ) => void
): () => void

Fires when a message is sent to the extension. Returns an unsubscribe function.

onMessageExternal

onMessageExternal(
  callback: (
    message: any,
    sender: chrome.runtime.MessageSender,
    sendResponse: (response?: any) => void
  ) => void
): () => void

Fires when a message is sent from another extension. Returns an unsubscribe function.

onRestartRequired

onRestartRequired(callback: (reason: chrome.runtime.OnRestartRequiredReason) => void): () => void

Fires when a restart is required (e.g., after an OS or app update). Returns an unsubscribe function.

onStartup

onStartup(callback: () => void): () => void

Fires when the browser starts up. Returns an unsubscribe function.

onSuspend

onSuspend(callback: () => void): () => void

Fires when the extension is being suspended. Returns an unsubscribe function.

onSuspendCanceled

onSuspendCanceled(callback: () => void): () => void

Fires when a previously dispatched onSuspend event is canceled. Returns an unsubscribe function.

onUpdateAvailable

onUpdateAvailable(callback: (details: chrome.runtime.UpdateAvailableDetails) => void): () => void

Fires when an update is available. Returns an unsubscribe function.

onUserScriptConnect

onUserScriptConnect(callback: (port: chrome.runtime.Port) => void): () => void

Fires when a user script establishes a connection. Returns an unsubscribe function.

onUserScriptMessage

onUserScriptMessage(
  callback: (
    message: any,
    sender: chrome.runtime.MessageSender,
    sendResponse: (response?: any) => void
  ) => void
): () => void

Fires when a message arrives from a user script. Returns an unsubscribe function.