Nazexa Logo
Nazexa Socket.IO v4 Engine
Next.js 15+ / React 19 Ready
Gateway: /socket.io

Connecting Your Project to Nazexa Socket Platform

Step-by-step developer integration guide for wiring Next.js, React, Node.js, and mobile applications into high-throughput multi-tenant WebSocket instances with zero-leakage token auth, instant room broadcasting, and live telemetry.

Real-Time Gateway Architecture

1. Overview & Protocol

Nazexa Socket Platform operates a high-concurrency WebSocket engine powered by Node.js, Socket.IO v4, and Next.js. It allows applications to communicate bidirectionally with microsecond latency, exchange state across multi-tenant rooms, and execute remote events with guaranteed delivery.

Gateway Path
/socket.io

Default Socket.IO multiplexing path with automatic WebSocket & HTTP long-polling fallback.

Transports
['websocket', 'polling']

Initiates WebSocket upgrade immediately; supports HTTP polling for restricted corporate firewalls.

Max Payload
1,000,000 bytes (1 MB)

High-capacity message buffers with built-in per-IP rate-limiting and connection throttling.


Credentials Setup

2. Prerequisites & Credentials

Before connecting an external project (e.g. a Next.js frontend, React SPA, or Node backend), ensure you have created a Socket Server in your Nazexa Dashboard:

1. Server Project ID

cly1234567890abcdef (cuid / UUID)

Unique identifier identifying your server cluster.

2. Project Secret Key

nsk_4f9a12c8e3b7...

32-byte cryptographic secret used for authenticating servers or issuing client tokens.

3. Gateway Endpoint

https://db.nazexa.com/ (or your production URL)

The host address running your Nazexa Socket Platform.

4. Allowed Origins (CORS)

https://nazexa.com/, https://your-app.com

Configured under Server Settings to allow browser cross-origin handshakes.

Install the official client library in your new project:
bash
npm install socket.io-client

High-Level Data Flow

3. Real-Time Architecture

Nazexa Socket Platform acts as a decoupled, standalone real-time hub. Client applications connect via WebSockets to listen for events and join dynamic rooms, while backend services can emit broadcasts over HTTP webhooks or direct sockets.

Next.js Client
Browser UI / React
socket.io-client
WebSocket────────►auth: { token / secret }
Nazexa Socket Server
Port 4000 (WS / HTTP)
Auth Guard & Multi-Tenant Rooms
HTTP Emit◄────────POST /internal/emit
Backend Microservice
API / Worker / Cron
Projects with Secret Key

Zero-Trust Security

4. Authentication Modes

Every incoming handshake at /socket.io passes through Nazexa's strict socketAuthMiddleware. The platform offers two primary authentication strategies depending on whether the client is a public browser or a trusted backend worker:

Strategy A
Server-to-Server

Project Secret Key Auth

Ideal for background workers, microservices, seeders, or internal tools. The client passes projectId and secretKey in the handshake payload.

⚠️ Never expose your secretKey in public client-side code (such as client React components or Mobile app bundles).
Strategy B (Recommended)
Web & Mobile Clients

Client Auth Tokens (JWT)

Recommended for public web applications. Your backend issues a short-lived, signed JWT via the Nazexa REST API. The browser connects using only this temporary token with granular scopes.

✅ Safe for public browsers: Tokens expire automatically (e.g. 4-24 hrs) and can be instantly revoked from the Nazexa Dashboard.
Generating Client Tokens via API

Before your frontend connects, your backend server (e.g. Next.js, Express) calls this endpoint to mint a safe client token:

typescript
// app/api/socket-token/route.ts
import { NextResponse } from 'next/server';
export async function GET() {
// 1. Resolve your local user session
const currentUserId = "user_98765";
const userEmail = "alex@acme.com";
// 2. Mint short-lived client token from Nazexa Socket Platform
const res = await fetch(
`${process.env.NEXT_PUBLIC_APP_URL}/api/servers/${process.env.NAZEXA_PROJECT_ID}/client-token`,
{
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-secret-key': process.env.NAZEXA_SECRET_KEY!,
},
body: JSON.stringify({
userId: currentUserId,
username: userEmail,
ttlHours: 4,
}),
}
);
const data = await res.json();
if (!res.ok) {
return NextResponse.json({ error: 'Failed to mint token' }, { status: 500 });
}
return NextResponse.json({ token: data.token });
}

Complete Project Integration

5. Client & Backend Integrations

Connect your new project with modern Next.js 14 / 15 / 16 practices. Select your project framework below to inspect the exact configuration:

Add the environment variables to your new project's .env.local:
bash
# .env.local in your new project
NEXT_PUBLIC_APP_URL="https://ws.nazexa.com"
NAZEXA_PROJECT_ID="your_project_id_from_dashboard"
NAZEXA_SECRET_KEY="nsk_your_project_secret_key"

Production React Hook

6. Custom useNazexaSocket Hook

Drop this enterprise-grade React hook directly into your new project at src/hooks/use-nazexa-socket.ts. It handles token resolution, connection lifecycle, automatic cleanup on unmount, and reconnect state:

