Forem: ablydevin

Building a realtime chat app with Next.js and Vercel

ablydevin — Tue, 06 Feb 2024 10:55:35 +0000

This post was originally written by Devin Rader on the Ably Blog

This post will walk through the creation of a realtime chat application with Next.js and deploying it to Vercel.

You'll learn how to:

Create a brand new Next.js application
Adding real-time functionality with Ably
Create a Next.js Vercel Serverless API
Use React Functional components and React Hooks with Ably
Host your app on Vercel

Check out a running version of the app or fork the app on GitHub.

WebSockets in Vercel with Ably

Vercel allows users to deploy Serverless Functions, which are essentially just blocks of code that provide a response to an HTTP request. However, these functions have a maximum execution timeout, which means that it is not possible to maintain a WebSocket connection this way.

This is where Ably comes in. The client can connect to an Ably Channel and send and receive messages on it to add realtime functionality to your app by managing your WebSocket connections for you.

We’ll start by going over how to build an app that uses realtime functionality. If you prefer, you can jump straight to how to use Ably with Vercel.

Take a look at some of the challenges of implementing a reliable and highly-performant client-side WebSocket solution for JavaScript apps.

// Detect dark theme var iframe = document.getElementById('tweet-1366799967088697344-205'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1366799967088697344&theme=dark" }

What are we going to build?

We’re building a realtime chat app that runs in the browser. It will be built upon the Next.js create-next-app template and contain a React component that uses Ably to send and receive messages. We'll also write a Next.js serverless function that will be used to connect to Ably.

The UI of the chat app we'll build. It is a window with speech bubbles for text.

Dependencies

To build this app, you’ll need:

An Ably account for sending messages: Create an account with Ably for free.
A Vercel account for hosting on production: Create an account with Vercel for free.
Node 16.14 or greater: Install Node.

Once you have your Ably account you'll need an API key to authenticate with the Ably Service. To get an API key:

Visit your app dashboard and click on "Create New App".
Give the new app a name.
Copy the Private API key once the app has been created. Keep it safe, this is how you will authenticate with the Ably service.

Vercel provides Next.js command line tools to help us. They don't need to be installed on your system as they're executed using npx.

Scaffolding the Next.js Chat App

Start building the chat application by using create-next-app to scaffold a new Next.js-based application. In your terminal, type:

npx create-next-app@latest

Answer the prompts as follows:

What is your project named? nextjs-chat-app
Would you like to use TypeScript? No
Would you like to use ESLint? Yes
Would you like to use Tailwind CSS? No
Would you like to use `src/` directory? No
Would you like to use App Router? (recommended) Yes
Would you like to customize the default import alias? No
What import alias would you like configured? @/*

After the prompts, create-next-app will create a folder with your project name and install the required dependencies. Change directories into your application directory:

cd nextjs-chat-app

Next, create a file called .env in the root of the directory. This is where we'll put the project's environment variables. Add your Ably API key to the .env file:

ABLY_API_KEY=your-ably-api-key:goes-here

Test that the application runs correctly by running the following command:

npm run dev

The Next.js dev server will spin up and you'll see an default Next.js starter app. This is what we'll build our chat app on top of.

Realtime pub/sub messaging with Ably

The chat app will use Ably for Publish/Subscribe (Pub/Sub messaging between the users. Pub/Sub is a popular pattern used for realtime data delivery. The app will be able to send, or publish, messages over an Ably Channel. Clients that use the app will be subscribed to the channel and able to receive messages. We'll build a UI to create messages to be sent and to display messages as they are received.

The realtime chat app architecture

The topology of our Next.js app will look like this:

├─ .env
├─ .gitignore
├─ package-lock.json
├─ package.json
├─ README.md   
|    
├─── components
│     ├─ Chat.jsx
|     ├─ ChatBox.jsx
│     ├─ ChatBox.module.css
|
├─── app
│    ├─ globals.css
│    ├─ layout.js
│    ├─ page.js
│    │   
│    └─── api
│          └─ route.js
│           
└─── public

/app/page.js is the home page
/app/api/route.js is our Ably token authentication API
/components/Chat.jsx is the main chat host component
/components/ChatBox.jsx the component that contains the actual chat UI
/components/ChatBox.module.css contains the styles for the chat component

Let's walk through how this application is built.

Authenticating an Ably client

There are a number of ways to authenticate an Ably client. For our application, we’ll use token authentication. Token authentication uses a trusted device with an API key, in our case an API route that we’ll build using Next.js, to issue time-limited tokens to untrusted clients.

In version 13, Next.js introduced the new App Router. Built on React Server Components it supports shared layouts, nested routing, loading states, error handling, and more including API routes via its Route Handler feature. Let's build that API route.

Start by installing the Ably npm package in the root of your new app:

npm install ably

Next, create a file called ./app/api/route.js. Add the following code:

import Ably from "ably/promises";

export async function GET(request) {
    const client = new Ably.Realtime(process.env.ABLY_API_KEY);
    const tokenRequestData = await client.auth.createTokenRequest({ clientId: 'ably-nextjs-demo' });
    return Response.json(tokenRequestData);
};

This function uses the Ably SDK to create a tokenRequest with your API key. The token will be used later - it allows you to keep your "real" API key safe while using it in the Next.js app. By default, this API is configured to be available on http://localhost:3000/api/. We're going to provide this URL to the Ably SDK in our client to authenticate with Ably.

Next.js Server vs Client Components

Before we start creating pages in our application, it's important to understand how Next.js renders content. The framework supports multiple rendering methods including server-side rendering (SSR), static site rendering (SSG), and client-side rendering (CSR). There are many pros and cons to each rendering method (too many to cover in this post) so if these concepts are new to you, Google’s web.dev site has a very good introduction to rendering on the web that can help you understand rendering options.

Next.js defaults to server-side rendering meaning the page HTML is generated on the server for each request and sent to the browser. This means that by default when you create a new component in your React app, you are creating a Server Component.

Server Components offer a lot of benefits, but one drawback is that they don’t have access to browser APIs. To allow you to create components that can access those APIs Next.js also includes the ability to create Client Components.

To indicate that you want a component to be a Client Component, you use React’s use client directive at the top of your component. Doing this tells React that it should render the component on the client side.

When using Next.js however even for components marked with use client the framework will try to render a static preview of the component on the server. This can cause problems when creating a component that attempts to instantiate an instance of an Ably client.

To avoid this, you can use Lazy Loading to defer loading of Client Components.

Building the components

Pages in Next.js are React components, so the app/page.jshome page is the React component that contains the page layout.

Open page.js and replace the default scaffolded content with this markup:

import Head from 'next/head';

export default function Home() {
  return (
    <div className="container">
      <Head>
        <title>Realtime Chat App with Ably, NextJS and Vercel</title>
        <link rel="icon" href="https://static.ably.dev/motif-red.svg?nextjs-vercel" type="image/svg+xml" />
      </Head>
      <main>
        <h1 className="title">Next.js Chat Demo</h1>
        {/* Insert Chat Component */}
      </main>
      <footer>
        Powered by&nbsp;<a href="https://vercel.com" target="_blank" rel="noopener noreferrer">Vercel</a>&nbsp;and&nbsp;<a href="https://ably.com" rel="noopener noreferrer">Ably</a>
        <a href="https://github.com/ably-labs/NextJS-chat-app" className="github-corner" aria-label="View source on GitHub">
          <svg width="80" height="80" viewBox="0 0 250 250" className="svg" aria-hidden="true">
            <path d="M0,0 L115,115 L130,115 L142,142 L250,250 L250,0 Z"></path>
            <path d="M128.3,109.0 C113.8,99.7 119.0,89.6 119.0,89.6 C122.0,82.7 120.5,78.6 120.5,78.6 C119.2,72.0 123.4,76.3 123.4,76.3 C127.3,80.9 125.5,87.3 125.5,87.3 C122.9,97.6 130.6,101.9 134.4,103.2" fill="currentColor" className="octo-arm"></path><path d="M115.0,115.0 C114.9,115.1 118.7,116.5 119.8,115.4 L133.7,101.6 C136.9,99.2 139.9,98.4 142.2,98.6 C133.8,88.0 127.5,74.4 143.8,58.0 C148.5,53.4 154.0,51.2 159.7,51.0 C160.3,49.4 163.2,43.6 171.4,40.1 C171.4,40.1 176.1,42.5 178.8,56.2 C183.1,58.6 187.2,61.8 190.9,65.4 C194.5,69.0 197.7,73.2 200.1,77.6 C213.8,80.2 216.3,84.9 216.3,84.9 C212.7,93.1 206.9,96.0 205.4,96.6 C205.1,102.4 203.0,107.8 198.3,112.5 C181.9,128.9 168.3,122.5 157.7,114.1 C157.9,116.9 156.7,120.9 152.7,124.9 L141.0,136.5 C139.8,137.7 141.6,141.9 141.8,141.8 Z" fill="currentColor" className="octo-body"></path></svg>
            </a>
      </footer>
    </div>
  )
}

Next, in the same app directory, locate the globals.css file and replace its contents with the basic CSS styles we’ll use in our application which you can find in the projects GitHub repository.

Run the app. You should see this:

Next, in the root of your application create a new components folder and within create a new React component file named Chat.jsx. Scaffold the initial component using the code below:

'use client'

import * as Ably from 'ably';
import { AblyProvider } from 'ably/react';

export default function Chat() {

  const client = Ably.Realtime.Promise({ authUrl: '/api' })

  return (
    <AblyProvider client={ client }>
    </AblyProvider>
  )
}

