Lightstreamer Client Web SDK

9.2.3 verified Sat Apr 25 auth: no javascript

Lightstreamer Client Web SDK (v9.2.3, stable) enables real-time bidirectional communication with a Lightstreamer server from web browsers. It supports WebSocket fallback options and delivers streaming data updates with low latency. Key differentiators: multiple module formats (UMD, CommonJS, ES Module) for varying bundler compatibility; includes core, full, and MPN builds; provides TypeScript definitions. Maintained by Lightstreamer with frequent releases. Ideal for financial tickers, live dashboards, and collaborative applications.

Common errors

error Uncaught ReferenceError: Ls is not defined ↓

cause The UMD script tag is missing the data-lightstreamer-ns attribute, but code references Ls.LightstreamerClient.

fix

Add data-lightstreamer-ns='Ls' to the script tag, or change code to use window.LightstreamerClient directly.

error Cannot use 'import' statement outside a module ↓

cause The library's ES module build is loaded via a script tag without type='module' or in a non-module context.

fix

Use the UMD build with a script tag, or add type='module' to the script tag and use an importmap or bundler.

error Error: No client found for session ↓

cause Calling subscribe before connect() or after disconnect() without a valid session.

fix

Ensure you call client.connect() before client.subscribe(sub), and check client status via client.addListener({onStatusChange}).

Warnings

gotcha When using the UMD build with a script tag, the library is placed under the namespace specified by the data-lightstreamer-ns attribute. If omitted, it pollutes the global window object. ↓

fix Add data-lightstreamer-ns='Ls' to the script tag to create a global Ls object, or omit to inject directly into window.

gotcha The full library contains Widgets and Mobile Push Notifications modules which are not available in Web Workers. Using the full build in a worker throws errors. ↓

fix Use the core build instead (e.g., importScripts('path/to/lightstreamer-core.js')).

gotcha CommonJS and ES Module builds are not minified; bundlers are expected to handle minification. Attempting to use them directly in a browser without bundling will fail. ↓

fix Use the UMD minified build for direct browser usage, or configure your bundler to minify the output.

deprecated The 'Subscription' constructor signature with mode, items, fields is still supported but the recommended pattern is to use the options object. ↓

fix Use new Subscription({mode:'MERGE', items:['item1'], fields:['field1']}) instead of positional arguments.

Install

npm install lightstreamer-client-web

yarn add lightstreamer-client-web

pnpm add lightstreamer-client-web

Imports

LightstreamerClient

wrong

const LightstreamerClient = require('lightstreamer-client-web');

correct

import { LightstreamerClient } from 'lightstreamer-client-web';

ESM import for modern bundlers; requires using the ES module build.

Subscription

wrong

import Subscription from 'lightstreamer-client-web';

correct

import { Subscription } from 'lightstreamer-client-web';

Subscription is a named export, not default.

ConsoleLogger

wrong

import { ConsoleLogger } from 'lightstreamer-client-web/lightstreamer.esm.js';

correct

import { ConsoleLogger } from 'lightstreamer-client-web';

Import from the package root; bundlers resolve the correct file.

Quickstart

Connects to Lightstreamer demo server, subscribes to three items with MERGE mode, and logs stock updates to console.

import { LightstreamerClient, Subscription } from 'lightstreamer-client-web';
import { ConsoleLogger } from 'lightstreamer-client-web';

const client = new LightstreamerClient('http://push.lightstreamer.com', 'DEMO');
client.addListener({
  onListenEnd: () => console.log('Disconnected'),
  onServerError: (errorCode, errorMessage) => console.error(errorCode, errorMessage),
  onStatusChange: (newStatus) => console.log('Status:', newStatus)
});

const sub = new Subscription('MERGE', ['item1','item2','item3'], ['stock_name','last_price']);
sub.setDataAdapter('QUOTE_ADAPTER');
sub.setRequestedSnapshot('yes');
sub.addListener({
  onItemUpdate: (obj) => {
    console.log(obj.getValue('stock_name') + ': ' + obj.getValue('last_price'));
  },
  onSubscriptionError: (code, msg) => console.error('Subscription error', code, msg)
});

client.connect();
client.subscribe(sub);