Getting started: Pub/Sub in Next.js

This guide will get you started with Ably Pub/Sub in a new Next.js application.

You'll establish a realtime connection to Ably and learn to publish and subscribe to messages. You'll also implement presence to track other online clients, and learn how to retrieve message history.

Prerequisites

Sign up for an Ably account.
Create a new app, and create your first API key in the API Keys tab of the dashboard.
Your API key will need the publish, subscribe, presence and history capabilities.

Create a Next.js project

Create a new Next.js project using the official scaffolding tool. The flags select TypeScript, the App Router and a src/ directory, which is where the files in this guide live:

npx create-next-app@latest ably-pubsub-nextjs --yes --typescript --app --src-dir --no-tailwind
cd ably-pubsub-nextjs

Update globals.css

Replace the contents of src/app/globals.css with the following to reset browser defaults and ensure consistent font sizing across all elements including inputs and buttons:

css

/* src/app/globals.css */
html {
  height: 100%;
}

html,
body {
  max-width: 100vw;
  overflow-x: hidden;
}

body {
  min-height: 100%;
  display: flex;
  flex-direction: column;
  color: #171717;
  background: #ffffff;
  font-family: Arial, Helvetica, sans-serif;
  font-size: 15px;
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
}

*,
input,
button {
  box-sizing: border-box;
  padding: 0;
  margin: 0;
  font-size: inherit;
  font-family: inherit;
}

Install Ably Pub/Sub JavaScript SDK

Install the Ably Pub/Sub JavaScript SDK:

npm install ably

(Optional) Install Ably CLI

Use the Ably CLI as an additional client to quickly test Pub/Sub features. It can simulate other clients by publishing messages, subscribing to channels, and managing presence states.

ably init installs the Ably CLI, authenticates, and sets the default app and API key in a single command:

npx @ably/cli init

Step 1: Connect to Ably

Clients establish a connection with Ably when they instantiate an SDK instance. This enables them to send and receive messages in realtime across channels.

Open up the dev console of your first app before you start so that you can see what happens.

Set up AblyProvider

The Ably Pub/Sub SDK provides React hooks and context providers that make it easy to use Pub/Sub features in your components.

The Ably Pub/Sub client and its React hooks are designed to run in the browser, not during server-side rendering. Create a new file src/app/AblyProvider.tsx that creates the client once, at module level, and wraps children in the AblyProvider:

React

// src/app/AblyProvider.tsx
'use client';

import * as Ably from 'ably';
import { AblyProvider as AblyReactProvider } from 'ably/react';
import { ReactNode, useEffect } from 'react';

const client = new Ably.Realtime({
  key: 'demokey:*****',
  clientId: 'my-first-client',
  autoConnect: false,
});

export default function AblyProvider({ children }: { children: ReactNode }) {
  useEffect(() => {
    client.connect();
  }, []);

  return <AblyReactProvider client={client}>{children}</AblyReactProvider>;
}

API key:

DEMO ONLY

While using an API key is fine for this guide, you should use token authentication in production. A clientId identifies the client, which is required for features such as presence.

Display the connection state

To display the connection state in your UI, create a client component at src/app/ConnectionState.tsx:

React

// src/app/ConnectionState.tsx
'use client';

import { useAbly, useConnectionStateListener } from 'ably/react';
import { useState } from 'react';

export function ConnectionState() {
  const ably = useAbly();
  const [connectionState, setConnectionState] = useState(ably.connection.state);

  useConnectionStateListener((stateChange) => {
    setConnectionState(stateChange.current);
  });

  return (
    <p style={{ color: '#555', padding: '8px 10px', background: '#f0f0f0', borderRadius: '5px' }}>
      Connection: <strong>{connectionState}</strong>
    </p>
  );
}

Replace the contents of src/app/page.tsx to render the component inside the AblyProvider. The page loads AblyProvider with next/dynamic and ssr: false, so the module that creates the client is only ever loaded in the browser:

React

