feat: Next.js Pub/Sub getting-started guide by maratal · Pull Request #3332 · ably/docs

maratal · 2026-04-12T19:30:20Z

Summary

Adds a new getting-started guide for Pub/Sub in Next.js (src/pages/docs/getting-started/nextjs.mdx)
Covers: connect to Ably, subscribe/publish, presence, and message history using ably/react hooks
Uses useEffect for Ably client creation to avoid SSR hydration mismatches in the App Router
Adds nextjs as a new language entry across languageData.ts, languageInfo.ts, and types.ts
Adds nav entry in pubsub.ts
Includes a screenshot of the completed example app

https://ably.atlassian.net/browse/DX-1001

Test plan

Guide renders correctly at /docs/getting-started/nextjs
nextjs language selector appears and is selected by default
Screenshot displays correctly
Nav entry appears in the Pub/Sub sidebar
All code blocks render with correct syntax highlighting
CLI commands in the guide work end-to-end

🤖 Generated with Claude Code

… layout - Replace module-level client creation with useEffect to avoid SSR hydration mismatches - Add null guard and cleanup (ably.close()) in AblyProvider - Update Step 1 prose to reference useEffect approach - Move ConnectionState inside ChannelProvider in Step 3 page.tsx - Replace em dash with hyphen in PresenceStatus member status display Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

coderabbitai · 2026-04-12T19:30:27Z

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: fd8ff1e5-a84a-4b36-979e-fc17e133ad3a

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch DX-1001-pubsub-nextjs-guide

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

nextjs is not registered in @ably/ui CodeSnippet languages registry, causing highlight.js to throw "Unknown language: nextjs" during SSR. react works because it has a syntaxHighlighterKey mapping to javascript. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

… app - Add globals.css subsection with font-size reset and box-sizing rules - Style ConnectionState with grey pill background and bold state - Style page.tsx with centred title and max-width container - Style Messages with scrollable bordered box, blue left-border per message, clientId label, and Publish button - Style PresenceStatus with grey pill, green dot indicator, and h3 heading - Add two-column flex layout to final page.tsx Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Copilot

Pull request overview

Adds a new Pub/Sub “getting started” guide tailored for Next.js (App Router) and wires Next.js in as a selectable language across the docs language system and Pub/Sub navigation.

Changes:

Adds a new MDX guide at /docs/getting-started/nextjs covering connection, pub/sub, presence, and history with ably/react.
Adds nextjs to docs language metadata (keys, labels, and Pub/Sub version mapping).
Adds a Pub/Sub sidebar nav entry and includes a screenshot asset for the guide.

Reviewed changes

Copilot reviewed 5 out of 6 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/pages/docs/getting-started/nextjs.mdx	New Next.js App Router Pub/Sub getting-started guide content and code samples
src/images/content/screenshots/getting-started/pub-sub-nextjs-getting-started-guide.png	Screenshot used by the new guide
src/data/nav/pubsub.ts	Adds “Next.js” link under Pub/Sub getting started
src/data/languages/types.ts	Adds `nextjs` to `LanguageKey` union
src/data/languages/languageInfo.ts	Adds label/syntax metadata for `nextjs`
src/data/languages/languageData.ts	Adds `nextjs` version entry for Pub/Sub language selector

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-16T12:54:15Z

