@connectycube/chat-widget 0.36.0 → 0.37.0

package/README.md

@@ -0,0 +1,203 @@
+# ConnectyCube Chat Widget
+
+A React component that seamlessly integrates ConnectyCube's real-time chat capabilities into your web applications. This widget offers an out-of-the-box solution for embedding chat features—such as instant messaging, user presence, and file sharing—without the overhead of building a complete chat system from scratch.
+
+## Overview
+
+The ConnectyCube Web Chat Widget for React is designed to simplify the process of adding chat functionality to your React apps. With a few configuration steps and minimal code, you can quickly enable robust, real-time communication powered by ConnectyCube. Key benefits include:
+
+- **Easy Integration:** Plug the widget into your existing React projects.
+- **Customizable Interface:** Adjust the look and feel to match your brand.
+- **Real-Time Messaging:** Leverage ConnectyCube's reliable backend for instant communication.
+- **Responsive Design:** Works seamlessly on both desktop and mobile devices.
+- **Modular and Extensible:** Adapt the widget to your unique requirements.
+
+## Demo
+
+- React: <https://connectycube-chat-widget.onrender.com>
+- Vanilla JS: <https://connectycube-chat-widget-vanilla.onrender.com>
+
+Split-view chat widget:
+
+<kbd><img alt="ConnectyCube chat widget, split view image demo" src="https://developers.connectycube.com/images/chat_widget/chat-widget-1.png" width="400" /></kbd>
+
+Single-view chat widget:
+
+<kbd><img alt="ConnectyCube chat widget, single view image demo" src="https://developers.connectycube.com/images/chat_widget/chat-widget-2.png" width="400" /></kbd>
+
+## Documentation
+
+<https://developers.connectycube.com/js/chat-widget>
+
+## Installation
+
+### React
+
+```bash
+# npm
+npm install @connectycube/chat-widget
+
+# yarn
+yarn add @connectycube/chat-widget
+```
+
+### Vanilla JS
+
+Add the following scripts on your html page somewhere in `head` element:
+
+```html
+<script src="https://unpkg.com/react@18/umd/react.production.min.js" crossorigin></script>
+<script src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js" crossorigin></script>
+<script src="https://unpkg.com/connectycube@4/dist/connectycube.min.js"></script>
+<script src="https://unpkg.com/@connectycube/chat-widget@latest/dist/index.umd.js"></script>
+```
+
+## Usage
+
+### Before you start
+
+Before you start, make sure:
+
+1. You have access to your ConnectyCube account. If you don’t have an account, [sign up here](https://admin.connectycube.com/register).
+2. An app created in ConnectyCube dashboard. Once logged into [your ConnectyCube account](https://admin.connectycube.com/), create a new application and make a note of the app credentials (**App ID** and **Authorization Key**) that you’ll need for authentication.
+
+### Display widget
+
+#### React
+
+Import and place the following component in your app:
+
+```js
+import ConnectyCubeChatWidget from "@connectycube/chat-widget";
+
+...
+
+<ConnectyCubeChatWidget
+  appId="111"
+  authKey="11111111-2222-3333-4444-55555555"
+  config={{ debug: { mode: 1 } }}
+  userId="112233"
+  userName="Samuel"
+  showOnlineUsersTab={false}
+  splitView={true}
+/>
+
+// userName - how other users will see your user name
+// userId - a User Id from your system
+```
+
+See chat widget code samples <https://github.com/ConnectyCube/connectycube-chat-widget-samples/tree/main/react-ts> as a reference for faster integration.
+
+##### React version support
+
+Since v0.35.0, the default build of the widget targets React 19 and is provided as an ESM module.
+For React 18 projects, use the dedicated ESM-only build:
+
+```js
+// v0.35.0 and later:
+import ConnectyCubeChatWidget from '@connectycube/chat-widget'; // default: React 19
+import ConnectyCubeChatWidget from '@connectycube/chat-widget/react19'; // explicit React 19 build
+import ConnectyCubeChatWidget from '@connectycube/chat-widget/react18'; // dedicated React 18 build
+
+// v0.34.0 and earlier:
+import ConnectyCubeChatWidget from '@connectycube/chat-widget'; // default: React 18
+import ConnectyCubeChatWidget from '@connectycube/chat-widget/react19'; // React 19 build
+```
+
+#### Vanilla JS
+
+Place the following script in your app:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <!-- ... -->
+  </head>
+  <body>
+    <!-- ... -->
+    <!-- @connectycube/chat-widget - start -->
+    <script src="https://unpkg.com/react@18/umd/react.production.min.js" crossorigin></script>
+    <script src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js" crossorigin></script>
+    <script src="https://unpkg.com/connectycube@4/dist/connectycube.min.js"></script>
+    <script src="https://unpkg.com/@connectycube/chat-widget@latest/dist/index.umd.js"></script>
+    <script>
+      const chatWidgetContainer = document.createElement('div');
+      chatWidgetContainer.id = 'ConnectyCube_chat-widget';
+      document.body.appendChild(chatWidgetContainer);
+      const props = {
+        appId: 111,
+        authKey: '11111111-2222-3333-4444-55555555',
+        config: { debug: { mode: 1 } },
+        userId: '112233', // a User Id from your system
+        userName: 'Samuel', // how other users will see your user name
+        showOnlineUsersTab: false,
+        splitView: true,
+        hideWidgetButton: false,
+        onOpenChange: (open) => {
+          console.log('Chat widget is open:', open);
+        },
+        onUnreadCountChange: (count) => {
+          console.log('Unread messages count:', count);
+        },
+      };
+      ReactDOM.createRoot(chatWidgetContainer).render(React.createElement(ConnectyCubeChatWidget, props));
+
+      // use the code below as an example to toggle the chat widget visibility state for custom button
+      document.getElementById('someCustomButton').addEventListener('click', () => {
+        ConnectyCubeChatWidget.toggle();
+      });
+    </script>
+    <!-- @connectycube/chat-widget - end -->
+  </body>
+</html>
+```
+
+See chat widget code samples <https://github.com/ConnectyCube/connectycube-chat-widget-samples/tree/main/vanilla> as a reference for faster integration.
+
+## Props
+
+See all available props <https://developers.connectycube.com/js/chat-widget/#props>
+
+## Recipes
+
+See all available recipes <https://developers.connectycube.com/js/chat-widget/#recipes>
+
+## SSR (Server-Side Rendering) Guide
+
+When using `@connectycube/chat-widget` in SSR environments (e.g., Next.js, Remix), some native Node.js modules like events may cause errors due to differences between Node and browser environments. Here are recommendations to ensure smooth SSR integration:
+
+### Usage
+
+```bash
+# npm
+npm install @connectycube/chat-widget
+npx connectycube patch-ssr      # Apply SSR patches
+# npx connectycube revert-ssr   # Revert SSR patches
+
+# yarn
+yarn add @connectycube/chat-widget
+yarn connectycube patch-ssr     # Apply SSR patches
+# yarn connectycube revert-ssr  # Revert SSR patches
+```
+
+The `connectycube` CLI will be available as part of the `connectycube` package, which is installed automatically as a dependency of `@connectycube/chat-widget`. This script applies fixes to make the SDK compatible with SSR environments.
+
+## Have an issue?
+
+Join our [Discord](https://discord.com/invite/zqbBWNCCFJ) community to get real-time help from our team
+
+## Community
+
+- [Blog](https://connectycube.com/blog)
+- X (twitter)[@ConnectyCube](https://x.com/ConnectyCube)
+- [Facebook](https://www.facebook.com/ConnectyCube)
+- [Medium](https://medium.com/@connectycube)
+- [YouTube](https://www.youtube.com/@ConnectyCube)
+
+**Want to support our team**:<br>
+<a href="https://www.buymeacoffee.com/connectycube" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-blue.png" alt="Buy Me A Coffee" style="height: 60px !important;width: 217px !important;" ></a>
+
+## Changelog
+
+<https://github.com/ConnectyCube/connectycube-chat-widget-samples/blob/main/CHANGELOG.md>