[DX-531] Getting started guide for NextJS

[maratal]

Description

Getting started guide for NextJS and React using Pub/Sub.

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

Checklist

• Commits have been rebased.
• Linting has been run against the changed file(s).
• The PR adheres to the writing style guide and contribution guide.

[coderabbitai]

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: bae64086-c550-4422-9be4-f8b8b29a6078

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-531-nextjs-push-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

• X
• Mastodon
• Reddit
• LinkedIn

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

[splindsay-92]

Before I start the review, I checked the ticket which states this is a Getting started guide for NextJS and React using Pub/Sub. Is this guide supposed to just be a NextJS with plain ably-js, is there a NextJS + React coming too? :)

[maratal]

Before I start the review, I checked the ticket which states this is a Getting started guide for NextJS and React using Pub/Sub. Is this guide supposed to just be a NextJS with plain ably-js, is there a NextJS + React coming too? :)

Oops, that's where lack of experience in platforms can bite. I wasn't aware that it's possible to use ably differently with NextJS (plain and hooks) to even ask this question. And now I'm not sure whether it worth two separate guides or put second set of code blocks into the same guide or go solo on hooks variant. WDYT @m-hulbert @splindsay-92

[splindsay-92]

Before I start the review, I checked the ticket which states this is a Getting started guide for NextJS and React using Pub/Sub. Is this guide supposed to just be a NextJS with plain ably-js, is there a NextJS + React coming too? :)

Oops, that's where lack of experience in platforms can bite. I wasn't aware that it's possible to use ably differently with NextJS (plain and hooks) to even ask this question. And now I'm not sure whether it worth two separate guides or put second set of code blocks into the same guide or go solo on hooks variant. WDYT @m-hulbert @splindsay-92

No worries at all! If you checkout https://github.com/ably/ably-nextjs-fundamentals-kit, this shows best practice for using ably-js react hooks and providers with NextJS (there are some gotchas which is why we put this together) :)

My personal opinion is that a common use-case is Vercel + NextJS + React as a stack, so it would be good to either have a built example app or a guide for NextJs + React at least :)

[m-hulbert]

I think we should have them as standalone guides rather than trying to mix languages in the getting started ones. As Steven says, React + NextJS has a few things that trip people up, so I think it would be worth updating to use hooks if you don't mind @maratal

[maratal]

Before I start the review, I checked the ticket which states this is a Getting started guide for NextJS and React using Pub/Sub. Is this guide supposed to just be a NextJS with plain ably-js, is there a NextJS + React coming too? :)

Oops, that's where lack of experience in platforms can bite. I wasn't aware that it's possible to use ably differently with NextJS (plain and hooks) to even ask this question. And now I'm not sure whether it worth two separate guides or put second set of code blocks into the same guide or go solo on hooks variant. WDYT @m-hulbert @splindsay-92

No worries at all! If you checkout https://github.com/ably/ably-nextjs-fundamentals-kit, this shows best practice for using ably-js react hooks and providers with NextJS (there are some gotchas which is why we put this together) :)

My personal opinion is that a common use-case is Vercel + NextJS + React as a stack, so it would be good to either have a built example app or a guide for NextJs + React at least :)

@splindsay-92 @m-hulbert I asked claude and this is the response:

  What adding Ably React hooks/providers would mean in practice:                                                                                                                                          
                             
  The key problem is that Ably's React hooks (AblyProvider, useChannel, etc.) cover the Pub/Sub layer — they don't provide any abstraction for push-specific operations. Things like                      
  realtime.push.activate(), realtime.device(), channel.push.subscribeDevice(), and push.admin.publish() all have to use the lower-level API regardless.
                                                                                                                                                                                                          
  So you'd end up in an awkward middle ground:                                                                                                                                                            
   
  - Client initialization → wrapped in AblyProvider                                                                                                                                                       
  - Channel message subscription → replaced with useChannel
  - Everything push-related → still raw SDK calls via useAbly()                                                                                                                                           
                                                                                                                                                                                                          
  That's a partial refactor that adds complexity (provider wrapper, component splitting for hook usage) without meaningfully simplifying the push-specific code, which is the whole point of the guide.   
                                                                                                                                                                                                          
  My view: The hooks/providers pattern makes more sense as a separate guide focused on Pub/Sub use cases with Next.js, where it genuinely simplifies things. Shoehorning it into this push notifications  
  guide would make the guide harder to follow without much payoff. Better to:
                                                                                                                                                                                                          
  1. Merge this PR as-is (push notifications with plain ably-js)                                                                                                                                          
  2. Create a separate guide for Next.js + Pub/Sub using React hooks/providers
                                                                                                                                                                                                          
  That maps cleanly to two guides instead of one confusing hybrid.   

[maratal]

React hooks rewrite

Updated the guide to use the new React hooks from ably/ably-js#2187 (usePushActivation, usePush, useAbly, useChannel, AblyProvider, ChannelProvider).

Structure change

The monolithic PushPage component is replaced by four focused files:

File	Responsibility
page.tsx	Entry point — dynamic(() => import('./PushApp'), { ssr: false })
PushApp.tsx	AblyProvider + ChannelProvider setup, shared log state
PushActivationBanner.tsx	usePushActivation + useAbly
ChannelSubscription.tsx	usePush + useChannel + service worker listener
NotificationLog.tsx	Pure presentational, no Ably dependency

Key changes

SSR handling: The previous guide created the Ably client inside useEffect to avoid SSR. The new guide uses dynamic with ssr: false on the page entry point, which means PushApp.tsx is only ever loaded client-side and the client can be safely instantiated at module scope — cleaner than managing a ref.

Activation (PushActivationBanner): usePushActivation() replaces manual calls to realtime.push.activate(). Returns localDevice (reactive, persisted across page loads via localStorage) — used to guard the send-to-device/client buttons so client.device() is never called before activation.

Channel subscriptions (ChannelSubscription): usePush(channelName) replaces channelRef.current.push.subscribeDevice(). The isActivated flag it returns is reactive — when PushActivationBanner calls activate(), the subscribe buttons in ChannelSubscription enable automatically with no extra wiring, via a shared module-level store in PushActivationState.ts. The channel returned by usePush is used directly for publishing, removing the need for a separate channelRef.

Realtime messages: useChannel replaces the manual channel.subscribe() call inside useEffect.

Error handling: connectionError and channelError come directly from usePush rather than being managed as separate state.

Service worker: unchanged.