1// src/app/page.tsx2'use client';3 4import dynamic from 'next/dynamic';5import { ConnectionState } from './ConnectionState';6 7const AblyProvider = dynamic(() => import('./AblyProvider'), { ssr: false });8 9export default function Home() {10  return (11    <main style={{ fontFamily: 'Arial, sans-serif', padding: '20px', maxWidth: '900px', margin: '0 auto' }}>12      <h1 style={{ marginBottom: '20px', fontSize: '36px', textAlign: 'center' }}>Ably Pub/Sub - Next.js</h1>13      <AblyProvider>14        <ConnectionState />15      </AblyProvider>16    </main>17  );18}

Start the development server:

npm run dev

Open http://localhost:3000 and you should see Connection: connected. You can also inspect the connection event in the dev console of your app.

To publish and subscribe to messages on a channel use the ChannelProvider component from the Ably Pub/Sub SDK, which scopes child components to a specific channel.

ChannelProvider

The ChannelProvider must be nested inside the AblyProvider. Update src/app/page.tsx to include the ChannelProvider:

React

1// src/app/page.tsx2'use client';3 4import { ChannelProvider } from 'ably/react';5import dynamic from 'next/dynamic';6import { ConnectionState } from './ConnectionState';7 8const AblyProvider = dynamic(() => import('./AblyProvider'), { ssr: false });9 10export default function Home() {11  return (12    <main style={{ fontFamily: 'Arial, sans-serif', padding: '20px', maxWidth: '900px', margin: '0 auto' }}>13      <h1 style={{ marginBottom: '20px', fontSize: '36px', textAlign: 'center' }}>Ably Pub/Sub - Next.js</h1>14      <AblyProvider>15        <ConnectionState />16        <ChannelProvider channelName='my-first-channel'>17          {/* Channel-scoped components go here */}18        </ChannelProvider>19      </AblyProvider>20    </main>21  );22}

Use the useChannel() hook to subscribe to messages on a channel. Create a new file src/app/Messages.tsx:

React

// src/app/Messages.tsx
'use client';

import type { Message } from 'ably';
import { useChannel } from 'ably/react';
import { useState } from 'react';

export function Messages() {
  const [messages, setMessages] = useState<Message[]>([]);

  useChannel('my-first-channel', (message) => {
    setMessages((prev) => [...prev, message]);
  });

  return (
    <div style={{ border: '1px solid #ddd', borderRadius: '4px', padding: '12px', width: '400px', height: '250px', overflowY: 'auto', background: '#fff' }}>
      {messages.map((msg) => (
        <p key={msg.id} style={{ margin: '4px 0', borderLeft: '3px solid #007bff', paddingLeft: '8px', color: '#171717' }}>
          {String(msg.data)}
        </p>
      ))}
    </div>
  );
}

Add Messages to page.tsx inside the ChannelProvider:

React

1// src/app/page.tsx2'use client';3 4import { ChannelProvider } from 'ably/react';5import dynamic from 'next/dynamic';6import { ConnectionState } from './ConnectionState';7import { Messages } from './Messages';8 9const AblyProvider = dynamic(() => import('./AblyProvider'), { ssr: false });10 11export default function Home() {12  return (13    <main style={{ fontFamily: 'Arial, sans-serif', padding: '20px', maxWidth: '900px', margin: '0 auto' }}>14      <h1 style={{ marginBottom: '20px', fontSize: '36px', textAlign: 'center' }}>Ably Pub/Sub - Next.js</h1>15      <AblyProvider>16        <ConnectionState />17        <ChannelProvider channelName='my-first-channel'>18          <Messages />19        </ChannelProvider>20      </AblyProvider>21    </main>22  );23}

Test it by publishing a message from the CLI:

ably channels publish my-first-channel 'Hello from CLI!'

Publish a message

The useChannel() hook also returns a publish method. Update src/app/Messages.tsx to add a message input:

React

