Getting Started - React (BETA)

The Chatkit React SDK builds on top of the general Chatkit JavaScript SDK to automatically inject Chatkit data and callbacks into your React application

This SDK is in Beta. We are expecting to make breaking changes in the future. If you have any feedback/suggestions please get in touch.

Looking to make a one-to-one chat? Jump straight to our guide for creating one-to-one chat with React.

Preparation

Installing dependencies

Create a new React project:

1
2
npx create-react-app chatkit-getting-started
cd chatkit-getting-started

Then install the Chatkit React SDK:

  • Yarn
  • NPM
1
yarn add @pusher/chatkit-client-react

Creating a Chatkit instance

Head on to dash.pusher.com, and click on the Create button in the Chatkit box. Give your instance a name.

name your instance

Clicking the create button will take you to your instance’s dashboard. Click on the Credentials tab under your instance name, where you’ll see 2 long strings - Instance Locator, and Secret Key.
They are unique for each instance. The instance locator lets your app connect to your Chatkit instance, and you will use the Secret Key on the server to authenticate clients.

your credentials

Creating users with the Instance Inspector

Next, you will need to add some test users to your instance (Alice and Bob). Open the console tab for your instance on the dashboard and click the CREATE USER button.

screenshot of selecting the 'create user' button in the instance inspector

Create two new users, one with ID alice and name Alice A and the other with ID bob and name Bob B:

screenshot of the instance inspector after both users have been added

Creating a React component

Open src/App.js and create a component called WelcomeMessage:

import React from "react"
import logo from './logo.svg';
import "./App.css"
 
function App() {
  return (
    <div className="App">
      <header className="App-header">
        <img src={logo} className="App-logo" alt="logo" />
        <p>
          Edit <code>src/App.js</code> and save to reload.
        </p>
        <a
          className="App-link"
          href="https://reactjs.org"
          target="_blank"
          rel="noopener noreferrer"
        >
          Learn React
        </a>
      </header>
      <WelcomeMessage />
    </div>
  )
}
 
const WelcomeMessage = props => {
  return <div>Hello Chatkit!</div>
}
 
export default App

Check it works

Start the app with

  • Yarn
  • NPM
1
yarn start

and open it in your browser – you should see the welcome message “Hello Chatkit!”.

A word on Token Providers

To make any request to the Chatkit API, you will require a valid token, that is signed by your secret key. You will normally generate these tokens in your backend, using the server SDK.
In the client you can use an instance of TokenProvider. It takes the url of an endpoint to request tokens from. The Chatkit SDK needs one of these tokens to perform any action with the Chatkit API.

For now, we provide you with a Test Token Provider endpoint, that you can enable for testing and development purposes.

To enable the test token provider, you need to check the box in the dashboard, in the Credentials tab, below the instance locator and the key - as you can see in the screenshot below. The dashboard generates you a Test Token Provider endpoint.

You can read more about how Chatkit performs authentication in the docs.

test token provider inspector

Adding a Token Provider to your app

Create a new TokenProvider instance. Copy the test token provider URL from the dashboard and paste it in the TokenProvider constructor:

import React from "react"
import "./App.css"
import {
  ChatkitProvider,
  TokenProvider,
  withChatkit,
} from "@pusher/chatkit-client-react"
 
const tokenProvider = new TokenProvider({
  url: "<YOUR_TEST_TOKEN_PROVIDER_URL>",
});
 
function App() {
/* Rest of file truncated */

Connecting to Chatkit

You can connect to Chatkit using the ChatkitProvider. This component will inject your connection to Chatkit into all Chatkit-compatible child components.

You will need to pass the following props to the ChatkitProvider:

  • instanceLocator: A unique string which helps clients find your Chatkit instance. This can be found in the Credentials tab in the dashboard
  • tokenProvider: A reference to the TokenProvider you created in the previous step
  • userId: The ID of the user you would like to connect as. In a real application this would be loaded from your authentication system. In this example, the ID will be hard-coded.

import React from "react"
import "./App.css"
import {
  ChatkitProvider,
  TokenProvider,
  withChatkit,
} from "@pusher/chatkit-client-react"
 
const instanceLocator = "<YOUR_INSTANCE_LOCATOR>"
const userId = "alice"
 
const tokenProvider = new TokenProvider({
  url: "<YOUR_TEST_TOKEN_PROVIDER_URL>",
})
 
function App() {
  return (
    <div className="App">
      <WelcomeMessage />
      <ChatkitProvider
        instanceLocator={instanceLocator}
        tokenProvider={tokenProvider}
        userId={userId}
      >
        <WelcomeMessage />
      </ChatkitProvider>
    </div>
  )
}
/* Rest of file truncated */

Wrapping the welcome message component

Next, wrap the WelcomeMessage component with the withChatkit higher-order component you imported earlier. This injects Chatkit properties for use in the component. Here were using props.chatkit.isLoading and props.chatkit.currentUser to display the name of the currently connected user. See the React SDK reference for full details.

import React from "react"
import "./App.css"
import {
  ChatkitProvider,
  TokenProvider,
  withChatkit,
} from "@pusher/chatkit-client-react"
 
const instanceLocator = "<YOUR_INSTANCE_LOCATOR>"
const userId = "alice"
 
const tokenProvider = new TokenProvider({
  url: "<YOUR_TEST_TOKEN_PROVIDER_URL>",
})
 
function App() {
  return (
    <div className="App">
      <ChatkitProvider
        instanceLocator={instanceLocator}
        tokenProvider={tokenProvider}
        userId={userId}
      >
        <WelcomeMessage />
      </ChatkitProvider>
    </div>
  )
}
 
const WelcomeMessage = props => {
  return <div>Hello Chatkit!</div>
}
const WelcomeMessage = withChatkit(props => {
  return (
    <div>
      {props.chatkit.isLoading
        ? 'Connecting to Chatkit...'
        : `Hello ${props.chatkit.currentUser.name}!`}
    </div>
  );
});
 
export default App

Check it works

Open the app again - if you are greeted as Alice, you have successfully connected to Chatkit 🎉

Next steps