npx expo prebuild   # if using Expo
# or
npx react-native-clean-project  # bare RN

Project setup

1. Copy the source/ directory into your project, e.g. src/ably-source/.

2. Update tsconfig.json to add path aliases so the SDK's internal cross-package imports resolve:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "common/*": ["src/ably-source/common/*"]
    },
    "module": "commonjs",
    "target": "ES2017",
    "esModuleInterop": true,
    "resolveJsonModule": true
  }
}

3. If you use ts-node or tsconfig-paths, register the paths at startup:

ts-node -r tsconfig-paths/register src/index.ts

4. Set your Ably API key via environment variable:

export ABLY_API_KEY="your-app.key:secret"

5. Import from the Node.js platform entry point:

import Ably from './ably-source/platform/nodejs/index';
const { Realtime, Rest, ErrorInfo } = Ably;

Public API

DefaultRealtime

import { DefaultRealtime } from './ably-source/common/lib/client/defaultrealtime';

const client = new DefaultRealtime({ key: process.env.ABLY_API_KEY });

Full-featured realtime client. Use when you need persistent connections, pub/sub channels, presence, and connection state management. Internally wires up WebSocket and Comet transports.

DefaultRest

import { DefaultRest } from './ably-source/common/lib/client/defaultrest';

const client = new DefaultRest({ key: process.env.ABLY_API_KEY });

Stateless HTTP REST client. Use for publish-only workloads, querying history, managing presence, or any server-side operation where a persistent connection is unnecessary.

ErrorInfo

import ErrorInfo from './ably-source/common/lib/types/errorinfo';

// ErrorInfo is thrown / returned by SDK methods on failure
// statusCode: number, code: number, message: string

Ably's structured error type. Always check err instanceof ErrorInfo in catch blocks to access err.code (Ably error code) and err.statusCode (HTTP status) for programmatic error handling.

makeProtocolMessageFromDeserialized

import { makeFromDeserializedWithDependencies as makeProtocolMessageFromDeserialized }
  from './ably-source/common/lib/types/protocolmessage';

Reconstructs a ProtocolMessage from a raw deserialized object (e.g., received over a custom transport or from msgpack). Use in custom transport or testing scenarios where you control the wire layer.

Working examples

Scenario - Subscribe to a channel and publish a message

Connect with the Realtime client, subscribe to an event, and publish a message.

import Ably from './ably-source/platform/nodejs/index';

const client = new Ably.Realtime({ key: process.env.ABLY_API_KEY!, clientId: 'server-1' });

async function run() {
  await client.connection.once('connected');
  console.log('Connected');

  const channel = client.channels.get('orders');

  await channel.subscribe('new-order', (msg) => {
    console.log('Received:', msg.data);
  });

  await channel.publish('new-order', { id: 42, item: 'widget' });
}

run().catch(console.error);

Scenario - Publish via REST (no persistent connection)

Use the REST client to publish a message from a stateless serverless function.

import Ably from './ably-source/platform/nodejs/index';

const rest = new Ably.Rest({ key: process.env.ABLY_API_KEY! });

async function publishEvent(orderId: string) {
  const channel = rest.channels.get('orders');
  await channel.publish('new-order', { id: orderId });
  console.log('Published order', orderId);
}

publishEvent('abc-123').catch(console.error);

Scenario - Presence: enter and list members

Use the Realtime client to join a presence set and list current members.

import Ably from './ably-source/platform/nodejs/index';

const client = new Ably.Realtime({
  key: process.env.ABLY_API_KEY!,
  clientId: 'worker-node-1',
});

async function managePresence() {
  await client.connection.once('connected');

  const channel = client.channels.get('workers');
  await channel.presence.enter({ role: 'processor' });

  const members = await channel.presence.get();
  console.log('Current members:', members.map((m) => m.clientId));

  // Clean up
  await channel.presence.leave();
  client.close();
}

managePresence().catch(console.error);

Scenario - Handle ErrorInfo in catch blocks

Distinguish Ably errors from generic errors.

import Ably from './ably-source/platform/nodejs/index';
import ErrorInfo from './ably-source/common/lib/types/errorinfo';

const rest = new Ably.Rest({ key: 'invalid.key:bad' });

