{"id":21258856,"url":"https://github.com/spacebro/spacebro-client","last_synced_at":"2025-07-11T02:32:56.723Z","repository":{"id":57366816,"uuid":"49010599","full_name":"spacebro/spacebro-client","owner":"spacebro","description":"🌟 Easily share event between application.","archived":false,"fork":false,"pushed_at":"2018-12-12T09:50:43.000Z","size":1464,"stargazers_count":5,"open_issues_count":9,"forks_count":2,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-07-07T10:16:31.425Z","etag":null,"topics":["realtime","socket-io","spacebro","websocket"],"latest_commit_sha":null,"homepage":"http://spacebro.space","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/spacebro.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2016-01-04T16:59:41.000Z","updated_at":"2022-12-11T09:38:49.000Z","dependencies_parsed_at":"2022-08-23T19:50:15.707Z","dependency_job_id":null,"html_url":"https://github.com/spacebro/spacebro-client","commit_stats":null,"previous_names":[],"tags_count":28,"template":false,"template_full_name":null,"purl":"pkg:github/spacebro/spacebro-client","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spacebro%2Fspacebro-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spacebro%2Fspacebro-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spacebro%2Fspacebro-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spacebro%2Fspacebro-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/spacebro","download_url":"https://codeload.github.com/spacebro/spacebro-client/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spacebro%2Fspacebro-client/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264712910,"owners_count":23652686,"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":["realtime","socket-io","spacebro","websocket"],"created_at":"2024-11-21T04:11:11.727Z","updated_at":"2025-07-11T02:32:56.293Z","avatar_url":"https://github.com/spacebro.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# spacebro client\n\n🌟 Connect easily to a [spacebro server](https://github.com/spacebro/spacebro).\n\n[![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg)](http://standardjs.com/) [![node](https://img.shields.io/badge/node-4.0.x-brightgreen.svg)](https://nodejs.org/en/) [![node](https://img.shields.io/badge/node-5.3.x-brightgreen.svg)](https://nodejs.org/en/) [![node](https://img.shields.io/badge/node-6.x.x-brightgreen.svg)](https://nodejs.org/en/)\n\n## 🌍 Installation\n\n```bash\nyarn add spacebro-client\n# or\nnpm i -S spacebro-client\n```\n\n## 👋 Usage\n\nFirst, you need to start a [spacebro server](https://github.com/soixantecircuits/spacebro).\n\n```bash\n$ npm i -g spacebro # or yarn global add spacebro\n$ spacebro\n```\n\nThen, write the following client code:\n\n```js\nconst { SpacebroClient } = require('spacebro-client')\n\nconst client = new SpacebroClient({\n  host: '127.0.0.1',\n  port: 36000,\n  channelName: 'bar',\n  client: {\n    name: 'foo',\n    description: \"a foo tool\",\n    in: {\n      inFoo: {\n        eventName: \"inFoo\",\n        description: \"Input foo\",\n        type: \"all\"\n      }\n    },\n    out: {\n      outBar: {\n        eventName: \"outBar\",\n        description: \"Output bar\",\n        type: \"all\"\n      }\n    }\n  },\n  connection: \"bar/outBar =\u003e bar/inFoo\"\n})\n\nclient.on('inFoo', (data) =\u003e console.log('inFoo', data))\nclient.emit('outBar', { do: stuff})\n```\n\nThe connection string was sent to the spacebro server, that will then\nconnects every event named `outBar` from client `bar` to a new event\nnamed `inFoo` sent to client `bar`\n\n## 🚀 API\n\n### `class SpacebroClient([options], [connect])`\n\nLook for a server, and return a handle to the connection.\n\n```js\n// For more details about possible options, see below.\nconst client = new SpacebroClient({\n  host: '127.0.0.1',\n  port: 8888,\n  client: {name: 'foo'},\n  channelName: 'bar'\n})\n```\n\n#### options:\n\n| name | default | required | description |\n|:---|:---|:---|:---|\n| **host** | - | *required* | The spacebro server's address. Ignored if `connect` is false. |\n| **port** | - | *required* | The spacebro server's address. Ignored if `connect` is false. |\n| **client.name** | `null` | *recommended* | Your client's name. Can be useful to perform targeted events and for monitoring. |\n| **channelName** | `null` | *recommended* | The channel your app will communicate in. This is especially usefull if you have multiple apps using the same server. |\n| **verbose** | `true` | *optional* | Should spacebro-client display logs (connection / emission / reception)? |\n| **sendBack** | `true` | *optional* | Should this client receive the events it sent? |\n\n#### connect\n\nIf the `connect` parameter is false, then the options are saved and a disconnected handle is returned; you have to call its `connect` method later before you can emit or receive events.\n\nDefault value: `true`\n\n\n```js\nconst client = new SpacebroClient({\n  client: {name: 'myClient'},\n  channelName: 'someChannel'\n}, false)\n\n// ...\n\nclient.connect('127.0.0.1', 8888)\n```\n\n### `create([options])`\n\nLook for a server, and creates a handle to the connection. Takes the same options as `new SpacebroClient`. Returns a Promise like `client.connect`.\n\n### `setDefaultSettings(options, [verbose])`\n\nOverwrite the default options of `new SpacebroClient` with the given options.\n\nIf [standard-settings](https://github.com/soixantecircuits/standard-settings) is installed in your module, `spacebro-client` will call this function with the contents of `services.spacebro` from your settings file.\n\n### `client.connect(address, port)`\n\nLook for a server, and connect `client` to this server. Returns a Promise that resolves to `client` when the connection is established, or throws an error if the connection fails.\n\n### `client.emit(eventName[, data])`\n\nBroadcast a specific event to all the clients in the channel. `data` must be a JSON object.\n\n### `client.sendTo(eventName, target[, data])`\n\nSend an event to a specific target in the channel. `data` must be a JSON object.\n\n### `client.on(eventName, handler)`\n\nListen to a specific event.\n\n### `client.once(eventName, handler)`\n\nListen to a specific event only once.\n\n### `client.off(eventName)`\n\nRemove a specific event listener.\n\n### `client.disconnect()`\n\nClose the connection.\n\n## Socket.io callbacks (acknowledgments)\n\nSpacebro now works with [acknowlegdments\ntoo](https://socket.io/docs/server-api/#socket-send-args-ack) ! \n\n```js\nconst { SpacebroClient } = require('spacebro-client')\n\nconst client = new SpacebroClient({\n  host: '127.0.0.1',\n  port: 36000,\n  channelName: 'bar',\n  client: {\n    name: 'foo',\n    description: \"a foo tool\",\n    in: {\n      inFoo: {\n        eventName: \"inFoo\",\n        description: \"Input foo\",\n        type: \"all\"\n      }\n    },\n    out: {\n      outBar: {\n        eventName: \"outBar\",\n        description: \"Output bar\",\n        type: \"all\"\n      }\n    }\n  },\n  connection: \"bar/outBar =\u003e bar/inFoo\"\n})\n\nclient.on('inFoo', (data, fn) =\u003e {\n  console.log('inFoo', data)\n  fn('thank you')\n})\n\nclient.emit('outBar', { do: stuff}, function (data) {\n  console.log('Received from callback: ' + data)\n})\n```\n\n\n## 🖥 Browser\n\nYou can use spacebro-client in the browser. You will need the following dependencies:\n\n```html\n\u003cscript src=\"https://cdnjs.cloudflare.com/ajax/libs/socket.io/2.1.0/socket.io.js\"\u003e\u003c/script\u003e\n\u003cscript src=\"https://wzrd.in/standalone/socketio-wildcard@latest\"\u003e\u003c/script\u003e\n\u003cscript src=\"https://cdnjs.cloudflare.com/ajax/libs/js-signals/1.0.0/js-signals.min.js\"\u003e\u003c/script\u003e\n```\n\nAfter adding these dependencies, you can include the spacebro-client lib like any script:\n\n```html\n\u003cscript src=\"./dist/spacebro-client.js\"\u003e\u003c/script\u003e\n```\n\nThen use the `window.spacebroClient` object.\n\n## ⚛ Electron\n\nSpacebro-client also works in [Electron](http://electron.atom.io). You just `require('spacebro-client')` in your electron [main process](https://github.com/electron/electron/blob/master/docs/tutorial/quick-start.md#differences-between-main-process-and-renderer-process) and use [ipc](https://github.com/electron/electron/blob/master/docs/api/ipc-main.md) or [web-contents](https://github.com/electron/electron/blob/master/docs/api/web-contents.md) to forward events to the [renderer process](https://github.com/electron/electron/blob/master/docs/tutorial/quick-start.md#differences-between-main-process-and-renderer-process).\n\nFrom the `example/electron/` folder of this repository:\n\n```js\n// In the main process.\nconst { app, BrowserWindow } = require('electron')\nconst { SpacebroClient } = require('../../dist/spacebro-client')\n\nlet win = null\n\nconst client = new SpacebroClient({\n  host: '127.0.0.1',\n  port: 8888,\n  client: {name: 'foo'},\n  channelName: 'bar'\n})\n\napp.on('ready', () =\u003e {\n  win = new BrowserWindow({ width: 800, height: 600 })\n  win.loadURL(`file://${__dirname}/index.html`)\n\n  for (const eventName of ['hello', 'world']) {\n    client.on(eventName, (data) =\u003e {\n      win.webContents.send(eventName, data)\n    })\n  }\n\n  win.webContents.on('did-finish-load', () =\u003e {\n    setTimeout(() =\u003e { client.emit('hello', { hello: 'world' }) }, 3000)\n    setTimeout(() =\u003e { client.emit('world', { world: 'hello' }) }, 5000)\n  })\n})\n```\n\n```html\n\u003c!-- index.html --\u003e\n\u003chtml\u003e\n\u003cbody\u003e\n  \u003cscript\u003e\n    require('electron').ipcRenderer.on('hello', (event, message) =\u003e {\n      console.log(message)\n    })\n    require('electron').ipcRenderer.on('world', (event, message) =\u003e {\n      console.log(message)\n    })\n  \u003c/script\u003e\n\u003c/body\u003e\n\u003c/html\u003e\n```\n\n## Examples\n\nYou can find many real life examples in the `example/` folder of this repository.\n\n## 🕳 Troubleshooting\n\n### `newClient` event 👋\n\nThe Spacebro server automatically broadcasts a `newClient` event when a client connects. Thus, you should avoid using that event name. See the `example/simple-node` script for more details.\n\n### Using native modules in Electron 🌀\n\nIf you want to use `spacebro-client` in an Electron app, you'll have to use [electron-rebuild](https://github.com/electron/electron-rebuild) in order to rebuild MDNS according to the version of Node.js embedded with Electron.\n\nUse the following commands:\n\n```bash\n$ npm i --save-dev electron-rebuild # or yarn\n$ ./node_modules/.bin/electron-rebuild # call the executable every time you add a new native module\n```\n\nYou can also add `\"rebuild\": \"./node_modules/.bin/electron-rebuild\"` to your `package.json` and run `npm run rebuild` for convenience.\n\n*[source](https://github.com/electron/electron/blob/master/docs/tutorial/using-native-node-modules.md)*\n\n### yarn and node-gyp issue (i.e not compiling) 🤖\n\nYou need to use at least yarn version `0.17.8`. You might have similar problems with outdated versions of npm, simply try to update it.\n\n*[source](https://github.com/yarnpkg/yarn/issues/1979)*\n\n\n### https\n\nIf the spacebro server is on https, use following settings:\n\n```\n  'service': {\n    'spacebro': {\n      'host': 'https://example.com'\n      'port': 0\n    }\n  }\n```\n\n### subdir on server\n\nIf the server url is something like `https://example.com/subdir`. You\ncan use this url as host. Spacebro will process `subdir` as a path,\ncontrary to socket.io that would process `subdir` as a\n[namespace](https://socket.io/docs/client-api/#io-url-options).\n\nThat means the requested urls will look like\n`https://example.com/subdir/?EIO=3\u0026transport=polling\u0026sid=\u003cid\u003e`\n\n### ping pong 🏓\n\nDo not try to test with `'ping'` and `'pong'` events, those are reserved.\n\n```\n- `ping`. Fired when a ping packet is written out to the server.\n- `pong`. Fired when a pong is received from the server.\n```\n*[source](https://github.com/socketio/socket.io-client/issues/1022)*\n\n## ❤️ Contribute\n\nPlease follow [Standard JS](https://github.com/feross/standard) conventions.\n\nThe package has lint testing and unit testing baked-in. Please use `npm run test` to run both sets of tests before making a pull request. Use `npm run build` to transpile the project.\n\nThe project's release versions are named after [stars in Andromeda ](https://en.wikipedia.org/wiki/List_of_stars_in_Andromeda). The current version is named Sirrah.\n\nEnjoy !\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspacebro%2Fspacebro-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspacebro%2Fspacebro-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspacebro%2Fspacebro-client/lists"}