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.

전체 설치 가이드와 연동 프롬프트는 구매 후 열람할 수 있습니다.

LiveKit React Components for Realtime Agent UI

Automation, Utilities & Developer Tools

무료