chat-engine
    TypeScript icon, indicating that this package has built-in type declarations

    0.9.21 • Public • Published

    PubNub ChatEngine is an object oriented event emitter based framework for building chat applications in Javascript. It reduces the time to build chat applications drastically and provides essential components like typing indicators, online presence monitoring and message history out of the box.

    The real time server component is provided by PubNub. ChatEngine is designed to be extensible and includes a plugin framework to make adding new features simple.

    Build Status Codacy Badge Codacy Badge

    Browser Support

    ChatEngine is compiled with babel and supports these browsers and create-react-app.

    Getting Started

    Check out the getting started guide.

    Videos

    Docs

    You can find the full docs on the full documentation website. Concepts are linked below for convenience.

    Concepts

    • Me - It's you dummy. The user that represents the current application.
    • Users and State - Explains how to interact with other users using ChatEngine and get additional information about them.
    • Chats - ChatEngine's bread and butter. These are isolated rooms that users can talk to each other in.
    • Events - Events are things that happen in a chat. Like message or image_upload for example.
    • Event Payload - The data that comes with an event. Includes things like who sent the event and what chat it was sent to.
    • Namespaces - ChatEngine has a lot of events, so we use name spacing to isolate them.
    • Wildcards - Get all the events of a single namespace, like $.online.* to get all types of online events.
    • Search - Retrieve old events that happened in the past. Usually done when your application boots up to show what happened before.
    • Global Chat - The chat that all users connect to. It's used for state management and application wide events.
    • Online List - Get all the users online in the chat room.
    • Authentication - How to use auth keys to identify your users and protect access to channels.
    • Privacy - Every user has a special feed chat that only they can publish to, and a direct chat that nobody else can read from. Outlines other ways of handling permissions as well.
    • Private Chats - Create private chats that nobody else can join.
    • Templating - How ChatEngine works with other frameworks like React, Angular, jQuery, and plain ol' Javascript.
    • Errors - Sometimes things don't go as planned, here's how you can catch errors gracefully.
    • Debugging - How to use the built-in utilities for logging events and network requests.
    • Plugins - Drop in extra functionality, like emojii or typing indicators with plugins.
    • Building a Plugin - If what you need doesn't exist, it's easy to build yourself. Share it with us!
    • PubNub Functions - ChatEngine uses PubNub functions as a server component and details about that can be found here.
    • PubNub Channel Topology - Describes what PubNub channels ChatEngine is using under the hood.

    Resources

    Javascript

    • Chat - Really simple chat example. The "hello world" of ChatEngine.
    • Online List - No chats, just renders who is online. See the Kitchen Sinks for how to combine this with private chats.

    React Native + Mobile

    React

    • React - Bare bones react web example.

    Vue

    • Vue Guide - Guide on using ChatEngine and Vue together. Uses the following resources.
    • Vue Example - Full featured ChatEngine vue example.
    • Vue Plugin - ChatEngine plugin for vue.

    Angular

    • Angular Simple - Angular "Hello World" app. Simple app that uses a custom Angular plugin to render when anything updates.
    • Angular Kitchen Sink - The largest demo app out there, almost a complete Desktop Team Chat clone (Slack, Stride, Flowdock). Persistent URLS and renders into a real desktop app with Electron!

    jQuery

    • jQuery Simple - jQuery ChatEngine "Hello World" app. Simple app where everyone chats together.
    • jQuery Kitchen Sink - Huge example that uses most ChatEngine features. Has an online list that spawns new chats when you click on usernames.

    3rd Party Authentication

    NodeJS + Chatbot

    • NodeJS ChatBot - An example bot that responds to messages and emulates typing. Works with the jQuery Kitchen Sink example by default.

    Other Resources

    Plugins

    Check out the jQuery Kitchen Sink and Angular Kitchen Sink examples to see plugins in action.

    Image Uploads

    Uses UploadCare service to uplaod images and render them in chats. Example.

    Markdown Support

    Render Markdown in HTML when receiving messages. Example.

    Mute Users

    Allows the current user to stop receiving events from other users. Example.

    Online User Search

    A simple way to search through the list of users online in the chat. Example.

    Typing Indicator

    Provides convenience methods that fire when a user starts or stops typing. Example

    Unread Messages

    Allows you to mark a chat as being in the background and increments a counter as events are sent to it. Example.

    Desktop Notifications

    Uses HTML5 Notification API to send "toaster" updates.

    Emoji Support

    Uses images as fallback for devices that might not yet support 💩.

    Event Status and Read Receipts

    Emits additional events when someone reads a receives and/or reads a message.

    Gravatar Support

    Uses Gravatar service to create an avatar based on user state information.

    Random Usernames

    A plugin that gives every use a random username combining a color and an animal.

    Development

    Cloning

    Clone repos (chat-engine and plugins).

    All repos should be siblings of one another. This is required for rendering docs properly.

    chat-engine
    chat-engine-desktop-notifications
    chat-engine-emoji
    chat-engine-examples
    //...
    

    Setting up environment

    nvm use v6
    

    run http-server from my /development directory which has all chat-engine repos:

    cd chat-engine

    node server.js

    load http://localhost:8080 in browser and navigate to /chat-engine-examples/jquery/kitchen-sink

    Compiling

    Run gulp to compile, but you should probably run gulp watch to get consistent changes.

    Running Tests

    You will need to assign environment variables PUB_KEY_0 and SUB_KEY_0 to your own PubNub keys. Add these variables into your .bashrc or .zshrc.

    # pubnub chatengine keys 
    export PUB_KEY_0="YOUR PUBNUB PUBLISH KEY"
    export SUB_KEY_0="YOUR PUBNUB SUBSCRIBE KEY"

    Then, in the root folder run:

    gulp test
    

    PubNub Functions and Account Setup

    You can find the scripts for the PubNub Automagic Setup here: https://github.com/pubnub/chat-engine-setup.

    Releasing a patch (chat engine and plugins)

    npm version patch && git push origin master --tags
    

    Install

    npm i chat-engine

    DownloadsWeekly Downloads

    1,312

    Version

    0.9.21

    License

    none

    Unpacked Size

    1.21 MB

    Total Files

    39

    Last publish

    Collaborators

    • ajb413
    • crgbaumgart
    • ianjennings
    • madisonsmith
    • pubnub
    • raimondi1337
    • stephenlb