Node.js Integration

Using Crosslink in Node.js applications

Setup

npm install @crosslink/sdk-node

Basic usage

import { createCrosslinkServer } from "@crosslink/sdk-node";

const server = createCrosslinkServer({
  application: { id: "com.example.myapp", name: "My App", version: "1.0.0" },
  capabilities: [
    { id: "app.control", title: "Control the app", risk: "medium" }
  ],
  signalingUrl: "http://127.0.0.1:8081",
  relayUrl: "http://127.0.0.1:8082",
  lan: { bind: "loopback" }
});

server.expose("app.status", () => ({ ok: true }));
await server.start();

Exposing methods

Basic method

server.expose("math.add", (args) => {
  return { result: args.a + args.b };
});

With capability

server.expose("admin.shutdown", () => {
  process.exit(0);
}, { capability: "admin" });

Async method

server.expose("db.query", async (args) => {
  const result = await db.query(args.sql);
  return { rows: result.rows };
});

Streaming progress

A handler can emit progress chunks before returning its final result, via emitProgress on the RPC context:

server.expose("file.read", async (args, { emitProgress }) => {
  const chunks = [];
  for await (const chunk of fs.createReadStream(args.path)) {
    emitProgress({ bytes: chunk.length });
    chunks.push(chunk);
  }
  return { content: Buffer.concat(chunks).toString("base64") };
}, { capability: "file.read" });

Emitting events

// Declare events
server.declareEvent("app.tick");
server.declareEvent("app.update");

// Emit events
setInterval(() => {
  server.emit("app.tick", { t: Date.now() });
}, 1000);

Managing clients

// List paired devices
const devices = server.listDevices();
console.log(`${devices.length} devices paired`);

// Revoke a specific device (kills its active session, blocks reconnection)
server.revokeDevice(deviceId);

// Revoke every paired device
server.revokeAllDevices();

Identity persistence

The host identity is persisted automatically under storageDir (default ./.crosslink-data/<appId>), in the strongest available secret store (OS keychain, Electron safeStorage, or an encrypted file), plus a paired-devices record. Pass storageDir in createCrosslinkServer() to override the location.

Environment variables

Variable	Default	Description
CROSSLINK_SIGNALING_URL	(none)	Signaling server URL, if not passed via signalingUrl
CROSSLINK_RELAY_URL	(none)	Relay server URL, if not passed via relayUrl
CROSSLINK_SECRET_KEY	(none)	Passphrase for encrypted-file secret storage

Graceful shutdown

process.on("SIGTERM", async () => {
  await server.stop();
  process.exit(0);
});

Handling server events

CrosslinkServer extends Node’s EventEmitter. Use typedOn() for the typed events it emits:

server.typedOn("devicePaired", (record) => {
  console.log("Paired:", record.deviceId);
});

server.typedOn("deviceConnected", ({ deviceId, transport }) => {
  console.log(`${deviceId} connected via ${transport}`);
});

server.typedOn("deviceDisconnected", ({ deviceId, transport }) => {
  console.log(`${deviceId} disconnected`);
});

server.typedOn("deviceRevoked", (deviceId) => {
  console.log(`${deviceId} revoked`);
});

TypeScript

Both SDKs ship with TypeScript declarations:

import type { CreateCrosslinkServerOptions } from "@crosslink/sdk-node";

const options: CreateCrosslinkServerOptions = {
  application: { id: "com.example.myapp", name: "My App", version: "1.0.0" },
  capabilities: [
    { id: "app.control", title: "Control the app", risk: "medium" }
  ]
};