typescript
'use client';
import { useEffect, useState, useRef, useCallback } from 'react';
import { io, Socket } from 'socket.io-client';
export function useNazexaSocket({
url = 'https://ws.nazexa.com',
token,
tokenEndpoint = '/api/socket-token',
room,
}: {
url?: string;
token?: string;
tokenEndpoint?: string;
room?: string;
} = {}) {
const [isConnected, setIsConnected] = useState(false);
const [socketId, setSocketId] = useState<string | null>(null);
const [error, setError] = useState<string | null>(null);
const socketRef = useRef<Socket | null>(null);
useEffect(() => {
let isCancelled = false;
let currentSocket: Socket | null = null;
async function init() {
try {
let activeToken = token;
if (!activeToken && tokenEndpoint) {
const res = await fetch(tokenEndpoint);
const data = await res.json();
activeToken = data.token;
}
if (isCancelled) return;
const socketInstance: Socket = io(url, {
path: '/socket.io',
auth: { token: activeToken },
transports: ['websocket', 'polling'],
});
currentSocket = socketInstance;
socketRef.current = socketInstance;
socketInstance.on('connect', () => {
if (!isCancelled) {
setIsConnected(true);
setSocketId(socketInstance.id || null);
if (room) socketInstance.emit('room:join', room);
}
});
socketInstance.on('disconnect', () => {
if (!isCancelled) setIsConnected(false);
});
socketInstance.on('connect_error', (err) => {
if (!isCancelled) setError(err.message);
});
} catch (err: any) {
if (!isCancelled) setError(err.message);
}
}
void init();
return () => {
isCancelled = true;
currentSocket?.disconnect();
};
}, [url, token, tokenEndpoint, room]);
const emitEvent = useCallback((event: string, data: unknown, targetRoom?: string) => {
socketRef.current?.emit('event:emit', {
event,
room: targetRoom || room,
data,
});
}, [room]);
return { socket: socketRef.current, isConnected, socketId, error, emitEvent };
}

Room Partitioning

7. Multi-Tenant Rooms

Nazexa Socket Platform isolates event streams using logical rooms. When a socket joins a room, the platform tracks active occupant counters and fires live telemetry to your admin dashboard.

Joining a Room
socket.emit('room:join', 'chat:workspace_12');

Joins the specified channel. Automatically updates active room counters in the database.

Leaving a Room
socket.emit('room:leave', 'chat:workspace_12');

Unsubscribes from events. If member count reaches 0, the room is marked inactive.

Automatic Built-In Rooms:
  • user:<externalId>: Each authenticated socket automatically joins its personal user room for direct user-to-user notifications.
  • server:<serverId>: Auto-joined room for server-wide broadcasts affecting all clients connected to this instance.

Event Flow

8. Bidirectional Events

Clients emit messages using the unified event:emit event. The Nazexa gateway verifies rate limits, checks for the socket:write scope, logs the event size for telemetry, and forwards it to the target room:

typescript
// 1. Define your payload interface
interface DocumentPayload {
documentId: string;
savedBy: string;
updatedAt: string;
}
// 2. Publishing an event to a room from client
socket.emit('event:emit', {
room: 'project:abc1234',
event: 'document:saved',
data: {
documentId: 'doc_55',
savedBy: 'alex',
updatedAt: new Date().toISOString(),
} satisfies DocumentPayload,
});
// 3. Listening for that event with strict typing
socket.on('document:saved', (payload: DocumentPayload) => {
console.log('Document updated by peer:', payload.savedBy);
});

Serverless & Microservices

9. Backend Webhook Emitter

If your background jobs run on serverless functions (e.g. Vercel, AWS Lambda) where persistent WebSockets are not ideal, you can emit events to connected users via a simple HTTP POST request to /internal/emit:

typescript
// lib/nazexa-emitter.ts
export async function emitServerEvent(room: string, event: string, data: unknown) {
const res = await fetch('https://ws.nazexa.com/internal/emit', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
projectId: process.env.NAZEXA_PROJECT_ID,
secretKey: process.env.NAZEXA_SECRET_KEY,
room,
event,
data,
}),
});
if (!res.ok) {
throw new Error('Failed to emit real-time event');
}
}

Diagnostics

10. Troubleshooting & FAQ

ERR: CORS Origin Blocked / Handshake Failure

Go to your server's Settings in the Nazexa Dashboard and verify that allowedOrigins contains your frontend domain (e.g. https://nazexa.com/ or *).

ERR: INVALID_CREDENTIALS / AUTHENTICATION_REQUIRED

The client must supply either auth: { token: '...' } or auth: { projectId, secretKey } in the initial handshake. Verify that the secret key hasn't been regenerated.

WARN: RATE_LIMITED: Event emission rate limit exceeded

Individual sockets are subject to per-minute event ceilings to protect server health. Adjust rateLimitPerMinute in your server settings if higher throughput is required.

Ready to test your connection?

Open your server details to watch live connection telemetry as you connect.