This component is marked with the use client directive. It will be the boundary between SSR components and CSR components.

The component imports the Ably and Ably React paths from the Ably package and uses them to create a new instance of an Ably client, authenticating it against the API endpoint we created above and then providing that instance to an <AblyProvider> component. <AblyProvider> will retain the client in the application context so that any child component can access it.

To use our new Chat component we’ll dynamically import it into our home page at the top of page.js:

import Head from 'next/head';
import dynamic from 'next/dynamic';

const Chat = dynamic(() => import('../components/Chat'), {
  ssr: false,
})

And add the component to the markup:

<main>
  <h1 className="title">Next.js Chat Demo</h1>
  <Chat />
</main>

Validate that the application works properly by running the project again. You won’t see any difference in the UI yet, but we’ll get to that in the next section.

Writing the chat component logic

The chat app logic is contained inside a new ChatBox component. To create this start by creating two new files: ChatBox.jsx which will hold the React component and ChatBox.module.css, a stylesheet we’ll use to style the ChatBox component.

As we did above with globals.css you can get the CSS needed to style the ChatBox component by copying into it the styles which you can find in the projects Github repository.

Next, open the Chatbox.jsx file and add the import statements we'll need at the top of the file:

import React, { useEffect, useState } from 'react';
import { useChannel } from "ably/react";
import styles from './ChatBox.module.css';

Define a ChatBox function that is exported as a React component. Add to the function variables to store references to some of the HTML elements in the code.

export default function ChatBox() {

  let inputBox = null;
  let messageEnd = null;

  return ()
}

Set up the state properties used in the component:

const [messageText, setMessageText] = useState("");
const [receivedMessages, setMessages] = useState([]);     
const messageTextIsEmpty = messageText.trim().length === 0;

messageText will be bound to a textarea element where messages can be typed
receiveMessages stores the on-screen chat history
messageTextIsEmpty is used to disable the send button when the textarea is empty

Now we'll use the useChannel hook that we imported earlier.
useChannel is a react-hook API for subscribing to messages from an Ably channel. You provide it with a channel name and a callback to be invoked whenever a message is received.

Both the channel instance and the Ably JavaScript SDK instance are returned from useChannel.

const { channel, ably } = useChannel("chat-demo", (message) => {
  const history = receivedMessages.slice(-199);
  setMessages([...history, message]);
});

Here we're computing the state that'll be drawn into the message history. We do that by slicing the last 199 messages from the receivedMessages buffer.

Then we take the message history and combine it with the new message. This means we'll always have up to 199 messages + 1 new message, stored using the setMessages React useState hook.

Next, we need to handle the UI interactions by defining a few functions.

First, there's sendChatMessage, which is responsible for publishing new messages. It uses the Ably Channel returned by the useChannel hook, clears the input, and focuses on the textarea so that users can type more messages:

const sendChatMessage = (messageText) => {
  channel.publish({ name: "chat-message", data: messageText });
  setMessageText("");
  inputBox.focus();
}

Then handleFormSubmission, which is triggered when the submit button is clicked and calls sendChatMessage, along with preventing a page reload:

const handleFormSubmission = (event) => {
  event.preventDefault();
  sendChatMessage(messageText);
}

Finally the handleKeyPress event is wired up to make sure that if a user presses the enter key, while there is text in the textarea, the sendChatMessage function is triggered.

const handleKeyPress = (event) => {
  if (e.charCode !== 13 || messageTextIsEmpty) {
    return;
  }
  sendChatMessage(messageText);
  event.preventDefault();
}

Next, we need to construct the UI elements to display the messages. To do this, we will map the received Ably messages into HTML span elements:

const messages = receivedMessages.map((message, index) => {
  const author = message.connectionId === ably.connection.id ? "me" : "other";
  return <span key={index} className={styles.message} data-author={author}>{message.data}</span>;
});

In order to keep the message box scrolled to the most recent message (the one on the bottom) we'll need to add an empty div element into the message container, which will then be scrolled into view whenever the components re-renders. This is the element that we'll add to the UI later:

<div ref={(element) => { messageEnd = element; }}></div>

We use a useEffect hook along with scrollIntoView() to scroll the message history to the bottom whenever the component renders.

useEffect(() => {
messageEnd.scrollIntoView({ behaviour: "smooth" });
});

Finally, we will write the React component markup with the event handlers all bound to the onChange and onKeyPress events in JSX.

The markup itself is just a few div elements and a form with a textarea for user input. There are two calls to the react ref function, which allows us to capture a reference to the elements when they are rendered so that we can interact with them in JavaScript. The returned markup will look like this:

return (
  <div className={styles.chatHolder}>
    <div className={styles.chatText}>
      {messages}
      <div ref={(element) => { messageEnd = element; }}></div>
    </div>
    <form onSubmit={handleFormSubmission} className={styles.form}>
      <textarea
        ref={(element) => { inputBox = element; }}
        value={messageText}
        placeholder="Type a message..."
        onChange={e => setMessageText(e.target.value)}
        onKeyPress={handleKeyPress}
        className={styles.textarea}
      ></textarea>
      <button type="submit" className={styles.button} disabled={messageTextIsEmpty}>Send</button>
    </form>
  </div>
  )

Add the ChatBox component to the Chat component

'use client'

import * as Ably from 'ably';
import { AblyProvider } from 'ably/react';
import ChatBox from './ChatBox.jsx';

const client = Ably.Realtime.Promise({ authUrl: '/api' })

export default function Chat() {
  return (
    <AblyProvider client={ client }>
      <ChatBox />
    </AblyProvider>
  )
}

Swap over to your browser (make sure you restart the application server if you need to) and you should see a functioning chat application now.

Hosting on Vercel

We're using Vercel as our development server and build pipeline.

The easiest way to deploy Next.js to production is to use the Vercel platform from the creators of Next.js. Vercel is an all-in-one platform with Global CDN supporting static & Jamstack deployment and Serverless Functions.
-- The Next.js documentation

In order to deploy your new chat app to Vercel you'll need to:

