Unofficial sdk for browserless.

📋 Table of Contents

• Install
• Client SDK
• WebSocket URL Helpers
• Browser Viewer Components
• React Example
• Exports
• Package Contents
• License

Install

npm install browserless-sdk

This package is a lightweight SDK for the Browserless live session API from the paired research/keepalive-reconnect Browserless branch. It does not ship the Browserless server, Docker image, debugger portal, or CLI.

Client SDK

Use BrowserlessClient to create, list, renew, suspend, and release live browser sessions.

import { BrowserlessClient } from 'browserless-sdk';

const client = new BrowserlessClient({
  baseURL: 'http://127.0.0.1:3023',
  token: 'browserless',
});

const session = await client.sessions.create({
  browser: 'chromium',
  continuity: true,
  leaseToken: 'browserless-example-lease',
  ttlMs: 300_000,
});

console.log(session.browserId);
console.log(session.browserWSEndpoint);

await client.sessions.renew(session.browserId, {
  leaseToken: session.leaseToken,
  ttlMs: 300_000,
});

await client.sessions.suspend(session.browserId, {
  leaseToken: session.leaseToken,
});

await client.sessions.release(session.browserId, {
  leaseToken: session.leaseToken,
});

browserWSEndpoint is returned as a bare browser websocket endpoint. Add auth and lease parameters before passing it to Puppeteer or another CDP client.

WebSocket URL Helpers

import {
  browserlessBrowserWebSocketURL,
  browserlessPageWebSocketURL,
  browserlessWebSocketURL,
} from 'browserless-sdk/ws';

const reconnectURL = browserlessWebSocketURL(session.browserWSEndpoint, {
  leaseToken: session.leaseToken,
  token: 'browserless',
});

const browserURL = browserlessBrowserWebSocketURL({
  baseURL: 'http://127.0.0.1:3023',
  browserId: session.browserId,
  leaseToken: session.leaseToken,
  token: 'browserless',
});

const pageURL = browserlessPageWebSocketURL({
  baseURL: 'http://127.0.0.1:3023',
  targetId: 'page-target-id',
  leaseToken: session.leaseToken,
  token: 'browserless',
});

Browser Viewer Components

The browser-viewer package provides framework-agnostic browser rendering components for web apps:

• RemoteBrowser manages a Browserless session, viewer canvas, DevTools shell, lifecycle state, navigation, renew/suspend/release helpers, and errors.
• RemoteBrowserSession is the lower-level worker-backed screencast/input session.
• ScreencastViewer renders CDP screencast frames to a canvas and sends frame acknowledgements.
• BrowserShell provides an embeddable viewer + DevTools layout.
• WorkerTransport bridges viewer messages to a web worker.

import {
  RemoteBrowser,
  type RemoteBrowserSnapshot,
} from 'browserless-sdk/browser-viewer';
import RemoteBrowserWorkerURL from 'browserless-sdk/browser-viewer/worker?url';

const mount = document.getElementById('viewer')!;

const browser = new RemoteBrowser({
  clientOptions: {
    baseURL: 'http://127.0.0.1:3023',
    token: 'browserless',
  },
  createSessionOptions: {
    leaseToken: 'browserless-example-lease',
    ttlMs: 300_000,
  },
  devtools: { startOpen: false },
  mount,
  viewport: {
    deviceScaleFactor: 'host',
    height: 'auto',
    width: 1280,
  },
  workerFactory: () =>
    new Worker(RemoteBrowserWorkerURL, {
      type: 'module',
    }),
});

browser.subscribe((snapshot: RemoteBrowserSnapshot) => {
  console.log(snapshot.phase, snapshot.session?.browserId);
});

await browser.connect();
await browser.navigate('https://example.com');

Reconnect to an existing browser

const browser = new RemoteBrowser({
  clientOptions: {
    baseURL: 'http://127.0.0.1:3023',
    token: 'browserless',
  },
  mount,
  sessionTarget: {
    browserId: 'existing-browser-id',
    leaseToken: 'browserless-example-lease',
    targetId: 'existing-page-target-id',
  },
  workerFactory: () => new RemoteBrowserWorker(),
});

await browser.connect();

React Example

import { useEffect, useRef, useState } from 'react';
import {
  RemoteBrowser,
  type RemoteBrowserSnapshot,
} from 'browserless-sdk/browser-viewer';
import RemoteBrowserWorkerURL from 'browserless-sdk/browser-viewer/worker?url';

export function BrowserPanel() {
  const mountRef = useRef<HTMLDivElement | null>(null);
  const [snapshot, setSnapshot] = useState<RemoteBrowserSnapshot>({
    phase: 'idle',
  });

  useEffect(() => {
    if (!mountRef.current) return;

    const browser = new RemoteBrowser({
      clientOptions: {
        baseURL: 'http://127.0.0.1:3023',
        token: 'browserless',
      },
      createSessionOptions: {
        leaseToken: 'browserless-example-lease',
      },
      devtools: true,
      mount: mountRef.current,
      workerFactory: () =>
        new Worker(RemoteBrowserWorkerURL, {
          type: 'module',
        }),
    });

    const unsubscribe = browser.subscribe(setSnapshot);
    browser.connect().then(() => browser.navigate('https://example.com'));

    return () => {
      unsubscribe();
      browser.dispose();
    };
  }, []);

  return (
    <section>
      <strong>{snapshot.phase}</strong>
      <div ref={mountRef} style={{ minHeight: 480 }} />
    </section>
  );
}

Exports

import { BrowserlessClient } from 'browserless-sdk';
import { BrowserlessClient as Client } from 'browserless-sdk/client';
import { RemoteBrowser } from 'browserless-sdk/browser-viewer';
import RemoteBrowserWorker from 'browserless-sdk/browser-viewer/worker';
import { browserlessWebSocketURL } from 'browserless-sdk/ws';

Available package subpaths:

• browserless-sdk
• browserless-sdk/client
• browserless-sdk/browser-viewer
• browserless-sdk/browser-viewer/worker
• browserless-sdk/browser-viewer/transport
• browserless-sdk/browser-viewer/worker-transport
• browserless-sdk/browser-viewer/shell
• browserless-sdk/ws

Package Contents

The published package is intentionally scoped to SDK runtime artifacts under build/sdk/**/*. It should not include Browserless server code, Docker files, debugger portal assets, test specs, examples, scripts, or source TypeScript.

Run this before publishing to audit the tarball:

npm pack --dry-run

License

MIT