HN
HubNestv1.4.0
Get Started
Quickstart Guides

React / Next.js Quickstart

Complete end-to-end guide to embedding real-time in-app notification centers (<Inbox />), toast alerts, and event triggers in React and Next.js applications.

1

1. Sign Up & Get API Credentials

Register at https://app.hubnest.io. Go to Developer → API Keys → Generate New Key to get your secret key (hn_live_...). Save the key as NEXT_PUBLIC_HUBNEST_API_KEY or use a backend session token to authenticate your frontend user subscribers safely.

Security Note for Client Apps
In production, generate temporary subscriber tokens on your backend instead of exposing full secret API keys in client-side code.
2

2. Install @hubnest/react Package

Install the React notification center library and STOMP WebSocket dependencies:

terminal/install.sh
bash
1npm install @hubnest/react @stomp/stompjs lucide-react
2
3# Or using yarn:
4yarn add @hubnest/react @stomp/stompjs lucide-react
3

3. Wrap App with <HubNestProvider>

Wrap your root app component (layout.tsx in Next.js App Router or _app.tsx in Pages Router) with HubNestProvider to initialize the real-time STOMP WebSocket connection:

app/layout.tsx
typescript
1'use client';
2
3import { HubNestProvider } from '@hubnest/react';
4
5export default function RootLayout({ children }: { children: React.ReactNode }) {
6 return (
7 <html lang="en">
8 <body>
9 <HubNestProvider
10 apiUrl="https://api.hubnest.io"
11 apiKey={process.env.NEXT_PUBLIC_HUBNEST_API_KEY!}
12 subscriberId="user_12345"
13 >
14 {children}
15 </HubNestProvider>
16 </body>
17 </html>
18 );
19}
4

4. Embed <Inbox /> Notification Center

Add the interactive <Inbox /> bell icon and slide-out notification drawer anywhere in your navigation bar or user dashboard:

components/Header.tsx
typescript
1'use client';
2
3import { Inbox, NotificationFeed } from '@hubnest/react';
4
5export function Header() {
6 return (
7 <header className="flex justify-between items-center px-6 py-4 bg-slate-900 border-b border-slate-800 text-white">
8 <h1 className="text-xl font-bold">My Dashboard</h1>
9
10 {/* Real-time Notification Bell & Feed Drawer */}
11 <div className="relative">
12 <Inbox
13 theme="dark"
14 position="bottom-end"
15 onNotificationClick={(notification) => {
16 console.log('Clicked notification:', notification);
17 if (notification.payload?.actionUrl) {
18 window.location.href = notification.payload.actionUrl as string;
19 }
20 }}
21 />
22 </div>
23 </header>
24 );
25}
5

5. Real-Time WebSockets & Toast Alerts

Listen to incoming real-time notifications programmatically and display dynamic toast popups using the useHubNest hook:

components/NotificationListener.tsx
typescript
1'use client';
2
3import { useHubNest } from '@hubnest/react';
4import { useEffect } from 'react';
5
6export function NotificationListener() {
7 const { subscribe, unreadCount } = useHubNest();
8
9 useEffect(() => {
10 // Subscribe to live incoming notifications via WebSocket
11 const unsubscribe = subscribe((notification) => {
12 console.log('New notification received:', notification.title, notification.body);
13 // Display browser toast or audio chime here
14 });
15
16 return () => unsubscribe();
17 }, [subscribe]);
18
19 return <div className="text-xs text-slate-400">Unread notifications: {unreadCount}</div>;
20}
6

6. Trigger In-App Notification Event

Trigger an event from your Next.js Server Action or backend API route to deliver an instant message into the user's inbox drawer:

app/api/notify/route.ts
typescript
1import { NextResponse } from 'next/server';
2
3export async function POST(req: Request) {
4 const { userId, message } = await req.json();
5
6 const res = await fetch('https://api.hubnest.io/api/v1/events', {
7 method: 'POST',
8 headers: {
9 'Authorization': `Bearer ${process.env.HUBNEST_API_KEY}`,
10 'Content-Type': 'application/json'
11 },
12 body: JSON.stringify({
13 eventName: 'inbox.welcome',
14 to: { subscriberId: userId },
15 payload: {
16 title: '🎉 Welcome to the Platform!',
17 body: message || 'Your account setup is complete. Click to explore.',
18 actionUrl: '/dashboard/settings'
19 }
20 })
21 });
22
23 const data = await res.json();
24 return NextResponse.json(data);
25}
7

7. Customize Theme & Dark Mode

Style the notification drawer, unread badge colors, and fonts using CSS variables or custom Tailwind classes:

styles/globals.css
css
1/* Customizing HubNest Notification Bell & Inbox Palette */
2:root {
3 --hn-inbox-bg: #0f172a;
4 --hn-inbox-border: #1e293b;
5 --hn-badge-bg: #6366f1;
6 --hn-badge-text: #ffffff;
7 --hn-item-hover: #1e293b;
8 --hn-text-primary: #f8fafc;
9 --hn-text-secondary: #94a3b8;
10}
8

8. Verify Delivery in Logs

Go to Developer → Logs at https://app.hubnest.io to monitor real-time WebSocket connection state, message dispatch latency, and read status tracking for all connected React clients.

Real-time Read States
When users click or open notifications in <Inbox />, read states are automatically synchronized across all open browser tabs via WebSockets.

Next steps

AWS SES Email

Configure AWS SES IAM keys, verified domains, and sending rate limits.

SendGrid Email

Connect SendGrid API Keys and verified sender identities.

Twilio SMS Provider

Connect Twilio Account SID, Auth Token, and phone numbers.

WhatsApp Business

Connect Meta WhatsApp Cloud API access tokens and phone number IDs.

Was this guide helpful?