Skip to main content

Five-minute quickstart

Requirements: Node.js 22.16.0 or later, npm, and three terminals. Success: the receiver prints hello#message and Hello, IOSignal!.

Start the server, subscribe the receiver, then send a message through the server.

To find the right order for your goal, choose a path.

1. Prepare a project​

mkdir iosignal-hello
cd iosignal-hello
npm init -y
npm install iosignal

The .mjs extension enables ES modules without changing package.json.

2. Start the server​

Save as server.mjs:

import { Server } from 'iosignal';

const server = new Server({ port: 7777 });
server.on('ready', () => console.log('Server ready: ws://localhost:7777'));

In terminal 1, run node server.mjs and leave it running.

3. Start the receiver​

Save as receiver.mjs:

import { IO } from 'iosignal';

const io = new IO('ws://localhost:7777');
io.listen('hello#message', (tag, message) => {
console.log(tag, message);
});
io.on('ready', () => console.log('Receiver ready:', io.cid));
io.on('error', console.error);

In terminal 2, run node receiver.mjs and wait for Receiver ready. listen() registers the handler and schedules the subscription when the connection becomes ready.

4. Send a message​

Save as sender.mjs:

import { IO } from 'iosignal';

const io = new IO('ws://localhost:7777');
io.on('ready', () => {
io.signal('hello#message', 'Hello, IOSignal!');
console.log('Message sent');
});
io.on('error', console.error);

In terminal 3, run node sender.mjs. The receiver should print hello#message Hello, IOSignal!. Here hello is the channel and message is the topic. Stop each process with Ctrl+C.

Try it with the CLI, no code​

You can check the same flow without code using iosignal-cli. Stop the Node.js server above, then use three terminals.

npm install -g iosignal-cli
io-server -l 7777

Leave terminal 1 running. In terminals 2 and 3, connect a client and wait for ready and a CID.

io-client -c ws://localhost:7777

Send to a channel: enter listen demo in client 2 and signal demo hello in client 3. The receiver prints < -message: demo hello.

Send directly to a CID: enter id in the receiver to find its CID, then enter signal actualCID@ hello in the sender, including a leading ? for an anonymous CID. Direct messages need no listen.

Exit a client with exit, quit, or Ctrl+C. CLI arguments are split on whitespace; shell quoting and JSON are not parsed. See CLI client and CLI server options for all commands. For Arduino, add -L 8888 to the server and use matching TCP settings on the board.

Next steps​