1// src/app/Messages.tsx2'use client';3 4import type { Message } from 'ably';5import { useChannel } from 'ably/react';6import { useState } from 'react';7 8export function Messages() {9  const [messages, setMessages] = useState<Message[]>([]);10  const [inputValue, setInputValue] = useState('');11 12  const { publish } = useChannel('my-first-channel', (message) => {13    setMessages((prev) => [...prev, message]);14  });15 16  const handlePublish = () => {17    if (!inputValue.trim()) return;18    publish('my-first-messages', inputValue.trim()).catch(console.error);19    setInputValue('');20  };21 22  return (23    <div style={{ display: 'flex', flexDirection: 'column', gap: '10px' }}>24      <div style={{ border: '1px solid #ddd', borderRadius: '4px', padding: '12px', width: '400px', height: '250px', overflowY: 'auto', background: '#fff' }}>25        {messages.map((msg) => (26          <p key={msg.id} style={{ margin: '4px 0', borderLeft: '3px solid #007bff', paddingLeft: '8px', color: '#171717' }}>27            <span style={{ color: '#777', marginRight: '6px' }}>{msg.clientId}:</span>28            {String(msg.data)}29          </p>30        ))}31      </div>32      <div style={{ display: 'flex', gap: '8px' }}>33        <input34          type='text'35          value={inputValue}36          placeholder='Type a message...'37          onChange={(e) => setInputValue(e.target.value)}38          onKeyDown={(e) => e.key === 'Enter' && handlePublish()}39          style={{ flex: 1, padding: '10px 12px', border: '1px solid #ccc', borderRadius: '4px', outline: 'none' }}40        />41        <button42          onClick={handlePublish}43          style={{ padding: '10px 20px', background: '#007bff', color: '#fff', border: 'none', borderRadius: '4px', cursor: 'pointer' }}44        >45          Publish46        </button>47      </div>48    </div>49  );50}

Type a message and click Publish to see it appear in your UI. Open another browser window to see messages arriving in realtime.

Step 3: Join the presence set

Presence enables clients to be aware of one another on the same channel. You can show who is online, provide status updates, and notify the channel when someone goes offline.

Use the usePresence() and usePresenceListener() hooks from the Ably Pub/Sub SDK. Create a new file src/app/PresenceStatus.tsx:

React

// src/app/PresenceStatus.tsx
'use client';

import { usePresence, usePresenceListener } from 'ably/react';

export function PresenceStatus() {
  usePresence('my-first-channel', { status: "I'm here!" });

  const { presenceData } = usePresenceListener('my-first-channel');

  return (
    <div style={{ padding: '8px 10px', background: '#f0f0f0', borderRadius: '5px' }}>
      <h3 style={{ marginTop: 0, marginBottom: '12px', fontSize: '18px' }}>
        Present ({presenceData.length})
      </h3>
      <ul style={{ listStyle: 'none', padding: 0, margin: 0 }}>
        {presenceData.map((member, idx) => (
          <li key={idx} style={{ padding: '4px 0', color: '#333' }}>
            <span style={{ display: 'inline-block', width: 8, height: 8, borderRadius: '50%', background: '#28a745', marginRight: 6 }} />
            {member.clientId}
            {member.data?.status ? <span style={{ color: '#777' }}> - {member.data.status}</span> : null}
          </li>
        ))}
      </ul>
    </div>
  );
}

Update src/app/page.tsx to include PresenceStatus and ConnectionState inside the ChannelProvider, alongside Messages:

React

1// src/app/page.tsx2'use client';3 4import { ChannelProvider } from 'ably/react';5import dynamic from 'next/dynamic';6import { ConnectionState } from './ConnectionState';7import { Messages } from './Messages';8import { PresenceStatus } from './PresenceStatus';9 10const AblyProvider = dynamic(() => import('./AblyProvider'), { ssr: false });11 12export default function Home() {13  return (14    <main style={{ fontFamily: 'Arial, sans-serif', padding: '20px', maxWidth: '900px', margin: '0 auto' }}>15      <h1 style={{ marginBottom: '20px', fontSize: '36px', textAlign: 'center' }}>Ably Pub/Sub - Next.js</h1>16      <AblyProvider>17        <ChannelProvider channelName='my-first-channel'>18          <div style={{ display: 'flex', gap: '10px' }}>19            <div style={{ flex: '0 0 220px', display: 'flex', flexDirection: 'column', gap: '10px' }}>20              <PresenceStatus />21              <ConnectionState />22            </div>23            <div style={{ flex: 1 }}>24              <Messages />25            </div>26          </div>27        </ChannelProvider>28      </AblyProvider>29    </main>30  );31}

