# leancloud-realtime > LeanCloud Realtime Message JavaScript SDK Latest version **5.0.0-rc.8** (published 2023-03-08) · MIT license · 0 weekly downloads ## Install ```sh npm install leancloud-realtime pnpm add leancloud-realtime yarn add leancloud-realtime bun add leancloud-realtime ``` ## Health **Score 25/100 (F)** — status: abandoned. Positive: has types; no vulnerabilities; high quality score. Warnings: low downloads; no esm support; large bundle. Negative: abandoned; low maintenance score. ## Facts | | | |---|---| | Version | 5.0.0-rc.8 | | Published | 2023-03-08 | | First published | 2015-07-28 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | bundled | | Module format | CommonJS | | Dependencies | 13 | | Unpacked size | 22 MB | | Known vulnerabilities | 0 (+12 in 2 direct dependencies) | | Install scripts | no | | GitHub stars | 201 | | Maintainers | notevenaneko, leeyeh, hjiang, jysperm, sdjdd, onerain88, avos | | Keywords | leancloud, realtime, message | ## Links - npm: https://www.npmjs.com/package/leancloud-realtime - Repository: https://github.com/leancloud/js-realtime-sdk - Homepage: https://leancloud.cn/ - Issues: https://github.com/leancloud/js-realtime-sdk/issues - npm.io page: https://npm.io/package/leancloud-realtime ## Dependencies (13) - [uuid](https://npm.io/package/uuid.md) ^3.0.0 - [debug](https://npm.io/package/debug.md) ^3.1.0 - [lodash](https://npm.io/package/lodash.md) ^4.17.10 - [protobufjs](https://npm.io/package/protobufjs.md) ^5.0.1 - [eventemitter3](https://npm.io/package/eventemitter3.md) ^3.0.0 - [@babel/runtime](https://npm.io/package/@babel/runtime.md) ^7.21.0 - [promise-timeout](https://npm.io/package/promise-timeout.md) ^1.3.0 - [base64-arraybuffer](https://npm.io/package/base64-arraybuffer.md) ^0.1.5 - [@leancloud/adapter-types](https://npm.io/package/@leancloud/adapter-types.md) ^3.0.0 - [javascript-state-machine](https://npm.io/package/javascript-state-machine.md) ^2.3.5 - [@leancloud/platform-adapters-node](https://npm.io/package/@leancloud/platform-adapters-node.md) ^1.1.0 - [@leancloud/platform-adapters-weapp](https://npm.io/package/@leancloud/platform-adapters-weapp.md) ^1.2.0 - [@leancloud/platform-adapters-browser](https://npm.io/package/@leancloud/platform-adapters-browser.md) ^1.1.0 ## Alternatives - [@opentelemetry/exporter-zipkin](https://npm.io/package/@opentelemetry/exporter-zipkin.md) — 14.8M weekly downloads - [pusher-js](https://npm.io/package/pusher-js.md) — 2.0M weekly downloads - [browserify](https://npm.io/package/browserify.md) — 1.7M weekly downloads - [sqs-consumer](https://npm.io/package/sqs-consumer.md) — 1.7M weekly downloads - [@sanity/eventsource](https://npm.io/package/@sanity/eventsource.md) — 930.8K weekly downloads ## Recent versions - 5.0.0-rc.8 (latest) — 2023-03-08 - 5.0.0-rc.1 (next) — 2020-03-17 - 5.0.0-dev.2003021435 (dev) — 2020-03-02 - 4.3.1 (latest-v4) — 2019-06-21 - 3.5.7 (latest-v3) — 2017-09-11 - 5.0.0-rc.7 — 2021-09-01 - 5.0.0-rc.6 — 2021-05-21 - 5.0.0-rc.5 — 2020-12-21 - 5.0.0-rc.4 — 2020-12-16 - 5.0.0-rc.3 — 2020-06-05 - 5.0.0-rc.2 — 2020-03-26 - 5.0.0-rc.0 — 2020-03-12 - 5.0.0-beta.3 — 2020-03-06 - 5.0.0-dev.2002282330 — 2020-02-28 - 5.0.0-beta.2 — 2020-01-26 - … 61 more at https://npm.io/package/leancloud-realtime/versions ## README # LeanCloud JavaScript Realtime SDK [![npm](https://img.shields.io/npm/v/leancloud-realtime.svg?style=flat-square)](https://www.npmjs.com/package/leancloud-realtime) [![npm](https://img.shields.io/npm/v/leancloud-realtime/next.svg?style=flat-square)](https://www.npmjs.com/package/leancloud-realtime) ![gzip size](https://img.badgesize.io/leancloud/js-realtime-sdk/next-dist/dist/im-browser.min.js.svg?compression=gzip&style=flat-square) [![Build Status](https://img.shields.io/travis/leancloud/js-realtime-sdk.svg?style=flat-square)](https://travis-ci.org/leancloud/js-realtime-sdk) [![Codecov](https://img.shields.io/codecov/c/github/leancloud/js-realtime-sdk.svg?style=flat-square)](https://codecov.io/github/leancloud/js-realtime-sdk) [![Known Vulnerabilities](https://snyk.io/test/github/leancloud/js-realtime-sdk/badge.svg?style=flat-square)](https://snyk.io/test/github/leancloud/js-realtime-sdk) 为您的 JavaScript App 接入 LeanCloud 实时通讯服务。 ## 版本说明 遵循 [语义化版本](http://semver.org/lang/zh-CN/)。 安装稳定版本： ``` npm install leancloud-realtime --save ``` 安装测试版本： ``` npm install leancloud-realtime@next --save ``` 安装指定版本： ``` // 安装 v3 版本 npm install leancloud-realtime@3 --save ``` ## 支持的运行环境 - 浏览器 / WebView - IE 10+ - Edge latest - Chrome 45+ - Firefox latest - iOS 9.3+ - Android 4.4+ - Node.js 4.0+ - 微信小程序/小游戏 latest - React Native 0.26+ - Electron latest ## 文档 - [安装文档](https://leancloud.cn/docs/sdk_setup-js.html) - [使用文档](https://leancloud.cn/docs/realtime_v2.html) - [API 文档](https://leancloud.github.io/js-realtime-sdk/docs/) ## Demo - [Simple Chatroom](https://leancloud.github.io/js-realtime-sdk/demo/simple-chatroom/) ([src](https://github.com/leancloud/js-realtime-sdk/tree/master/demo/simple-chatroom)) - [LeanMessage](https://leancloud.github.io/leanmessage-demo) ([src](https://github.com/leancloud/leanmessage-demo)) - [WebRTC 视频通话](https://leancloud.github.io/js-realtime-sdk/demo/webrtc/) ([src](https://github.com/leancloud/js-realtime-sdk/tree/master/demo/webrtc)) ## 插件 | package name | 描述 | 版本 | 文档 | | :------------------------------------------- | :------------ | :-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------: | | leancloud-realtime-plugin-typed-messages | 富媒体消息 | [![npm](https://img.shields.io/npm/v/leancloud-realtime-plugin-typed-messages.svg?style=flat-square)](https://www.npmjs.com/package/leancloud-realtime-plugin-typed-messages) | [API docs](https://leancloud.github.io/js-realtime-sdk/plugins/typed-messages/docs/) | | leancloud-realtime-plugin-groupchat-receipts | 群聊已读回执 | [![npm](https://img.shields.io/npm/v/leancloud-realtime-plugin-groupchat-receipts.svg?style=flat-square)](https://www.npmjs.com/package/leancloud-realtime-plugin-groupchat-receipts) | [API docs](https://leancloud.github.io/js-realtime-sdk/plugins/groupchat-receipts/docs/) | | leancloud-realtime-plugin-webrtc | WebRTC 客户端 | [![npm](https://img.shields.io/npm/v/leancloud-realtime-plugin-webrtc.svg?style=flat-square)](https://www.npmjs.com/package/leancloud-realtime-plugin-webrtc) | [API docs](https://leancloud.github.io/js-realtime-sdk/plugins/webrtc/docs/) | ## 支持 - 在使用过程中遇到了问题时 - 如果你是商用版用户，请新建一个工单。 - 也可以在 [论坛](https://forum.leancloud.cn/) 提问、讨论。 ## 贡献 如果你希望为这个项目贡献代码，请按以下步骤进行： 1. Fork 这个项目，clone 到本地 1. 在目录中执行 `npm install` 安装所需 Node.js 依赖包 1. 编码，更新测试用例 1. 运行 `npm test` 确保测试全部 pass 1. 提交改动，请遵循 [conversational commit message 风格](http://www.ruanyifeng.com/blog/2016/01/commit_message_change_log.html) 1. 发起 Pull Request 至 master 分支 ### 项目的目录结构 ``` . ├── demo ├── deploy.sh // 部署 gh-pages 分支 ├── release.sh // 部署 dist 分支 ├── dist // 打包产出 (dist 分支) │   ├── core.js // 核心逻辑（不包含运行时） │   ├── im.js // IM（不包含运行时） │   ├── im-browser.js // 浏览器用 │   ├── im-weapp.js // 微信小程序用 │   └── im-node.js // node 用 ├── proto │   ├── message-compiled.js // 使用 pbjs 生成的 message 类 │   ├── message.js // ES6 wrapper │   └── message.proto // proto 原始文件 ├── src // 源码 │   └── index.js // 打包入口 ├── test // 测试用例 │ ├── browser // 浏览器测试入口 │ └── index.js // 测试入口 └── plugins    ├── typed-messages // leancloud-realtime-plugin-typed-messages package    └── webrtc // leancloud-realtime-plugin-webrtc package ``` ### Architecture SDK 分为连接层与应用层两部分，只存在应用层对连接层公开 API 的调用，连接层对开发者不可见。 #### 连接层 - `WebSocketPlus`：封装了 WebSocket。相比 w3 WebSocket，增加了以下特性： - 是一个有限状态机 - 实现了 [Node.js EventEmitter 接口](https://nodejs.org/api/events.html) - 超时与自动重连机制 - url 参数支持 Promise 及备用地址 - `Connection`：继承自 `WebSocketPlus`，增加了与业务相关的功能： - 根据 subprotocol 自动处理发送与接收的消息，应用层发送接收的均是 ProtoBuf Message 类 - `send` 接口返回 Promise，在 server 回复后才算 send 成功 - 实现了应用层 ping/pong #### 应用层 - `Realtime`：开发者使用 SDK 的入口，负责访问 router、创建 connection、创建与管理 clients、创建 messageParser（管理消息类型）、监听 connection 的消息并 dispatch 给对应的 client - `Client`：所有的 clients 共享一个 connection - `IMClient`：对应即时通讯中的「用户」，持有 connection 与 conversations，负责创建管理将收到的消息处理后在对应 conversation 上派发，所有的 IMClients 共享一个 messageParser - `MessageParser` 消息解析器，负责将一个 JSON 格式的消息 parse 为对应的 Message 类 - `Conversation`：实现对话相关的操作 - `ConversationQuery`：对话查询器 - `Messages` - `AVMessage`：接口描述，生成文档用 - `Message`：消息基类 - `TypedMessage`：类型消息基类，继承自 `Message` - `TextMessage`：文本消息，继承自 `TypedMessage` - 其他富媒体消息类（`FileMessage` 及其子类、`LocationMessage`）由于依赖 leancloud-storage，作为另一个独立 package 发布 ### 开启调试模式 #### Node.js ```bash export DEBUG=LC* ``` #### 浏览器 ```javascript localStorage.setItem('debug', 'LC*'); ``` ## Develop Workflow ### 本地开发 更新 .proto 后请运行 ``` npm run convert-pb ``` 测试 ``` npm run test:node -- --grep KEYWORDS ``` 浏览器测试 ``` npm run test:browser-local ``` 编译 ``` npm run build ``` ### 持续集成 合并 PR 到 master 分支后持续集成会自动运行 `npm build` 与 `npm run docs`，然后将 dist 目录推送到 dist 分支，将文档与 demo 推送到 gh-pages。 ## Release Process Workflow 0. 遵循 semver 提升 `package.json` 中的版本号 1. `npm run changelog` 生成新的 `changelog.md`，润色之 1. Commit `package.json`，`changelog.md` 1. Push to remote `master` branch 1. 等待持续集成 pass 1. 使用 GitHub 基于 dist 分支生成 pre-release 包（for bower） 1. Fetch and checkout remote `dist` branch 并确认该提交的内容是即将发布的版本 1. npm publish（`npm publish`，需 npm 协作者身份），如果是 pre-release 版本需要带 next tag 1. 如有更新，在 npm 上发布各个 plugin --- _Source: https://npm.io/package/leancloud-realtime · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._