@sockudo/client

Sockudo JavaScript client SDK with modern runtime targets:

• Web
• Node.js
• Web Worker
• React hooks
• Vue composables
• React Native
• NativeScript

Install

npm install @sockudo/client

or

bun add @sockudo/client

Runtime Imports

Use the entrypoint that matches your runtime:

// Browser / default
import Sockudo from "@sockudo/client";

// Filter helper entrypoint
import { Filter } from "@sockudo/client/filter";

// With encryption
import SockudoEncrypted from "@sockudo/client/with-encryption";

// Worker
import WorkerSockudo from "@sockudo/client/worker";

// Worker with encryption
import WorkerEncrypted from "@sockudo/client/worker/with-encryption";

// React hooks
import { SockudoProvider, useChannel } from "@sockudo/client/react";

// Vue composables
import { createSockudoPlugin, useChannel as useSockudoChannel } from "@sockudo/client/vue";

// React Native
import ReactNativeSockudo from "@sockudo/client/react-native";

// NativeScript
import NativeScriptSockudo from "@sockudo/client/nativescript";

The package also exposes runtime-aware fields in package.json (main, browser, react-native, nativescript, exports) so bundlers can resolve correctly.

Quick Start

import Sockudo from "@sockudo/client";

const sockudo = new Sockudo("app-key", {
  wsHost: "your-sockudo-host",
  wsPort: 6001,
  wssPort: 6001,
  forceTLS: true,
  enabledTransports: ["ws", "wss"],
});

const channel = sockudo.subscribe("public-updates");
channel.bind("message", (payload: unknown) => {
  console.log(payload);
});

The default client mode is Protocol V1 compatibility (protocol=7). Opt into Protocol V2 explicitly when you want Sockudo-native event prefixes and V2-only features.

const sockudoV2 = new Sockudo("app-key", {
  wsHost: "your-sockudo-host",
  wsPort: 6001,
  forceTLS: true,
  protocolVersion: 2,
});

Features

• Pusher-protocol-compatible client surface
• Protocol V1 compatibility by default
• WebSocket-first connection strategy
• Fetch-first auth/timeline integrations
• ESM-first package outputs
• Runtime-specific builds for web/node/worker/react-native/nativescript
• Built-in React hooks via @sockudo/client/react
• Built-in Vue composables via @sockudo/client/vue
• Continuity-aware recovery positions and subscribe-time rewind in Protocol V2

Recovery And Rewind

const client = new Sockudo("app-key", {
  wsHost: "127.0.0.1",
  wsPort: 6001,
  forceTLS: false,
  protocolVersion: 2,
  connectionRecovery: true,
});

const channel = client.subscribe("market:BTC", {
  rewind: { seconds: 30 },
});

channel.bind("message", () => {
  console.log(client.getRecoveryPosition("market:BTC"));
});

client.bind("sockudo:resume_success", (payload) => {
  console.log(payload.recovered, payload.failed);
});

channel.bind("sockudo:rewind_complete", (payload) => {
  console.log(payload.historical_count, payload.complete);
});

React Hooks

Install the framework peer dependencies:

npm install @sockudo/client react react-dom

import React from "react";
import Sockudo from "@sockudo/client";
import { SockudoProvider, useChannel } from "@sockudo/client/react";

const client = new Sockudo("app-key", {
  wsHost: "127.0.0.1",
  wsPort: 6001,
  forceTLS: false,
});

client.connect();

function PresencePanel() {
  const { subscribed, members } = useChannel("presence-room");

  return (
    <div>
      <div>Subscribed: {String(subscribed)}</div>
      <div>Members: {members?.length ?? 0}</div>
    </div>
  );
}

export function App() {
  return (
    <SockudoProvider client={client}>
      <PresencePanel />
    </SockudoProvider>
  );
}

Available React exports:

• SockudoProvider
• useSockudo
• useSockudoEvent
• useChannel
• usePresenceChannel

Vue Composables

Install the framework peer dependency:

npm install @sockudo/client vue

import { createApp, defineComponent, h } from "vue";
import Sockudo from "@sockudo/client";
import { createSockudoPlugin, useChannel } from "@sockudo/client/vue";

const client = new Sockudo("app-key", {
  wsHost: "127.0.0.1",
  wsPort: 6001,
  forceTLS: false,
});

client.connect();

const PresencePanel = defineComponent({
  setup() {
    const { subscribed, members } = useChannel("presence-room");
    return () =>
      h("div", [
        h("div", `Subscribed: ${String(subscribed.value)}`),
        h("div", `Members: ${members.value?.length ?? 0}`),
      ]);
  },
});

createApp(PresencePanel).use(createSockudoPlugin(client)).mount("#app");

Available Vue exports:

• createSockudoPlugin
• provideSockudo
• useSockudo
• useSockudoEvent
• useChannel
• usePresenceChannel

React Native Notes

• React Native build output is dist/react-native/sockudo.js
• Package exposes both:
  • root react-native resolution
  • explicit @sockudo/client/react-native subpath
• @react-native-community/netinfo is an optional peer dependency
• React Native support remains inside @sockudo/client; React and Vue integrations stay as subpath exports in the same package

NativeScript Notes

• Install the NativeScript websocket polyfill:

npm install @sockudo/client @valor/nativescript-websockets

• Import @sockudo/client/nativescript to automatically load the websocket polyfill before the SDK.
• NativeScript build output is dist/nativescript/sockudo.js
• Package exposes both:
  • root nativescript resolution
  • explicit @sockudo/client/nativescript subpath

Development

Requirements

• Bun >=1.0.0
• Node.js >=22

Commands

# typecheck + lint + tests
bun run check

# typecheck only
bun run typecheck

# lint
bun run lint

# format
bun run format
bun run format:check

# tests
bun test
bun run test:watch

# builds
bun run build
bun run build:all

Release Process

This repo uses GitHub Actions for CI/CD and changelogs.

CI

• Workflow: .github/workflows/ci.yml
• Runs on push to main and pull requests
• Executes:
  • bun run check
  • bun run build:all

Changelog + Versioning

• Workflow: .github/workflows/release-please.yml
• Uses Release Please to open/update a Release PR
• Generates and updates:
  • CHANGELOG.md
  • package.json version
  • git tag on release merge

npm Publish

• Workflow: .github/workflows/publish-npm.yml
• Triggers on:
  • release.published
  • manual dispatch
• Publishes @sockudo/client with npm provenance

Required repo secret:

• NPM_TOKEN

Repository

• GitHub: https://github.com/sockudo/sockudo-js
• npm: https://www.npmjs.com/package/@sockudo/client