Your client ID will appear in the presence list. Join presence via the CLI to see another client joining:

ably channels presence enter my-first-channel --data '{"status":"From CLI"}'

Step 4: Retrieve message history

Ably stores messages for 2 minutes by default. You can extend the storage period if required.

The useChannel() hook returns a channel instance. Use its history() method to load previously published messages on mount. Update your Messages component in src/app/Messages.tsx to load history with a useEffect:

React

1// src/app/Messages.tsx2'use client';3 4import type { Message } from 'ably';5import { useChannel } from 'ably/react';6import { useEffect, useState } from 'react';7 8export function Messages() {9  const [messages, setMessages] = useState<Message[]>([]);10  const [inputValue, setInputValue] = useState('');11 12  const { publish, channel } = useChannel('my-first-channel', (message) => {13    setMessages((prev) => [...prev, message]);14  });15 16  useEffect(() => {17    let cancelled = false;18    async function loadHistory() {19      await channel.attach();20      const history = await channel.history({ limit: 5, untilAttach: true });21      if (cancelled) return;22      const olderMessages = [...history.items].reverse();23      setMessages((prev) => [...olderMessages, ...prev]);24    }25    loadHistory().catch(console.error);26    return () => {27      cancelled = true;28    };29  }, [channel]);30 31  const handlePublish = () => {32    if (!inputValue.trim()) return;33    publish('my-first-messages', inputValue.trim()).catch(console.error);34    setInputValue('');35  };36 37  return (38    <div style={{ display: 'flex', flexDirection: 'column', gap: '10px' }}>39      <div style={{ border: '1px solid #ddd', borderRadius: '4px', padding: '12px', width: '400px', height: '250px', overflowY: 'auto', background: '#fff' }}>40        {messages.map((msg) => (41          <p key={msg.id} style={{ margin: '4px 0', borderLeft: '3px solid #007bff', paddingLeft: '8px', color: '#171717' }}>42            <span style={{ color: '#777', marginRight: '6px' }}>{msg.clientId}:</span>43            {String(msg.data)}44          </p>45        ))}46      </div>47      <div style={{ display: 'flex', gap: '8px' }}>48        <input49          type='text'50          value={inputValue}51          placeholder='Type a message...'52          onChange={(e) => setInputValue(e.target.value)}53          onKeyDown={(e) => e.key === 'Enter' && handlePublish()}54          style={{ flex: 1, padding: '10px 12px', border: '1px solid #ccc', borderRadius: '4px', outline: 'none' }}55        />56        <button57          onClick={handlePublish}58          style={{ padding: '10px 20px', background: '#007bff', color: '#fff', border: 'none', borderRadius: '4px', cursor: 'pointer' }}59        >60          Publish61        </button>62      </div>63    </div>64  );65}

Setting untilAttach returns only messages published before the channel attached, and useChannel delivers everything after that, so no message appears in both. It requires the channel to be attached first. history() returns the newest messages first, so the component reverses them before adding them above any messages that have already arrived. The cleanup function discards a history response that resolves after the effect has been cleaned up. In development, React Strict Mode runs every effect twice, and without the cleanup each run would add its own copy of the history.

Publish a few messages first if needed:

ably channels publish --count 5 my-first-channel "Message number {{.Count}}"

Reload the page. The last 5 messages will appear immediately, loaded from history before any new realtime messages arrive.

Your completed application should look like this:

The completed Next.js Pub/Sub application.

Next steps

Continue to explore the documentation with Next.js as the selected language:

Understand token authentication before going to production.
Understand how to effectively manage connections.
Explore more advanced Pub/Sub concepts.

You can also explore the Ably CLI further, visit the Pub/Sub API references, or browse the Ably Next.js Fundamentals Kit for more complete examples.

Getting started: Pub/Sub in Next.js

Prerequisites

Create a Next.js project

Update globals.css

Install Ably Pub/Sub JavaScript SDK

(Optional) Install Ably CLI

Step 1: Connect to Ably

Set up AblyProvider

Display the connection state

Step 2: Subscribe to a channel and publish a message

ChannelProvider

Subscribe to a channel

Publish a message

Step 3: Join the presence set

Step 4: Retrieve message history

Next steps