Create a GitHub account (if you don't already have one)
Push your app to a GitHub repository
Create a Vercel account
Create a new Vercel app and import your app from your GitHub repository. (This will require you to authorize Vercel to use your GitHub account)
Add your ABLY_API_KEY as an environment variable
Watch your app deploy
Visit the newly created URL in your browser!

Make it your own

There are a few ways that this example could be extended:

Add message history

There is currently no chat history in this demo, you'll only see messages that come in after you join the chat. You could expand this demo by using Ably's rewind feature for up to two minutes of history for free, or with a paid account, for up to ~48 hours.

Add user names

There aren't any usernames sent with the chat messages. This demo could be extended to introduce a username input box, and to add the current username to messages as they're sent.

The demo uses the randomly generated Ably client Id as a unique identifier - which is how it can detect if it is "me" or "someone else" who sent the message.

Let us know

Hope you have enjoyed this tutorial. If you are interested in learning more about realtime in Next.js, check out these resources:

If this tutorial was helpful, or you're using Next.js and Ably in your project, we'd love to hear about it. Drop us a message on Twitter or email us at devrel@ably.com.

How To Enhance AG Grid with Avatars: Building a Collaborative Grid with React and Ably

ablydevin — Fri, 26 Jan 2024 15:52:08 +0000

One of the most common UI elements in software is the tried and true data grid. The idea of organizing data into rows and columns dates back thousands of years. Though human creativity has given us many more ways of displaying data, the humble grid remains a powerful tool in the software developers toolbelt.

Today, however, working with any data, including data in grids, often benefits from collaboration capabilities that allow multiple users to work together on the same data.

In this post I’ll show you how, using the AG Grid component and Ably Spaces, you can create a React application that allows users to see not only who else is currently viewing the grid, but using a Flowbite Avatar Stack component, what row each user currently has selected.

Read on to start building or, if you’d rather jump straight to the finished code, check out this GitHub repo.

Prerequisites

Before you start to build you’ll need to make sure you’ve got an Ably account. You can sign up today for free and use our generous free tier.

We’ll also be using a starter kit application as the base of this application. The starter kit sets up a Vite React project with a single API endpoint used to generate an Ably Token Request. That Token Request allows the Ably client to authenticate itself safely. You can use giget a git cloning tool to clone the repo to your local machine:

npx giget@latest gh:ablydevin/starter-kits/vite-react-javascript realtime-datagrid-demo
cd realtime-datagrid-demo

Once you’ve cloned the starter kit, create a copy of the example environment variables file:

cp .env.example .env.local

And drop your Ably API key in. If you’re not sure where to find your Ably API key, don’t worry we have a great article that walks you through that.

VITE_ABLY_API_KEY="[YOUR_ABLY_API_KEY]"

Once you’ve added your API key you are ready to test the start ket app by running npm run dev. Vite will start a local website and give you a URL you can load in your browser to view the app.

Set up a Space

With the start kit app configured and running the next step is to create a Space within the app. A Space is a virtual area of your application in which realtime collaboration between users can take place. You can have any number of virtual spaces within an application, with a single Space being anything from a web page, a sheet within a spreadsheet, an individual slide in a slideshow, or the entire slideshow itself

In this application, we only need a single Space and it will encompass the entire application.

Start by installing the Ably Spaces SDK:

npm install @ably/spaces

Connect a Space to Ably by creating a SpacesProvider. Import the SpacesProvider and SpaceProvider components into main.jsx:

import Spaces from '@ably/spaces'
import { SpacesProvider, SpaceProvider } from '@ably/spaces/react'

Create a new Spaces object, passing the existing Ably client to it. Wrap the <App /> component inside of a single SpaceProvider, which itself is wrapped inside of the SpacesProvider.

const client = new Ably.Realtime.Promise({ authUrl: "/api/ably/token" });
const spaces = new Spaces(client);

ReactDOM.createRoot(document.getElementById("root")).render(
  <React.StrictMode>
    <AblyProvider client={client}>
      <SpacesProvider client={spaces}>
        <SpaceProvider
          name="datagrid"
          options={{ offlineTimeout: 10_000 }}
        >
          <App />
        </SpaceProvider>
      </SpacesProvider>
    </AblyProvider>
  </React.StrictMode>,
);

Next, import the useSpace hook into App.js

import { useAbly } from "ably/react";
import { useSpace } from '@ably/spaces/react'

The useSpace hook lets you subscribe to the current Space and receive Space state events and get current Space instance.

Use that instance inside of the useEffect hook to register the client as a member of this Space:

function App() {
  const client = useAbly();
  const { space } = useSpace();

  useEffect(() => {
    space?.enter({ clientID: client.auth.clientId });
  }, [space]);

  // ... 
}

Fantastic. We’ve created a Space and registered the client as a member of that Space. Soon we’ll use the Spaces SDK to learn about other members of the Space and display them in our application.

Add an AG Grid

Next let's add an AG Grid component to our application, provide it with some data, and configure it to be able to display the Space members in each grid row.

Use npm to install AG Grid Community, AG Grid React, and Immer, a package that will help us work with immutable state more conveniently.

npm install ag-grid-community ag-grid-react immer use-immer

In App.js, import the AgGridReact component and useImmer hook. Now is also a good time to import the AG Grid CSS styles.

import { AgGridReact } from "ag-grid-react";
import { useImmer } from "use-immer";

import "ag-grid-community/styles/ag-grid.css"; // Core grid CSS, always needed
import "ag-grid-community/styles/ag-theme-alpine.css"; // Optional theme CSS

Next, create an array that contains the grid data. Here we’re using some made-up auto price data, but you could use whatever you want.

const [rowData, updateRowData] = useImmer([
  {
    id: "a",
    make: "Toyota",
    model: "Celica",
    price: 35000,
    rowMembers: []
  },
  {
    id: "b",
    make: "Ford",
    model: "Mondeo",
    price: 32000,
    rowMembers: []
  },
  {
    id: "c",
    make: "Porsche",
    model: "Boxter",
    price: 72000,
    rowMembers: []
  },
]);

Each object in our data array contains four properties:

id: This is a unique identifier - if this was a database it would be auto-generated.
make: The make of the auto.
model:The model of the car.
price:The price of the car.
rowMembers:An array used to hold the ID’s of Space members.

Note that we’re using the useImmer hook to store the array. As mentioned earlier, Immer simplifies working with immutable data. In our case, it will make it much easier to mutate the rowMembers arrays as users select different grid rows.

Now define an array that contains the grid column definitions. The make, model, and price columns are straightforward, but displaying the row ID and row members is a little more complicated.

const [columnDefs, setColumnDefs] = useState([
  { headerName: "Row ID", valueGetter: "node.id" },
  {
    field: "rowMembers",
    cellRenderer: (props) => {
      return (
        <>
          {props.value.length > 0 ? (
            <div>{props.value.toString()}</div>
          ) : (
            <div>None</div>
          )}
        </>
      );
    },
  },
  { field: "make" },
  { field: "model" },
  { field: "price" },
]);

To get the unique ID of each row you use the valueGetter property to get the ID assigned to each node or row. AG Grid can auto-generate those ID’s or like in our case, use the ID that we are providing in each data object.

Displaying the rowMembers is also unique in that we want to insert a custom UI containing an AvatarStack into each row and bind the rowMembers array to that AvatarStack. To do this we use the cellRenderer property. For now, when the array has values, we’ll render the array as a string. Later we’ll add the AvatarStack component.

const getRowId = useMemo(() => {
  return (params) => params.data.id;
})

return (
  <>
    <div>{ client.auth.clientId }</div>
    <div className="ag-theme-alpine" style={{ height: 400, overflow: 'hidden'}}>
      <AgGridReact
        rowSelection="single"
        rowData={rowData}
        rowHeight={50}
        columnDefs={columnDefs}
        getRowId={getRowId}
      />
    </div>
  </>
);

Create a memoized constant that holds the row datas unique identifiers (make sure you remember to import the useMemo function) and then replace the default JSX in App.jsx with theAgGridReact component.

The grid is bound to the row data, column definitions, and row ID’s. It also has rowSelectionconfigured as “single”.

Finally, before you test the application, we need to tweak one small bit of the application's CSS. The <body> element is configured with its display property set to flex. This will constrain the grid to a very narrow display which makes it hard to view the grid data. To fix this, open the index.css file, locate the body element, and remove or comment out the display: flex attribute.

body {
  margin: 0;
  /* display: flex; */
  place-items: center;
  min-width: 320px;
  min-height: 100vh;
}

Test the application and you should see a grid with data that allows for row selection.

The Row Members column will display “None” for now because we haven’t connected the row selection event. We will do that next.

Change row selection and member locations

As users select different rows, we want to display all of the users who have that same row selected as an AvatarStack in that row. We need a way to keep track of every user’s location. Recall that the grid exists inside of a Space, a virtual area of the application in which realtime collaboration between users can take place. Because all users of our application are members of the same Space we can use the member location to track which row they currently have selected, and then communicate that to all other members in real time.

The member location feature enables you to track where members are within a Space, to see which part of your application they’re interacting with. A location could be the form field they have selected, the cell they’re currently editing in a spreadsheet, or the slide they’re viewing within a slide deck. Multiple members can be present in the same location.

We’ll use AG Grid’s onRowSelected event to update the location of a member. We’ll also use the Ably Spaces useLocation hook to listen for member location changes and update the grid data.

Start by creating a function that mutates the rowMembers arrays based on a member’s previous and current locations in the Space. Make sure you import the useCallback function into the page. We’re using useCallback to have React cache the function definition between rerenders.

const mutateMemberLocations = useCallback((previousLocation,nextLocation,clientId) => {
  updateRowData((draft) => { 
    if (previousLocation) {
      const rowIdx = draft.findIndex((row) => row.id === previousLocation);
      const memberIdx = draft[rowIdx].rowMembers.indexOf(clientId);
      if (memberIdx > -1) {
        draft[rowIdx].rowMembers.splice(memberIdx, 1);
      }
    }
    if (nextLocation) {
      const rowIdx = draft.findIndex((row) => row.id === nextLocation);
      if (draft[rowIdx]) {
        if (!draft[rowIdx].rowMembers.includes(clientId)) {
          draft[rowIdx].rowMembers.push(clientId);
        }
      }
    }
  });
}, []);

When updateRowData is called the function first checks to see if the members clientId was in a previous location and if so, removes them. It then checks to see if there is a new location and if there it adds the member’s clientId to that rowMembers array.

This is where using Immer helps us. Immer gives us a draft, or a copy, of the row data to mutate as we see fit. Once we’re done and the updateRowData function exists, Immer takes care of merging the changes from our draft into a new copy of the data object, which triggers the state change events in React and UI updates that are required.

We want to update the row data anytime a member’s location changes. To know about location changes we can use the useLocations hook. Add it as an import to App.js:

import { useSpace, useLocations } from "@ably/spaces/react";

useLocation gives you a function to call to update the member location and a callback to listen for member location changes. Use the callback to run the mutate function, passing in the previous location, current location, and id of the member whose location changed.

const { update } = useLocations((location) => {
  mutateMemberLocations(
    location.previousLocation?.nodeid,
    location.currentLocation.nodeid,
    location.member.clientId
  );
});

Reacting to location changes is great, but how do we change a member’s location in the first place? We’ll use the AG Grid onRowSelected event to do that.

The onRowSelected event is called both when a row becomes unselected and selected so first check to make sure the row passed in is the newly selected one. Then use the update function to change the Space member location:

const onRowSelected = async (e) => {
  if (e.node.isSelected()) {
    update({ nodeid: e.node.id });
  }
};

Don’t forget to add the onRowSelected property to the grid component and bind it to the onRowSelected function.

Test the application again. When you select a row the member of that row should be shown. Open a second tab and load the site. Select a row and now both members of the Space should be reflected in the row members column.

Add an Avatar Stack

Now that the app is displaying members, let’s change the column to show them using an Avatar Stack. Avatar Stacks are a common way of showing the online status of members in an application by displaying an avatar for each member. We’ll use the Avatar component that’s included in the Flowbite component library.

To use Flowbite in our project you will need to install the packages and configure the React application to import the resources. The Flowbite website has a fantastic integration guide that walks you through this process. You can also check out the Ably blog post: How to create an Avatar Stack using Ably and Flowbite React to learn more about installing and using the Flowbite Avatar component in a React application.

Once you have Flowbite installed, create a new component named AvatarStack.tsx. Import the Avatar component and then using the map function, generate an array of Avatar components, one for each row member. Stack the avatars together by using the <Avatar.Group> component and by binding the array of Avatars as the child components of the group.

"use client";
import { Avatar } from "flowbite-react";
function AvatarStack({ members }) {
  const avatars = members.map((m) => (
    <Avatar
      key={m}
      rounded
      stacked
      placeholderInitials={m.toUpperCase().substring(0, 1)}
    />
  ));
  return (
    <div id="avatar-stack" className={`example-container`}>
      <Avatar.Group>{avatars}</Avatar.Group>
    </div>
  );
}
export default AvatarStack;

Finally, import the AvatarStack component into App.js and add it to the cellRenderer of the column.

import AvatarStack from "./AvatarStack";
return (
  <>
    {props.value.length > 0 ? (
        <AvatarStack members={props.value} />
      ) : (
        <div>None</div>
      )}
  </>
);

Test the application and now, instead of a string of client IDs, you should see an AvatarStack displayed for each row with members in that location.

Again, open a second tab and as you select different rows, you should see the Avatar stack synchronized across both browsers.

Set up initial member state

Notice when you open the application in a second tab, existing row members that have selected rows in the first tab are not reflected. It’s not until you select a row in the second tab that existing members are shown. Ideally, we’d show member locations as soon as the grid loads, but right now we only get member location info from row selection changes.

Let’s change the application to show the existing state when the page loads. To do that use the Ably Spaces useMembers hook. useMembers retrieves members of the Space, including members that have recently left the Space, but have not yet been removed. It provides three functions we can use to get member information:

self: A member’s member object.
others: An array of member objects for all members other than the member themselves.
members: An array of all member objects, including the member themselves.

Start by importing the useMembers hook into App.js and then grab the others function:

const { others } = useMembers();

Next, loop through each existing “other" member, calling the mutation function to update the grids row members:

useEffect(() => {
  others.forEach((member) => {
    if (member.lastEvent.name == 'present') {
      mutateMemberLocations(null, member.location?.nodeid, member.clientId)
    } else if (member.lastEvent.name == 'leave') {
      mutateMemberLocations(member.location?.nodeid, null, member.clientId)
    }
  })
}, [others]);

Notice how the loop checks to see if the member’s last event was present or leave. Members fire the present only if they were already in the room when the requesting member joined.

Test the application one more time. Select a row in the first browser and then open the site in a second browser. This time the location of the first member should be shown right away without any interaction with the grid required.

Wrapup

Congratulations, you did it! Using React, AG Grid, and Ably Spaces you’ve built a collaborative data grid that allows users to see in real time the selected row of other grid users. This makes it easier for multiple users to collaboratively navigate the grid together.

Grid collaboration doesn’t need to stop there though. Using the Component Locking feature of the Ably Spaces SDK you could control simultaneous editing of grid data, allowing users to lock cells while editing data to prevent accidental data overwrites.

Additionally, if you’re using the Enterprise version of AG Grid, then you could enable range selection rather than whole-row selection. Using range selection and the same Location capabilities of the Spaces SDK you could create a Google Sheets-style cell-level collaboration experience.

What collaborative grid features do you use? Let me know. Drop an email to devin.rader@ably.com, hit me up at @ablydevin on X (Twitter), or message me on LinkedIn.

How to authenticate a Next.js Route Handler using Clerk

ablydevin — Thu, 11 Jan 2024 15:12:54 +0000

When building web applications you’ll often be using services on the client that require authentication. A common way client-side SDKs like Ably authenticate themselves is by using server-side API endpoints that generate and return access tokens. Using access tokens allows you to keep your service’s secrets on the server and instead issue time-limited and scope-limited tokens to a client. Some services even let you create revocable tokens for added security.

But how do you protect those token-generating endpoints? For a React application, Clerk is a simple but powerful way to add user management and authentication capabilities. In this blog post, I’ll show you how to use Clerk to protect routes in an Next.js application that users will access and how to protect the token-generating API endpoints the Ably client-side SDKs need.

If you want to skip ahead for the completed sample code, head over to this GitHub repository. Otherwise, let's start building!

Prerequisites

Before building this application you’ll need to make sure you have an Ably account. If you don’t have one you can sign up for a free trial. You will also need a Clerk account. Clerk has a generous free tier that makes it super simple to add user management to your application.

When creating your Clerk account, make sure you enable the Username attribute for your Application. We'll use that later in the post to show how you can access the user data Clerk manages for you to customize an Ably client.

Once you have accounts for Clerk and Ably you will need to locate your Clerk API Keys and Ably API key. Clerk API keys are found in the API Keys section of your Clerk applications dashboard. Ably API keys are found in the API Keys section of your Ably applications dashboard.

Finally, you’ll need to make sure you have at least Node 18 installed in order to build this project. You can check your current Node version by running the command node -v from your terminal or command line.

Application Setup

Get started building the application by using using giget to clone an Ably Next.js starter kit application:



npx giget@latest gh:ablydevin/starter-kits/next-typescript clerk-ably-nextjs

The starter kit provides you with a Next.js application that has been preconfigured with an Ably client. Once you’ve cloned the folder, make sure you copy the .env.example file and drop in your Ably API key.

Make sure the project works as expected by installing its dependencies using npm install. Test the site by running npm run dev. The project should start and load on a local web server running on port 3000. Open the site in a browser to verify it loads successfully.

Once the basic site is running, you can add the infrastructure needed to use Clerk in the site.

Start by adding the dependency for the Clerk package:



npm install @clerk/nextjs

Next set up the environment variables used to store the Clerk key and secret we’ll use for this project:



NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY="[YOUR_CLERK_PUBLISHABLE_KEY]"
CLERK_SECRET_KEY="[YOUR_CLERK_SECRET_KEY]"
ABLY_API_KEY="[YOUR_ABLY_API_KEY]"

Setting up Clerk Authentication

Let's add basic authentication to our application using Clerk. Clerk provides a set of Next.js specific components and helpers that make adding user management a breeze.

Open layout.tsx and surround the default HTML tags with a <ClerkProvider> component:



import { ClerkProvider } from "@clerk/nextjs";

// ...

return (
  <ClerkProvider>
    <html lang="en">
      <body className={inter.className}>{children}</body>
    </html>
  </ClerkProvider>
)

This puts our entire application within the scope of Clerk. Next, we need a route where unauthenticated users sign in. Under the app directory add a new folder named sign-in and add a new file called page.tsx to it.



import { SignIn } from "@clerk/nextjs";

export default function Page() {
  return <SignIn />;
}

The page renders the <SignIn> component which is Clerks default UI for signing in users.

In the app folder open page.tsx. Import the UserButton component and add it to the page markup. The UserButton component is Clerks default UI for user profile management and session signout.



import { UserButton } from "@clerk/nextjs";

// ...

<main className="flex min-h-screen flex-col items-center justify-between p-24">
  <div>
      <UserButton afterSignOutUrl="/"/>
  </div>

  {/* ... The existing page markup ... */}
</main>

Finally, add a new file named middleware.ts to the project root. This is a special file that Next.js uses to allow you to define application middleware. Middleware allows you to run code before a request is completed. Based on the incoming request, you can modify the response by rewriting, redirecting, modifying the request or response headers, or responding directly. Clerk uses a helper function called authMiddleware to integrate authentication into a Next.js application.

For our application add the following code to define the paths that Clerk should protect and to configure how Clerk performs that authentication:



import { authMiddleware } from "@clerk/nextjs";

export default authMiddleware({});

export const config = {
  matcher: ["/((?!.+\\.[\\w]+$|_next).*)", "/", "/(api|trpc)(.*)"],
};

The code uses Clerks recommended matcher, which by default protects all routes, with the exception of internal /_next/ routes and static files.

Let's test the application. Make sure it's still running (or run npm run dev again) and reload the site in the browser. Now when the site loads, the home page should automatically redirect to the Clerk sign-in because you haven’t authenticated yourself yet.

From the sign-in UI you can either use your existing Clerk user credentials to log in, or walk through the new user sign-up process. Once you can successfully authenticate you should be redirected back to the site home page.

Notice that on the site home page, there is now a user avatar. This is Clerks UserButton. Click the button and a context menu with options to edit your profile or sign out are shown.

Token API

As mentioned earlier the matcher we’ve configured in the middleware protects any routes in the project, including the token generation route handler that comes preconfigured in the Ably starter kit project. You can find this route handler under the app/api/ably/ folder.

In this project, the route handler is used as an API endpoint. When requested, it generates and returns a Token Request the Ably Client uses to connect to Ably. Token Requests are one of several methods available from Ably that allow you to authenticate an Ably Client securely without exposing your API secret keys.

Try loading the route handler in the browser by loading http://localhost:3000/api/ably. When you load the route you will be redirected to the sign-in page because we’ve configured Clerk to protect all routes the same way - even the API route. Having an API endpoint redirect to a signup isn’t really the behavior that we want. Humans won’t be using this endpoint, browsers will, so we should return something a browser will understand like a 401 Unauthorized status code.

To accommodate this different expectation of API endpoints, Clerk includes an apiRoutes property that you can pass to the authMiddleware function in our middleware.ts file.



export default authMiddleware({
  apiRoutes: ["/api(.*)"],
});

Try loading the /api/ably/ endpoint again in the browser. This time it should return the 401 status code as we expect. Trying to load the root route of the website should continue to redirect to the sign-in page.

Log in to the site using the sign-in and then return to the /api/ably/ endpoint. This time, because you’ve created an authorized session, the API endpoint should return an Ably token.

Clerk Username as Ably Client ID

In our Token Request endpoint we’re randomly generating a string of characters to use as the Ably Client ID. Randomly generator strings okay but because we’re using Clerk we have actual user data, like a username. We can access the user data and use it as our client ID instead of a random number.

To do this import the currentUser function into the route.ts file:



import { currentUser } from "@clerk/nextjs";

Calling the currentUser function returns a user object which we can use to access the user's username property. Change the value of the clientId property that is passed into the createTokenRequest function from a hard-coded string to the users username:



export async function GET(request: Request) {
  const user = await currentUser();

  // ...

  //const clientId = Math.random().toString(36).substring(2, 15) + Math.random().toString(36).substring(2, 15);

  const client = new Ably.Rest(process.env.NEXT_ABLY_API_KEY as string);

  const tokenRequestData = await client.auth.createTokenRequest({
    clientId: user?.username as string 
  });
  console.log(`Request: ${JSON.stringify(tokenRequestData)}`)
  return Response.json(tokenRequestData);
}

Reload the /api/ably/ endpoint and you should now see that the token contains the username.

Lastly, display the connected client ID in the site by altering the Status.tsx component. Import the useAbly hook which returns an instance of the Ably client object. Use that instance to access and display the Client ID on the page.



'use client'
import Image from 'next/image'
import { useState } from 'react'
import { useConnectionStateListener, useAbly } from 'ably/react'
export default function Status() {
  const client = useAbly();
    const [state, setState] = useState('')
    useConnectionStateListener((stateChange) => {
      setState(stateChange.current)
    });

    return (
      <div>
        <p><span>Realtime Connection Status: {state}</span></p>
        <p><span>ClientId: {client.auth.clientId}</span></p>
      </div>
    )
}

Yay!

Wrapup

Clerk is a great tool for adding user management and application authentication to a React application. It makes it easy not only to protect React routes users will access, but also routes that client-side SDKs need to access.

In this post, I showed you how to use Clerk to protect an API route that generates Ably Token Requests. Token Requests are used by the ably-js client library to authenticate with Ably and allow you to add realtime experiences to your React application.

Additionally, I showed you how you access the user profile data managed by Clerk and use that as part of the Token Request generation process, setting the Ably client ID to the user’s username.

User management is a complex part of many websites. Clerk makes it easy to add to React applications. It would be simple to use Clerk to manage other parts of realtime applications like usernames in an Ably-powered chat application or tracking a Clerk user’s current status using Ablys presence capabilities.

Let me know how you are using Clerk in your application! Drop me a line on X (Twitter) or via an email to devin.rader@ably.com.

Get started with security: Vite, React, and Ably Token Requests for API access

ablydevin — Thu, 04 Jan 2024 10:39:58 +0000

SaaS APIs typically require some kind of authentication to allow access. While there are many ways that APIs can implement authentication, one popular choice is using secret keys as the scheme.

Exposing secret keys directly to a client application however can create security risks, so how can client applications based on libraries like React securely access SaaS services? Many APIs, including Ably, offer an additional client-oriented token authentication system. Tokens have the benefit of being short-lived and allow you to include access control information, meaning you can give different clients different levels of access to your system.

Ably offers an additional token scheme called Token Requests. Using an Ably SDK, a TokenRequest is generated from your server and returned to the client-side SDK instance. The client-side SDK instance then uses the TokenRequest to request an Ably Token directly from Ably.

Token Requests have several advantages over passing tokens directly to clients. They are generated securely by your servers without communicating with Ably so your secret API key is never passed between your server application, Ably or your client applications. Additionally, Ably Token Requests cannot be tampered with due to being signed, must be used soon after creation, and can only be used once.

In this blog post, I’ll show you how you can use Ably SDK’s in a React application to authenticate an Ably client using a Token Request to avoid exposing your Ably secret keys. If you want to skip straight to the code check out this GitHub repository, otherwise lets get building!

Vite Project Setup

Start building the application by using Vite, a popular frontend build tool to scaffold a basic React and Javascript application:

npm create vite@latest ably-tokenrequest-sample --template react-js

Once Vite has finished scaffolding follow its instructions to finish installing the project dependencies and run the project:

cd ably-tokenrequest-sample
npm install
npm run dev

The project will run, starting a local web server that you can browse to.

Now let's add an API endpoint that generates and returns a Token Request.

Create API routes

Because server-side applications can access environment variables, we can use an API endpoint running on the server (and therefore has access to our Ably secret key) to generate a Token Request for the client.

By default, Vite comes with no server components but there are multiple plugins that add API route capabilities to a Vite project. In our project we’ll use vite-plugin-api a plugin that adds API routing to Vite by basing it on directory structure. It uses Express as its underlying server.

Use NPM to install the vite-plugin-api and express packages:

npm install vite-plugin-api express

Add the plugin to vite.config.js:

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { pluginAPI } from "vite-plugin-api";
// https://vitejs.dev/config/
export default defineConfig({
  plugins: [
    react(),
    pluginAPI({
      // Configuration options go here
    }),
  ],
});

Next, create a place to store the environment variables used in our project. Vite uses dotenv to load environment variables from .env files into your environment directory.

In the root of your project, create a new file named .env.local. The .local extension tells dotenv to prioritize these values over other .env files it may load.

To prevent accidentally leaking env variables to the client, only variables prefixed with VITE_ are exposed to your Vite-processed code. Add a variable for your Ably secret key:

VITE_ABLY_API_KEY="[YOUR_ABLY_API_KEY]"

We’re now ready to create an endpoint and generate a Token Request.

Generating a Token Request

Ably has several ways to create tokens but one way is using an Ably SDK to have your server application generate a Token Request and pass this to the client. To do that start using NPM to install the Ably SDK:

npm install ably

Under the /src/ filter create an /api/ably/ folder. This serves as your API root. To that folder add a token.js file. Insert the following code:

import Ably from "ably/promises";

export const GET = async (req, res) => {

  // Your application should perform some type of user 
 // authorization to validate that the user is allowed 
 // to receive a token before fulfilling the token request 
 // if (requesting_user.isAuthenticated) {

    const client = new Ably.Rest(import.meta.env.VITE_ABLY_API_KEY);
    const tokenRequestData = await client.auth.createTokenRequest({
      clientId: 'Random Client ID',
    });
    console.log(`Request: ${JSON.stringify(tokenRequestData)}`);
    return res.json(tokenRequestData);

  //} else {
 // res.status(401).json({ 'error':'User is not authorized' })
  //}
};

This code defines an endpoint that serves GET requests, uses the createTokenRequest function from the Ably SDK to generate a TokenRequest, and returns that TokenRequest as a JSON-encoded object.

ℹ️
Note that right now this code will return a valid TokenRequest to any client that sends a GET request to the endpoint. As called out in the code comments, for most applications you will want to include in this endpoint some type of user authorization to validate the request is coming from an application user allowed to generate TokenRequests.

Additionally, validating the user making the request allows you to include access controls in the Token Request to give the user the smallest number of required permissions.

Save the file and if needed restart your Vite project by running npm run dev. Load the route http://localhost:5173/api/ably/token and you should see the JSON encoded TokenRequest returned.

Congratulations! Your client applications can now request TokenRequests they can use to authenticate with Ably. To do that, they can provide the API route as the value of the authUrl property:

const client = Ably.Realtime.Promise({ authUrl: '/api/ably/token/' });

Alternatively, use the authCallback property to provide a function that gives you more direct control of the request to the API:

const client = Ably.Realtime.Promise({ authCallback: async (data, callback) => {
  try {
    const response = await fetch("/api/ably/token/");
    const tokenRequest = await response.json();
    callback(null, tokenRequest)
  } catch (e) {
    callback(e, null)
  }
}

Either method allows the Ably client to receive the TokenRequest object it can use to authenticate with Ably.

Wrapup

Allowing client applications to use authenticated services can complicate how you think about securing your application. You need to avoid passing service secrets to the client, but still allow them a way to authenticate. Many services like Ably solve this problem by providing you with a mechanism for creating short-lived access tokens in your server application, and passing them to the client.

One way to allow client applications to retrieve a token is via an API endpoint. One way to allow client applications to retrieve a token is via an API endpoint. In a Vite project, the vite-plugin-api is a simple way to add API routes to your application. The plugin enhances the default routing in a Vite project by adding a simple directory structure-based mechanism for API routes.

In this demo we created a new route that uses the Ably SDK to generate a new Ably Token Request. What are your favorite ways to add API routes to a React app? Let us know by reaching out on Twitter or drop me an email.

Build a realtime closed-caption system in React, AssemblyAI and Ably

ablydevin — Mon, 06 Nov 2023 11:25:44 +0000

Closed-captioning for television systems was first demonstrated in the early 1970s. Realtime closed-captioning was developed later in the early 1980s. Here, stenotype operators who type at speeds of over 225 words per minute provide captions for live television programs, allowing the viewer to see the captions within two to three seconds of the words being spoken was developed later in the early 1980s.

As the internet has exploded the ability for anyone to create content, including live video and audio, has also grown. It remains important to consider making that content as accessible as possible not only allowing those with hearing impairment to consume your content, but also those learning to read, learning to speak a non-native language, or those in an environment where the audio is difficult to hear or is intentionally muted.

Sometimes, consumers of your content may simply prefer to read a transcript.

In this blog post, we will build a realtime browser-based closed-captioning system using React, AssemblyAI’s realtime transcription service, and Ably. If you want to jump ahead and check out the completed code, check out this Github repo, otherwise let's get started!

Prerequisites

Before you start coding, you’ll need to make sure you have the following prerequisites.

First, you’ll need to create an AssemblyAI account. We’ll be using their realtime transcription services as part of our project. Realtime transcription is priced at a per-second rate so while you will need to add a payment method to your account to use realtime transcription you’ll only pay for what you use.

Next, you will need a free Ably account. We’ll use Ably to broadcast the transcription to our application users.

Lastly, we will be building the server-side parts of the application in Node including using Nodes native fetch API which is available in Node 18 or newer.

Once you’ve got those accounts, then head on to the rest of the blog post to start to build!

Application setup

Start your application by using Vite to scaffold a basic React and JavaScript application. Open a terminal and run Vites create command:

npm create vite@latest

Vite will ask you a few questions about your project including the project name, an application framework (select React), and which framework variant you want to use (select JavaScript).

After the scaffolding completes, navigate into the project directory and install the project dependencies using npm. Finally, run the project to verify that the scaffolded project works as expected:

cd react-closed-captioning
npm install
npm run dev

Add application routing

Our closed captioning application will have two modes:

A publisher mode that records and transcribes the audio.
A subscriber mode that receives the transcription text.

We’ll need to allow a user to navigate between those modes which we do by adding routing using the react-router-dom package.

Start by creating components in the applications src directory for the publisher (Publisher.jsx) and subscriber (Subscriber.jsx) modes:

import { useState } from "react";
import './App.css'

function Publisher() {}

export default Publisher

import { useState } from "react";
import './App.css'

function Subscriber() {}

export default Subscriber

Next, install the react-router-dom package using NPM:

npm install react-router-dom

In the main.jsx file import the BrowserRouter object from react-router-dom and wrap the default App component with it:

import React from 'react'
import { BrowserRouter } from 'react-router-dom'
import ReactDOM from 'react-dom/client'
import App from './App.jsx'
import './index.css'

ReactDOM.createRoot(document.getElementById('root')).render(
  <React.StrictMode>
    <BrowserRouter>
     <App />
    </BrowserRouter>
  </React.StrictMode>,
)

In App.jsx, add import statements for the Routes, Route, and Link objects as well as the Publisher and Subscriber components you created earlier:

import { Routes, Route, Link } from 'react-router-dom';
import Publisher from './Publisher'
import Subscriber from './Subscriber'

Finally, add the route links inside of the App components Empty tag:

<div style={{ textAlign: "center", marginBottom: 10, }}>
  <div>
    <Link to="/Publisher">Publisher</Link>
  </div>
  <div>
    <Link to="/Subscriber">Subscriber</Link>
  </div>
</div>
<div style={{ textAlign: "center" }}>
  <Routes>
    <Route path="/publisher" element={<Publisher />} />
    <Route path="/subscriber" element={<Subscriber />} />
  </Routes>
</div>

Restart the app if needed by running npm run dev or refresh the page you should see links to the Publisher and Subscriber views.

Generate service authentication tokens

The two services we use in the application, Ably and AssemblyAI, both require the application to authenticate itself with their APIs. To do that we need to create API tokens using server-side code. This lets us keep our service keys safe on the server and instead create temporary authentication tokens our client code can use to authenticate with the services.

To create the server code for the application we’ll use a Vite plugin called vite-plugin-api. This plugin makes it easy to create API endpoints as part of our application.

Use NPM to install the plugin package, express web server package, and the Ably client library:

npm install vite-plugin-api express ably

Add the plugin to your Vite configuration file:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { pluginAPI } from "vite-plugin-api";

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [react(),
    pluginAPI({
      // Configuration options go here
    }),
  ],
})

The application will store those sensitive Ably and AssemblyAI service keys as environment variables. Vite makes it easy to access environment variables stored in a local file named .env.local. Create this file in the root of your project directory and then add the following keys:

VITE_ABLY_API_KEY=[YOUR_ABLY_API_KEY]
VITE_ASSEMBLYAI_API_KEY=[YOUR_ASSEMBLYAI_API_KEY]

Make sure you replace the placeholder values with your actual Ably and AssemblyAI keys.

Next, inside of your project’s src directory create a new directory named api/tokens and add two files to it: realtime.js and transcription.js.

Inside of realtime.js add the following code which uses the Ably client library to generate and return a new Ably authentication token:

import Ably from "ably/promises";

export const GET = async (req, res) => {
  const client = new Ably.Rest(import.meta.env.VITE_ABLY_API_KEY);
  const tokenRequestData = await client.auth.createTokenRequest({ clientId: 'ably-demo' });
  console.log(`Request: ${JSON.stringify(tokenRequestData)}`)
  return res.json(tokenRequestData);
}

Inside of transcription.js add the following code which uses Nodes fetch function to fetch and return a new AssemblyAI authentication token:

export const GET = async (req, res) => {
  const response = await fetch("https://api.assemblyai.com/v2/realtime/token", {
    method: "POST",
    body: JSON.stringify({ expires_in: 3600 }),
    headers: {
      Authorization: import.meta.env.VITE_ASSEMBLYAI_API_KEY,
   "Content-Type": "application/json",
    },
  });
  const token = await response.json();
  console.log(token);
  return res.json(token);
};

Test your new API endpoints by loading the realtime (http://localhost:5173/api/token/realtime/) and transcription (http://localhost:5173/api/token/realtime/) routes in your browser. You should see responses similar to those seen in the images below:

Create the publisher component

Now that we can generate tokens, we’ll implement the publisher component of the application. Remember that the publisher's job is to acquire realtime audio, send it to AssemblyAI for transcription, and then broadcast the transcription results to subscribers.

Start by adding some markup to the Publisher component:

function Publisher() {
  return (
    <div>
      <p id="real-time-title">Click start to begin recording!</p>
      <button id="start">Start</button>
      <button id="stop">Stop</button>
      <p id="message"></p>
    </div>
  );
}

This markup adds two buttons to start and stop publishing and an area to display the transcription.

Next, add a variable to store an audio recorder object (which we will create in a future step) and button click handler functions for the start and stop buttons.

const texts = {};
let recorder = null;

async function start(e) {}
async function stop(e) {}

Connect those handler functions to the buttons using their onClick event:

<button id="button" onClick={start}>Start</button>
<button id="button" onClick={stop}>Stop</button>

Open an AssemblyAI WebSocket connection

AssemblyAI uses WebSockets as the transport for receiving raw audio and returning its transcription results. To use the AssemblyAI WebSocket endpoint in our React application we’ll use the react-use-websocket library. This library gives us a React-idiomatic way of using WebSockets.

Install react-use-websocket using NPM:

npm install react-use-websocket

Once installed, add another import statement into Publisher.jsx to import the useWebSocket object from the library:

import useWebSocket from "react-use-websocket";

Add two React state properties, one to store the WebSocket URL and a second to toggle opening and closing the WebSocket connection:

const [socketUrl, setSocketUrl] = useState('');
const [shouldConnect, setShouldConnect] = useState(false);

Notice that the default for the shouldConnect property is false. By default, the react-use-websockets library will immediately try to open a WebSocket connection. In our application, however, we only want to open that connection when the Start button is clicked.

Next, use the useWebSocket hook to configure the WebSocket connection.

const { sendJsonMessage, lastMessage, readyState } = useWebSocket(socketUrl,
{
  onOpen: () => {
    console.log('AssemblyAI WebSocket opened');
  }
}, shouldConnect);

The useWebSocket hook accepts three parameters.

url - The WebSocket URL we want to connect to.
options - An object containing WebSocket configuration options.
connect - A boolean value allowing us to control the library's automatic connection behavior.

Notice that our options object is defining a function for the onOpen event. We’ll use this event in just a moment to start recording realtime audio once the WebSocket connection opens.

In the start click handler add code that fetches a new AssemblyAI authentication token, appends that token to the WebSocket URL, and then toggles the shouldConnect value. This last step will trigger the useWebSocket hook to try to open a connection to the WebSocket URL.

async function start(e) {
  const response = await fetch("/api/tokens/transcription");
  const { token } = await response.json();
  setSocketUrl(`wss://api.assemblyai.com/v2/realtime/ws?sample_rate=16000&token=${token}`);
  setShouldConnect(true);
}

Capturing audio in the browser

If the WebSocket connection opens successfully we can start to capture realtime audio and send it to AssemblyAI for transcription. To capture audio we’ll use the browsers built in getUserMedia function. The getUserMedia function is part of the MediaDevices set of APIs that browsers implement in order to provide developers with safe and standardized ways to access local media hardware devices like microphones, cameras, and speakers.

Calling getUserMedia, in our case, asking only to access audio, returns a MediaStream with tracks containing the requested types of media. Once we have the MediaStream we’ll use the RecordRTC library to transform the raw audio track into a format that we can pass to AssemblyAI. RecordRTC is an abstraction over the native MediaRecoder APIs and provides a number of capabilities that simplify recording audio in the browser.

Install recordrtc using NPM:

npm install recordrtc

Once installed add an import statement importing the RecordRTC and StereoAudioRecorder objects from the library:

import RecordRTC, { StereoAudioRecorder } from "recordrtc";

Inside the onOpen event handler call getUserMedia to access an audio MediaStream. Pass that stream to a new instance of a RecordRTC object. Based on the audio requirements of AssemblyAI’s realtime streaming API, configure the instance of the RecordRTC object to encode 250ms of audio as a single channel track using the pcm codec at a sample rate of 16000Hz.

onOpen: () => {
  console.log("AssemblyAI WebSocket opened");
  navigator.mediaDevices
      .getUserMedia({ audio: true })
      .then((stream) => {
        recorder = new RecordRTC(stream, {
        type: "audio",
        mimeType: "audio/webm;codecs=pcm", // endpoint requires 16bit PCM audio
        recorderType: StereoAudioRecorder,
        timeSlice: 250, // set 250 ms intervals of data that sends to AAI
        desiredSampRate: 16000,
        numberOfAudioChannels: 1, // realtime requires only one channel
        bufferSize: 16384,
        audioBitsPerSecond: 128000,
        ondataavailable: (blob) => {
          const reader = new FileReader();
          reader.onload = () => {
            const base64data = reader.result;
       // audio data must be sent as a base64 encoded string
           sendJsonMessage({
             audio_data: base64data.split("base64,")[1],
          });
        };
        reader.readAsDataURL(blob);
      },
    })
    recorder.startRecording();
  })
}

Each time RecordRTC records 250ms of data it calls the ondatavailable event passing the recorded audio as a Blob. Use this event to base64 encode the audio and use the sendJsonMessage function of useWebSockets to send the encoded data to AssemblyAI.

Finally, after creating the new RecordRTC object, call the startRecording function which triggers the recording of audio and the process of converting and sending it to AssemblyAI.

Pause the recorder

Starting the recording and transcription process is great, but at some point, you’ll probably want to stop it as well. To do that use the stop button click handler to toggle the shouldConnect value to false, closing the WebSocket connection and pause the RecordRTC recorder.

async function stop(e) {
  setShouldConnect(false);
  if (recorder)
    recorder.pauseRecording()
}

Let’s make sure the application is working as expected. Go ahead and try pressing the Start button. You may be prompted to give your application permission to access the microphone. If you are, go ahead and give permission.

Transcription using AssemblyAI

At this point our application is now capable of sending audio to AssemblyAI for transcription. AssemblyAI will perform that transcription and begin sending it back via the same WebSocket connection transcription data.

Start by adding a new state property to store transcribed text:

const [transcription, setTranscription] = useState('');

And use that state property to display the text on our page:

<p id="message">{transcription}</p>

As AssemblyAI transcribes the audio we’re sending, it uses the open WebSocket connection to send back to us messages containing partial transcription results. Those messages look roughly like this:

{
  "message_type":"PartialTranscript",
  "created":"2023-10-13T18:36:02.574861",
  "audio_start":0,
  "audio_end":2230,
  "confidence":0.805910792864326,
  "text":"this is a test",
  "words":[
    {"start":1430,"end":1465,"confidence":0.999489806225809,"text":"this"},
    {"start":1470,"end":1505,"confidence":0.676980979301034,"text":"is"},
    {"start":1910,"end":1945,"confidence":0.763494430232322,"text":"a"},
    {"start":1950,"end":1985,"confidence":0.783677955698138,"text":"test"}
  ]
}

As AssemblyAI continues to receive additional audio, it may send back partial responses containing some or all of the same audio samples. This means that we have to create a way to detect if we need to replace an existing partial response or if we’ve received a final response for a particular time slide of audio.

We’ll do that by using the audio_start value contained in each message and creating a function called processPartialTranscription that can store and update messages based on that value.

const processPartialTranscription = (source) => {
  let msg = "";
  const res = JSON.parse(source.data);
  if (res.text) {
    texts[res.audio_start] = res.text;
    const keys = Object.keys(texts);
    keys.sort((a, b) => a - b);
    for (const key of keys) {
      if (texts[key]) {     
        msg += ` ${texts[key]}`;
      }
    }
  }
  return msg;
}

Each message is added to a dictionary using the audio_start value as the key. If that key already exists then its content is overwritten. Once the data is added to the dictionary it is sorted by its keys (in other words in time order). The sorted keys are looped over to create a single transcription result string.

To receive the WebSocket messages from AssemblyAI the useWebSockets hook gives us access to the last incoming message through the lastMessage property. We can use an Effect based on the lastMessage property to update the transcription text.

Import useEffect from React:

import { useState, useEffect } from "react";

Create a new Effect which checks if lastMessage is not empty and if not passes the last message through the processing function before setting the value to the transcription property:

useEffect(() => {
  if (lastMessage !== null) {
    setTranscription(processPartialTranscription(lastMessage));
  }
}, [lastMessage]);

Run the app. Start the recording and watch as text transcription shows up.

Broadcasting transcription messages

So far in our application we’ve done everything as the Publisher, meaning the person creating the audio is also receiving the transcription text. But closed-captioning is about broadcasting the audio transcription to a wide audience.

AssemblyAI only gives us a single WebSocket connection. To fan out to many transcription consumers we’ll use Ably.

Start by importing the Ably client library into the App component:

import { AblyProvider } from "ably/react";
import * as Ably from 'ably/promises';

Create a new connection to Ably:

const client = new Ably.Realtime.Promise({ authUrl:'/api/tokens/realtime' });

Enclose the Routes component with an AblyProvider, setting its client property to the Ably client you just created. The AblyProvider holds and manages the Ably WebSocket connection for you and makes it accessible to any child component:

<AblyProvider client={ client }>
  <Routes>
    <Route path="/publisher" element={<Publisher />} />
    <Route path="/subscriber" element={<Subscriber />} />
  </Routes>
</AblyProvider>

To broadcast the transcribed messages from the Publisher to Subscribers we need to access an Ably Channel and publish messages to it. The Ably client library includes a set of React hooks that make using Ably in React applications simple.

In the Publisher component import the useChannel object:

import { useChannel } from "ably/react";

Within the component use the useChannel hook to access an Ably channel:

const { channel } = useChannel('closed-captions');

Finally, publish messages to that channel by calling the channels publish method from inside of the processPartialTranscription function:

The application should now begin to publish the JSON formatted transcription data that AssemblyAI is sending the publisher. You can validate that this is happening correctly by logging into the Ably dashboard and connecting to the closed-captions channel using the Dev Console.

Create a subscriber component

With messages being published to Ably, we can shift gears to the Subscriber component. We’ll want the application to consume and display the messages being published into the closed-captions channel.

Import the useState hook from React and Ably useChannel hook into the Subscriber component:

import { useState } from 'react';
import { useChannel } from "ably/react";

Add a variable to hold partial snippets and a state value to hold the current transcription message:

const texts = {};

const [transcription, setTranscription] = useState('');

Add some basic HTML markup that defines two buttons and a place to display the transcription text:

return (
  <>
    <div>
      <p id="real-time-title">Listening for transcription messages!</p>
      <p id="message">{transcription}</p>
    </div>
  </>
);

Add the processPartialTranscription method:

const processPartialTranscription = (source) => {
 let msg = "";

 const res = JSON.parse(source.data);
 if (res.text) {
  texts[res.audio_start] = res.text;
  const keys = Object.keys(texts);
  keys.sort((a, b) => a - b);
  for (const key of keys) {
   if (texts[key]) {     
    msg += ` ${texts[key]}`;
   }
  }
 }

useChannel has a callback function that gets called when new messages are received. Use that to receive and process incoming transcription messages and update the transcriptions state value:

const { channel } = useChannel("closed-captions", (message) => {
 setTranscription(processPartialTranscription(message));
});

That’s it! Open the application in two separate browser windows, one with the Publisher route loaded and the other with the Subscriber route loaded. In the publisher view, start the recorder and watch as transcription text begins to show in both the publisher and subscriber views.

Wrap up

Congrats on building this realtime closed-captioning application! In building his application you learned how easy it is to capture realtime audio from the browser, send it to AssemblyAI for transcribing and broadcast the transcription to an audience.

Combining AssemblyAI’s realtime transcription with Ably’s realtime message broadcasting gives you a powerful set of tools for your developer toolbelt.

If you’re looking to take this application further, one idea is to allow users of your application to select a language in which to receive the transcribed text, using a service like https://languageio.com/ to translate the text in realtime.

I'm always interested in how developers are combining tools like AssemblyAI or Language.io with Ably. Tell me how you are mashing tools together by hitting me up on X (Twitter)

React Hooks now part of Ably’s JavaScript SDK (and how to build a simple React App with Ably)

ablydevin — Mon, 25 Sep 2023 17:16:12 +0000

React is one of the most popular JavaScript libraries in the world, and is known for its performance, scalability, and flexibility. Whether it’s single-page apps, high fidelity frontends, or even in some cases static sites, there's a high chance React is being used to build them.

Today, we are pleased to announce that we have now baked in support for React Hooks within our Ably JavaScript SDK. Ably’s React Hooks provide developers with an efficient and idiomatic way to integrate Ably realtime functionality into their React applications. Not only do they make it easier to integrate with the Ably platform, but they also enhance code quality, maintainability, and performance.

Jump to the code and start building realtime with React

Ably React Hooks

Hooks have been widely adopted by the React community and have become a standard approach to building components in React applications. They make it easier to organize logic in components and create small, reusable parts without using classes. React Hooks are basic JavaScript functions that help separate reusable parts in functional components. Platform providers, such as Ably, can build custom React Hooks, to ease integration - giving developers the head-space to focus on their application instead.

Our React Hooks offering:

Easily handle realtime at scale: Ably’s React Hooks help manage things like state and effects, making sure the code stays organized and easy to maintain.
Full suite of React Hook features: Everything you need to send and receive messages, listen and react to changes, and consume presence events so you know which users/clients are connected.
Easy to use: Simple and intuitive SDK component that can be used with any web application, easing integration with Ably and your React-based app.
High performing: Powered by our market-proven, realtime infrastructure that’s built for reliability at scale, backed by five nines SLAs and messaging guarantees.
Realtime experiences unlocked: Unlock end-to-end realtime messaging throughout your app using our suite of products. While Spaces powers the features you need to enable synchronous collaboration for teams and manage their participant state, Pub/Sub channels allows you to flexibly broadcast and sync app state changes between members, your backend, and any other pieces in your system design.

Ably’s suite of React Hooks features

Ably’s React Hooks are included in the latest version of the Ably JavaScript SDK. They provide a robust pattern for using the Ably client. They allow you to get a callback when messages are received by your component, they re-render and re-subscribe if the channel you're subscribing to is modified, and they make presence events trivial to consume so that your React app can be aware of other connected clients. The full set of features includes:

The AblyProvider component is used to set up the Ably client for your application.
The useChannel hook subscribes to a channel and receives messages from it.
The usePresence hook subscribes to presence events on a channel, notifying when users join or leave the channel.
The useConnectionStateListener hook attaches a listener to be notified of connection state changes in the Ably client.
The useChannelStateListener hook attaches a listener to be notified of channel state changes.
The useAbly hook grants access to the Ably client instance provided by the AblyProvider context.

Hooks like useChannel and usePresence provide information about connection and channel errors.

Multiple Ably clients can be used on the same page by keeping them in separate AblyProvider components.

Building a simple React app with Ably

Let's explore Ably's new React components by building a simple React app that can send and receive realtime messages and display users' presence status. If you want to jump ahead and grab the code, you can head over to the Github repository.

Before you get started, you’ll need to make sure you have an Ably account which you can get for free! We’ll wait here while you grab your account.

Great! Let’s start building by using Vite, a popular frontend build tool, to scaffold an initial React application. Run the following command from your terminal:

$ npm create vite@latest

Vite will ask you a few questions about your project including the project name, an application framework (select React), and which framework variant you want to use (select Typescript).

Once you’ve made all of the selections Vite will get to work scaffolding the project.

Once the scaffolding completes, navigate into the project directory and install the project dependencies using npm. Next, run the project:

$ npm install 
$ npm run dev

The project Vite scaffolds for you is a fully running site. Check it out by loading the site URL in your browser:

Now that the initial website is in place we can move on to adding some realtime features using Ably.

Ably Client Authentication

In order to use Ably’s realtime platform, we need to authenticate an Ably client. Ably supports a number of different methods of client authentication, but for our application, we’ll use Token authentication.

Token authentication uses a trusted device with an API key to issue time-limited tokens to untrusted clients. Tokens have a limited set of access rights, known as capabilities, and can have a specific identity using a clientId. Tokens are the recommended authentication method to use client-side as it provides more fine-grained access control and limits the risk of credentials being exposed.

For our application, our trusted device will be an API endpoint that we’ll create using the Vite vite-plugin-api plugin. This plugin allows us to create routes in our React application that serve as API endpoints. In our case, that route will generate and return a temporary authentication token to the client.

Start by installing express, the vite-plugin-api package, and the Ably Javascript SDK:

npm install express vite-plugin-api ably

Next, configure you Vite config (vite.config.ts) to load the api plugin:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { pluginAPI } from 'vite-plugin-api'

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [
    react(),
    pluginAPI({})
  ],
})

Create a place to store your Ably API key by adding a .env.local to your project. In that file define the variable VITE_ABLY_API_KEY and set its value to your Ably API key, which you can find by logging into your Ably dashboard.

VITE_ABLY_API_KEY=[YOUR_ABLY_API_KEY]

Next, add a new /api/token directory to the src directory of your project and in that directory add a new Typescript file index.ts. This will be our API endpoint. Add the code shown below to generate and return an authorization token:

import Ably from "ably/promises";

export const GET = async (req:any, res:any) => {
  const client = new Ably.Rest(import.meta.env.VITE_ABLY_API_KEY);
  const tokenRequestData:Ably.Types.TokenRequest = await  client.auth.createTokenRequest({ clientId: 'me' });

  return res.json(tokenRequestData);
}

Let’s test the API endpoint. Make sure your website is still running (rerun npm run dev if needed) and load the website URL in a browser. Navigate to the /api/token path. You should see a JSON object returned that includes the authorization token:

Awesome! Now that we have a way to generate tokens we can move on to adding realtime features to our React app.

Using Ably in a React app

To use Ably in our React app we first have to create an instance of the Ably client. We’ll do this by adding the component to our application. The is used to set up the Ably client for your application and should be placed in the component tree such that it wraps every other component that needs to access Ably.

In App.tsx, import ably and the ably React extensions:

import * as Ably from 'ably';
import { AblyProvider } from 'ably/react'

Next create a new instance of an Ably client, configuring it with an authUrl property that points to the token endpoint we created earlier. Pass the instance of the client to the component:

import * as Ably from 'ably';
import { AblyProvider, useChannel } from 'ably/react'

function App() {

  const client = new Ably.Realtime.Promise({ authUrl: '/api/token' });

  return (
    <AblyProvider client= { client } >
    </AblyProvider>
  )
}
export default App;

Once we have an Ably client we'll next add the ability to send and receive realtime messages.

Pub/Sub Channels

Ably's Pub/Sub Channels allow you to send and receive realtime messages using the Ably platform. Let's start by listening for incoming messages.

To do that create a child component that encapsulates the usage of Ably. The child component is needed because we need to control which components are rendered when changed.

If the App component reloads it will cause the Ably client (and any WebSocket connections it has created) to get destroyed, so to avoid that we use a child component to hold real-time functionality. The child component can safely rerender when it needs to without the Ably client being impacted.

First import the useChannel React hook which gives us access to an Ably Channel:

import * as Ably from 'ably';
import { AblyProvider, useChannel } from 'ably/react'

Next, create a new component named Messages:

function Messages() {
  return (<div></div>)
}

Add that component to the App component:

return (
  <AblyProvider client={ client } >
    <Messages />
  </AblyProvider>
)

To receive messages we’ll use the useChannel hook we imported earlier, storing the returned channel as a variable to use later. Messages are received using a callback function:

function Messages() {
  const { channel } = useChannel("ably-demo", (message: Ably.Types.Message) => {
    console.log(message)
  });
  return (<div></div>)
}

To send messages we’ll use the instance of the channel received from the useChannel hook. Channel has a publish function which we can call from a button click:

return (
  <div>
    <button onClick={(event:React.MouseEvent<HTMLButtonElement>) => { channel.publish('world', 'hello world!')}}>Publish</button>
  </div>
)

Return to the browser and if needed refresh your page. You should now see the Publish button. Click the button and then open the browser debugger. You should see message objects logged to the console.

Woohoo! That's how easy it is to send and receive realtime messages in your React app.

Presence

The last feature we’ll explore is Ably Presence. Presence enables clients to be aware of other clients that are currently “present” on a channel. Each member present on a channel has a unique self-assigned client identifier and system-assigned connection identifier, along with an optional payload that can be used to describe the member’s status or attributes.

Start by two new objects, the first being the usePresence React hook and the second being the useState React hook:

import * as Ably from 'ably';
import { AblyProvider, useChannel, usePresence } from 'ably/react'
import { useState } from 'react'

Next, create another new component called Presence:

function Presence() {
  return (<div></div>)
}

Add that new component to the App:

return (
  <AblyProvider client={ client } >
    <Messages />
    <Presence />
  </AblyProvider>
)

To have Ably begin to track our client we’ll use the usePresence hook. This hook enables you to subscribe to presence events on a channel, notifying you when a user enters or leaves the presence set or updates their member data. In our application, we want to subscribe to presence events for the ably-demo channel and we’re passing the string current status to Ably as this client's initial status:

function Presence() {
  const { presenceData, updateStatus } = usePresence<string>("ably-demo", 'current status');
  return (<div></div>)
}

The usePresence hook returns an array of presence messages where each message is a regular Ably JavaScript SDK presenceMessage instance. Using the map function we can convert the presence data to list items to render:

function Presence() {
  const { presenceData, updateStatus } = usePresence<string>("ably-demo", 'current status');
  const peers = presenceData.map((msg, index) => <li key={msg.id}>{msg.clientId}: {msg.data}</li>);

return (
  <div>
    <ul>{peers}</ul>
  </div>
  )
}

It also returns a updateStatus function which can be used to update the presence data for the current client:

return (
  <div>
    <button onClick={(event:React.MouseEvent<HTMLButtonElement>) => { updateStatus('new status') }}>Update Presence</button>
  <ul>{peers}</ul>
</div>
)

Finally, to leave the presence set of a channel we've previously joined we'll conditionally render the Pre sence component. We'll add a new state property that stores a boolean value indicating if the client status is "online" or and a button to toggle the state value.

Using that state value we'll conditionally render the <Presence> component. If the component is rendered it will automatically enter presence tracking. When the state value changes and the component unmounts the client will leave presence tracking:

function App() {

const [isOnline, setIsOnline] = useState<boolean>(true);
const client = new Ably.Realtime.Promise({ authUrl: '/api/token' });

return (
  <>
    <Messages />
    { isOnline && <Presence /> }
    <button onClick={(event:React.MouseEvent<HTMLButtonElement>) => { setIsOnline(!isOnline)}}>Toggle Presence</button>
  </>
  )
}

Reload the application in your browser one more time and now you should see your client’s presence shown in the list.

Press the Update Button to update your client's status. You can even open your website in a second browser to see how additional clients are shown in the list.

Congratulations - you’ve built a React application using Ably's new React Hooks!

Resource roundup

Get started with Ably’s React Hooks.
Sign-up for a free account.
Run through the Using Ably React Hooks tutorial.