index.md

---

title: runtime.connect()
slug: Mozilla/Add-ons/WebExtensions/API/runtime/connect
page-type: webextension-api-function
tags:
  - API
  - Add-ons
  - Extensions
  - Method
  - Non-standard
  - Reference
  - WebExtensions
  - connect
  - runtime
browser-compat: webextensions.api.runtime.connect

---

{{AddonSidebar()}}

Make a connection between different contexts inside the extension.

You can call this:

• in an extension's content scripts, to establish a connection with the extension's background scripts (or similarly privileged scripts, like popup scripts or options page scripts).

• in an extension's background scripts (or similarly privileged scripts), to establish a connection with a different extension.

Note that you can't use this function to connect an extension to its content scripts. To do this, use {{WebExtAPIRef('tabs.connect()')}}.

By default, this connection enables the extension to exchange messages with itself or any other extension (if extensionId is specified). However, the externally_connectable manifest key can be used to limit communication to specific extensions and enable communication with websites. Connections within the extension trigger the {{WebExtAPIRef('runtime.onConnect')}} event, connections from other extensions or web pages trigger the {{WebExtAPIRef('runtime.onConnectExternal')}} event.

Syntax

let port = browser.runtime.connect(
  extensionId, // optional string
  connectInfo  // optional object
)

Parameters

• extensionId {{optional_inline}}

  • : string. The ID of the extension to connect to. If the target has set an ID explicitly using the browser_specific_settings key in manifest.json, then extensionId should have that value. Otherwise it should have the ID that was generated for the target.

• connectInfo {{optional_inline}}

  • : object. Details of the connection:

    • name {{optional_inline}}

      • : string. Will be passed into {{WebExtAPIRef("runtime.onConnect")}} for processes that are listening for the connection event.

    • includeTlsChannelId {{optional_inline}}

      • : boolean. Whether the TLS channel ID will be passed into {{WebExtAPIRef("runtime.onConnectExternal")}} for processes that are listening for the connection event.

Return value

{{WebExtAPIRef('runtime.Port')}}. Port through which messages can be sent and received. The port's onDisconnect event is fired if the extension does not exist.

Browser compatibility

{{Compat}}

Examples

This content script:

• connects to the background script and stores the Port in a variable called myPort.

• listens for messages on myPort and logs them.

• sends messages to the background script, using myPort, when the user clicks the document.

// content-script.js

let myPort = browser.runtime.connect({name:"port-from-cs"});
myPort.postMessage({greeting: "hello from content script"});

myPort.onMessage.addListener((m) => {
  console.log("In content script, received message from background script: ");
  console.log(m.greeting);
});

document.body.addEventListener("click", () => {
  myPort.postMessage({greeting: "they clicked the page!"});
});

The corresponding background script:

• listens for connection attempts from the content script.

• when it receives a connection attempt:

  • stores the port in a variable named portFromCS.

  • sends the content script a message using the port.

  • starts listening to messages received on the port, and logs them.

• sends messages to the content script, using portFromCS, when the user clicks the extension's browser action.

// background-script.js

let portFromCS;

function connected(p) {
  portFromCS = p;
  portFromCS.postMessage({greeting: "hi there content script!"});
  portFromCS.onMessage.addListener((m) => {
    console.log("In background script, received message from content script")
    console.log(m.greeting);
  });
}

browser.runtime.onConnect.addListener(connected);

browser.browserAction.onClicked.addListener(() => {
  portFromCS.postMessage({greeting: "they clicked the button!"});
});

{{WebExtExamples}}

Note: This API is based on Chromium's chrome.runtime API. This documentation is derived from runtime.json in the Chromium code.