async function safeFetch() {
  try {
    const channel = rest.channels.get('test');
    await channel.publish('evt', 'hello');
  } catch (err) {
    if (err instanceof ErrorInfo) {
      console.error(`Ably error ${err.code} (HTTP ${err.statusCode}): ${err.message}`);
    } else {
      throw err;
    }
  }
}

safeFetch();

File walkthrough

• common/lib/client/defaultrealtime.ts - Assembles the full Realtime client with all features enabled.
• common/lib/client/defaultrest.ts - Assembles the full Rest client with all features enabled.
• common/lib/client/baseclient.ts - Shared base: auth, options parsing, HTTP dispatch.
• common/lib/client/auth.ts - Token auth, API key auth, requestToken, authorize.
• common/lib/client/realtimechannel.ts - Channel attach/detach, subscribe/unsubscribe, state machine.
• common/lib/client/restchannel.ts - REST channel: publish and history.
• common/lib/client/realtimepresence.ts - Realtime presence: enter, leave, update, get, subscribe.
• common/lib/transport/connectionmanager.ts - Manages transport lifecycle and reconnection strategy.
• common/lib/transport/websockettransport.ts - WebSocket transport implementation.
• common/lib/transport/comettransport.ts - Comet (long-poll) fallback transport.
• common/lib/types/errorinfo.ts - ErrorInfo structured error class.
• common/lib/types/message.ts - Message type with encode/decode helpers.
• common/lib/types/protocolmessage.ts - Wire-level protocol message; makeFromDeserializedWithDependencies factory.
• common/lib/util/logger.ts - Configurable logger with log-level support.
• common/lib/util/eventemitter.ts - Internal typed event emitter used by channels and connection.
• common/lib/util/defaults.ts - getDefaults() merges platform defaults with user options.
• platform/nodejs/index.ts - Node.js platform entry point; wires Crypto, Http, transports, msgpack.
• platform/nodejs/lib/transport/index.ts - Exports transport order and bundled WebSocket + Comet implementations.
• platform/react-native/index.ts - React Native entry point (same shape, different platform modules).
• platform/nativescript/index.ts - NativeScript entry point.
• platform/react-hooks/src/index.ts - React hooks: useChannel, usePresence, useAbly, usePresenceListener, etc.
• fragments/ably.d.ts - Aggregated TypeScript type declarations for the whole SDK.

Common pitfalls and fixes

• Cannot find module 'common/...' at runtime - Add tsconfig-paths and register it before entry (-r tsconfig-paths/register); the SDK uses bare common/ imports internally.
• ws is not installed - The Node.js WebSocket transport requires ws; it is not bundled. Run npm install ws.
• msgpack is null on Node.js - The Node.js platform exports msgpack: null; do not pass useBinaryProtocol: true unless you wire msgpack yourself.
• ErrorInfo instanceof check fails across module copies - Ensure only one copy of ably-source exists in the dependency tree; duplicate copies break instanceof.
• React Native: TextEncoder not defined - The RN platform index imports fastestsmallesttextencoderdecoder as a polyfill; ensure this runs before any SDK code.
• Connection not closing on process exit - Always call client.close() or the Node.js process will hang due to open WebSocket/TCP handles.

Vibe-coding prompt template

I have the Ably Pub/Sub JavaScript SDK source at `src/ably-source/` (upstream package: user@example.com)
and a USAGE.md integration guide at `src/ably-source/USAGE.md`.

Please integrate this SDK into my existing Node.js / TypeScript project step by step:

1. Read USAGE.md fully before writing any code.
2. Add the required tsconfig path aliases for `common/*` as shown in USAGE.md.
3. Install all runtime dependencies listed in the "Required dependencies" section.
4. Create a singleton Ably Realtime client (using `platform/nodejs/index.ts`) that reads
   the API key from the `ABLY_API_KEY` environment variable.
5. Wire up a channel subscription for the channel name I specify, and export a `publish`
   helper function.
6. Add proper error handling using `ErrorInfo` from `common/lib/types/errorinfo.ts`.
7. Ensure `client.close()` is called on process SIGTERM/SIGINT.
8. Only use exports that are visible in USAGE.md - do not invent new APIs.

License and credit

The Ably Pub/Sub JavaScript SDK is released under the Apache 2.0 license. See source/LICENSE if present, or refer to the upstream repository.

Upstream package: ably on npm - version 2.21.0. Source repository: https://github.com/ably/ably-js.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

LiveKit React Components for Realtime Agent UI

Automation, Utilities & Developer Tools

Free