Lightrail Clients

In the Lightrail ecosystem, a Client is a piece of software that runs outside of the Lightrail program and communicates with the Lightrail application. Typically, they tend to be extensions for other platforms, to serve as bridges between those platforms and Lightrail. Examples of clients include the lightrail-bridge VSCode extension (opens in a new tab), the chrome extension (opens in a new tab), or the JupyterLab extension (opens in a new tab). Clients currently must be written in TS/JS, because they depend on the lightrail-sdk which is only available in those languages. However, communication with Lightrail occurs over websocket, so porting to other languages should be fairly simple. Let use know if you require support for a different language/platform, and we'll help you get it up and running.

Implementation

Currently, creating a Lightrail Client requires two packages: lightrail-sdk (opens in a new tab) as well as socket.io-client (opens in a new tab). To get started, install both using your preferred package manager (npm, yarn, etc.) in the project that you'd like to communicate with Lightrail from. Then, use this snippet to establish a new client connection to a local Lightrail instance, with client-name replaced with an identifier for your client:

import { LightrailClient } from "lightrail-sdk";
import { io } from "socket.io-client";
 
let lightrailClient = new LightrailClient(
  "client-name",
  io("ws://localhost:1218") as any
);

LightrailClient has only two methods, described here:

lightrailClient.sendMessageToMain(trackName: string, messageName: string, messageBody: any ): Promise<any>

Send a message to a main process handler, in the specified track. Since main process handlers can return values, this method returns a promise that resolves to the return value of the handler.

lightrailClient.registerHandler(messageName: string, handler: (messageBody: any) => Promise<any> ): void

Register a new handler on the client, that tracks can send messages to from Lightrail's main process. Handlers will be identified from the main process by both client name and handler name. The handler can return a promise that resolves to a value, and this value will be made available as a response when this handler is called from a Lightrail track.