{"id":16206925,"url":"https://github.com/asimen1/ext-messenger","last_synced_at":"2025-03-16T11:30:33.356Z","repository":{"id":58243954,"uuid":"145661083","full_name":"asimen1/ext-messenger","owner":"asimen1","description":"📫 Extension message passing made easy","archived":false,"fork":false,"pushed_at":"2024-09-09T05:50:03.000Z","size":91,"stargazers_count":17,"open_issues_count":4,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-16T01:41:21.769Z","etag":null,"topics":["chrome-extension","message-passing","messages","messenger"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/ext-messenger","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/asimen1.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-08-22T05:37:13.000Z","updated_at":"2025-03-11T19:54:44.000Z","dependencies_parsed_at":"2022-08-31T00:40:32.789Z","dependency_job_id":null,"html_url":"https://github.com/asimen1/ext-messenger","commit_stats":null,"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asimen1%2Fext-messenger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asimen1%2Fext-messenger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asimen1%2Fext-messenger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asimen1%2Fext-messenger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/asimen1","download_url":"https://codeload.github.com/asimen1/ext-messenger/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243862297,"owners_count":20360118,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chrome-extension","message-passing","messages","messenger"],"created_at":"2024-10-10T10:08:54.571Z","updated_at":"2025-03-16T11:30:32.850Z","avatar_url":"https://github.com/asimen1.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"## Browser Extension message passing made easy\n\n[![Latest Stable Version](https://img.shields.io/npm/v/ext-messenger.svg)](https://www.npmjs.com/package/ext-messenger)\n[![NPM Downloads](https://img.shields.io/npm/dt/ext-messenger.svg)](https://www.npmjs.com/package/ext-messenger)\n\n### What?\n\nSmall library for messaging across any browser extension parts (background, content script, popup or devtool).\n\nIt has a simple API, promise based callback support and more.\n\nSupports extensions for `Chrome` and any Chromium based browser extensions like `Edge`, `Arc`, ...\n\n### Why?\n\nSending messages between extension parts can get complicated and usually requires some relaying mechanism in the background page. Adding callback functionality to these messages can make it even trickier.\n\nFurthermore, the messaging API is not coherent or straight forward, sometimes requiring you to use `runtime.*` API and sometimes `tabs.*` API depending on which extension part you are currently in.\n\n### How?\n\n```shell\nnpm i ext-messenger\n```\n\nOR\n\n```shell\nyarn add ext-messenger\n```\n\n#### 1) In the background page: create a messenger instance and init the background hub\n\n```javascript\nconst Messenger = require('ext-messenger');\nlet messenger = new Messenger(Messenger.EXT_PARTS.BACKGROUND);\n\nmessenger.initBackgroundHub();\n```\n\n\u003e This step is **obligatory** and should be done as soon as possible in your background page.\n\n\\* You can also add the [library](https://github.com/asimen1/ext-messenger/tree/master/dist) via script tag and use `window['ext-messenger']`.\n\n#### 2) Init connections (in any extension parts)\n\n```javascript\nconst Messenger = require('ext-messenger');\nlet messenger = new Messenger(Messenger.EXT_PARTS.CONTENT_SCRIPT);\n\n/*\n * {string} name - Identifier name for this connection.\n * {function} messageHandler - Handler for incoming messages.\n */\nmessenger.initConnection(name, messageHandler);\n```\n\nThis returns a **connection** object.\n\n#### 3) Start sending messages across connections (in any extension parts)\n\n```javascript\n/*\n * {string} to - '\u003cextension part\u003e:\u003cconnection name\u003e'.\n * {*} message - The message to send (any JSON-ifiable object).\n */\nconnection.sendMessage(to, message);\n```\n\n* `\u003cextension part\u003e` possible values: `background`, `content_script`, `popup`, `devtool`.\n* Sending messages from background require an additional tab id argument `:\u003ctab id\u003e`.\n\nReturns a `Promise`:\n\n* The promise will be resolved if the receiver invoked the `sendResponse` method argument (see example below).\n* The promise will be rejected if the connection has been disconnected via the `disconnect()` API.\n\n#### More\n\n```javascript\n// Init hub with handlers notifying someone connected/disconnected.\nmessenger.initBackgroundHub({\n    connectedHandler: function(extensionPart, connectionName, tabId) {},\n    disconnectedHandler: function(extensionPart, connectionName, tabId) {}\n});\n\n// Sending to multiple connections is supported via:\n// 'extension part:name1,name2,...'.\nc.sendMessage('content_script:main,main2', { text: 'HI!' });\n\n// Sending to all connections is supported using wildcard value '*'.\nc.sendMessage('devtool:*', { text: 'HI!' });\n\n// Disconnect the connection to stop listening for messages.\nc.disconnect();\n```\n\n\u003e When sending a message to multiple extension names (e.g. \"name1,name2\" or \"*\"), the returned promise will be resolved by the first connection that sends a response.\n\n### Example\n\n```javascript\n/* ---------------------------------------------- */\n/* Init connections in desired extension part:    */\n/* BACKGROUND, CONTENT_SCRIPT, POPUP, DEVTOOL     */\n/* ---------------------------------------------- */\nconst Messenger = require('ext-messenger');\nlet messenger = new Messenger(Messenger.EXT_PARTS.BACKGROUND);\n\nlet messageHandler = function(msg, from, sender, sendResponse) {\n    if (msg.text === 'HI!') {\n        sendResponse('HOWDY!');\n    }\n};\n\nlet c = messenger.initConnection('main', messageHandler);\nlet c2 = messenger.initConnection('main2', messageHandler);\n...\n\nlet msg = { text: 'HI!' };\n\n/* ------------------------------------------------------ */\n/* Send message to content script                         */\n/* ------------------------------------------------------ */\nc.sendMessage('content_script:main', msg);\n\n/* ------------------------------------------------------ */\n/* Send message to popup (with response)                  */\n/* ------------------------------------------------------ */\nc.sendMessage('popup:main2', msg).then((response) =\u003e {\n    console.log(response);\n});\n\n/* ------------------------------------------------------ */\n/* Send message to background (with response)             */\n/* ------------------------------------------------------ */\nc.sendMessage('background:main', msg).then((response) =\u003e {\n    console.log(response);\n});\n\n/* ------------------------------------------------------ */\n/* Send message from background to devtool.               */\n/* '50' is an example tab id of the devtool.              */\n/* ------------------------------------------------------ */\nc.sendMessage('devtool:main:50', msg).then((response) =\u003e {\n    console.log(response);\n});\n```\n\n### Notes\n\n* Requires your extension to have [\"tabs\" permission](https://developer.chrome.com/extensions/declare_permissions).\n* Uses only long lived port connections via `runtime.*` API.\n* This library should satisfy all your message passing needs, however if you are still handling some port connections manually, using `runtime.onConnect` will also receive messenger ports connections. In order to identify connections originating from this library you can use the static method `Messenger.isMessengerPort(port)` which will return true/false.\n* The Messenger `messageHandler` and `runtime.onMessage` similarities and differences:\n  * **Same** - `sender` object.\n  * **Same** - `sendResponse` - The argument should be any JSON-ifiable object.\n  * **Same** - `sendResponse` - With multiple message handler, the `sendResponse()` will work only for the first one to respond.\n  * **Different** - `from` object indicating the senders formatted identifier e.g. `devtool:connection name`.\n  * **Different** - Async `sendResponse` is supported directly (no need to return `true` value like with `runtime.onMessage`).\n* This library should probably also work for `Firefox` extensions but have never been tested.\n* This library is compatible with manifest V3 (if you are looking for a manifest V2 compatible version, you can use version [^3.0.2](https://www.npmjs.com/package/ext-messenger/v/3.0.2)).\n\n### Extensions using messenger\n\n* [Restyler](https://chrome.google.com/webstore/detail/restyler/ofkkcnbmhaodoaehikkibjanliaeffel)\n\n* Working on one? let me know ext.messenger@gmail.com! [![](https://asimen1.github.io/ext-messenger/images/mailicon.png \"email\")](mailto:ext.messenger@gmail.com)\n\n### Developing Locally\n\n```shell\nnpm install\nnpm run dev\n```\n\nYou can now use the built messenger from the `dist` folder in a local test extension (or use [npm link](https://docs.npmjs.com/cli/link)).\n\nI have created one (for internal testing purposes) that you can use: [ext-messenger-test](https://github.com/asimen1/ext-messenger-test).\n\n### License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fasimen1%2Fext-messenger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fasimen1%2Fext-messenger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fasimen1%2Fext-messenger/lists"}