+import { AblyProvider } from './AblyProvider';
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {


In the layout.tsx snippet, children is typed as React.ReactNode but React isn’t imported. In a typical Next.js + TypeScript setup this will fail type-checking. Prefer importing ReactNode as a type (or PropsWithChildren) from react and using that instead of the React. namespace.

Suggested change

import { AblyProvider } from './AblyProvider';

export default function RootLayout({ children }: { children: React.ReactNode }) {

import type { ReactNode } from 'react';

import { AblyProvider } from './AblyProvider';

export default function RootLayout({ children }: { children: ReactNode }) {

Copilot · 2026-04-16T12:54:16Z

+  useEffect(() => {
+    async function loadHistory() {
+      const history = await channel.history({ limit: 5 });
+      setMessages(history.items.reverse());
+    }
+    loadHistory().catch(console.error);
+  }, [channel]);


The history-loading effect replaces the entire messages state with history.items.reverse(). Because the realtime subscription callback is active at the same time, any messages received between mount and the history request resolving can be dropped (overwritten). Consider merging history into the existing state (and optionally de-duping) rather than replacing it.

m-hulbert · 2026-04-19T12:23:03Z

+  - nextjs
+---
+
+This guide will get you started with Ably Pub/Sub in a new Next.js application using the App Router.


Suggested change

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

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

m-hulbert · 2026-04-19T12:24:40Z

+Because the Ably Realtime client uses browser APIs such as WebSocket, it cannot run during server-side rendering. Create a new file `src/app/AblyProvider.tsx` that initializes the client inside a `useEffect` and wraps children in the `AblyProvider`:
+
+<Code>
+```javascript


This should be React throughout.

m-hulbert · 2026-04-19T12:25:05Z

+
+The Ably Pub/Sub SDK provides React hooks and context providers that make it easy to use Pub/Sub features in your components.
+
+Because the Ably Realtime client uses browser APIs such as WebSocket, it cannot run during server-side rendering. Create a new file `src/app/AblyProvider.tsx` that initializes the client inside a `useEffect` and wraps children in the `AblyProvider`:


Same comment as the others on 'Ably realtime client' vs Pub/Sub SDK.

m-hulbert · 2026-04-19T12:26:33Z

+
+## Step 2: Subscribe to a channel and publish a message <a id="step-2"/>
+
+Messages contain the data that a client is communicating. Channels are named message streams — clients only receive messages published to channels they are subscribed to.


Channels are named message streams I'm not sure about this terminology.

m-hulbert · 2026-04-19T12:27:30Z

+Update `src/app/page.tsx` to include the `ChannelProvider`:
+
+<Code>
+```javascript


You could use the syntax highlighting of code blocks for items where we're adding lines in.

m-hulbert · 2026-04-19T12:29:16Z

+```
+</Code>
+
+Your client ID will appear in the presence list. Test with another client joining via the CLI:


Suggested change

Your client ID will appear in the presence list. Test with another client joining via the CLI:

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

m-hulbert · 2026-04-19T12:30:14Z

+
+Your completed application should look like this:
+
+![Screenshot of the completed Next.js Pub/Sub application showing a web interface with a presence panel listing online clients, a connection status indicator, a realtime message feed with blue left-border accents, and a message input field with a Publish button.](../../../images/content/screenshots/getting-started/pub-sub-nextjs-getting-started-guide.png)


That's a very long description of the image :-)

splindsay-92

Code looks good, just a few minor points :)

splindsay-92 · 2026-04-20T14:07:26Z

+
+## Step 2: Subscribe to a channel and publish a message <a id="step-2"/>
+
+Messages contain the data that a client is communicating. Channels are named message streams — clients only receive messages published to channels they are subscribed to.


I don't really see the utility in this statement, perhaps it's enough to say.. You can use the ChannelProvider to access the underlying channel, this enables you to publish and subscribe to messages on that channel. The the sections below just detail this?

splindsay-92 · 2026-04-20T14:09:51Z

+
+<Code>
+```shell
+ably channels publish my-first-channel 'Hello from CLI!'


Would it be better to mention subscribe here instead, since you're testing publishing via the component now?

splindsay-92 · 2026-04-20T14:20:37Z

+
+### Update globals.css <a id="step-4-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:


Should this be at the end or at the start? Considering it affects the look of the app as you build it, perhaps starting from the correct style state is better

maratal and others added 3 commits April 12, 2026 15:12

Generate PubSub NextJS guide (with previously generated skill).

5ed58af

feat(nextjs-guide): add screenshot of completed Next.js Pub/Sub app

16e3333

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

maratal added the review-app Create a Heroku review app label Apr 12, 2026

ably-ci temporarily deployed to ably-docs-dx-1001-pubsu-z1fi48 April 12, 2026 19:30 Inactive

maratal changed the title ~~feat: Add Next.js Pub/Sub getting-started guide~~ feat: Next.js Pub/Sub getting-started guide Apr 12, 2026

ably-ci temporarily deployed to ably-docs-dx-1001-pubsu-kkgpmz April 12, 2026 19:43 Inactive

Fix screenshot.

9d686fd

ably-ci temporarily deployed to ably-docs-dx-1001-pubsu-kkgpmz April 12, 2026 20:03 Inactive

ably-ci temporarily deployed to ably-docs-dx-1001-pubsu-kkgpmz April 12, 2026 21:14 Inactive

refactor(nextjs-guide): move AblyProvider setup into Step 1

9b6a35f

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

ably-ci temporarily deployed to ably-docs-dx-1001-pubsu-kkgpmz April 12, 2026 21:15 Inactive

refactor(nextjs-guide): move globals.css and screenshot to end of guide

7bf4ab2

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

ably-ci temporarily deployed to ably-docs-dx-1001-pubsu-kkgpmz April 12, 2026 22:32 Inactive

feat(nextjs-guide): add ably-nextjs-fundamentals-kit to next steps

03f7a6a

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

ably-ci temporarily deployed to ably-docs-dx-1001-pubsu-kkgpmz April 12, 2026 23:04 Inactive

maratal marked this pull request as ready for review April 13, 2026 09:05

maratal requested review from Copilot and m-hulbert April 16, 2026 12:45

Copilot started reviewing on behalf of maratal April 16, 2026 12:46 View session

Copilot AI reviewed Apr 16, 2026

View reviewed changes

m-hulbert requested a review from splindsay-92 April 19, 2026 12:22

m-hulbert reviewed Apr 19, 2026

View reviewed changes

splindsay-92 reviewed Apr 20, 2026

View reviewed changes

		import { AblyProvider } from './AblyProvider';

		export default function RootLayout({ children }: { children: React.ReactNode }) {

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


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

		Because the Ably Realtime client uses browser APIs such as WebSocket, it cannot run during server-side rendering. Create a new file `src/app/AblyProvider.tsx` that initializes the client inside a `useEffect` and wraps children in the `AblyProvider`:


		## Step 2: Subscribe to a channel and publish a message <a id="step-2"/>

		Messages contain the data that a client is communicating. Channels are named message streams — clients only receive messages published to channels they are subscribed to.

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


		Your completed application should look like this:

		![Screenshot of the completed Next.js Pub/Sub application showing a web interface with a presence panel listing online clients, a connection status indicator, a realtime message feed with blue left-border accents, and a message input field with a Publish button.](../../../images/content/screenshots/getting-started/pub-sub-nextjs-getting-started-guide.png)


		### Update globals.css <a id="step-4-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:

Conversation

maratal commented Apr 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

coderabbitai Bot commented Apr 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

splindsay-92 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

5 participants

maratal commented Apr 12, 2026 •

edited

Loading

coderabbitai Bot commented Apr 12, 2026 •

edited

Loading