> For the complete documentation index, see [llms.txt](https://trident-cas.sabn.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://trident-cas.sabn.xyz/socket-client-setup-and-authentication.md).

# Socket Client Setup & Authentication

### Authentication Mechanism

* For the socket connection to be authenticated, the JWT token must be passed in the `auth` object during the initial handshake.
* The backend verifies this token and attaches the user object to the socket session (`socket.user`).

### Installation

```bash
npm install socket.io-client
# or
yarn add socket.io-client
```

### Initialization Code

To authenticate, you must pass the token in the `auth` field of the configuration object.

#### Basic Setup

```javascript
import { io } from "socket.io-client";

// URL of your backend
// [NOTE]: Ask the backend team for this backend URL
const SOCKET_URL = process.env.NEXT_PUBLIC_API_URL || "http://localhost:4000";

// Retrieve the token from wherever you stored it (e.g., localStorage)
const token = localStorage.getItem("jwt_token");

export const socket = io(SOCKET_URL, {
    path: "/socket.io",
    transports: ["websocket"],
    auth: {
        token: token, // Sent during the handshake for authentication
    },
    autoConnect: true,
});

socket.on("connect", () => {
    console.log("Connected with ID:", socket.id);
});

socket.on("connect_error", err => {
    console.error("Connection failed:", err.message);
    // If error is 'Unauthorized', handle re-login
});
```

#### React Hook / Context Pattern

In a React or Next.js application, you can update the `auth` token dynamically if the user logs in after the initial connection.

```javascript
// lib/socket.js
import { io } from "socket.io-client";

const SOCKET_URL = process.env.NEXT_PUBLIC_API_URL || "http://localhost:4000";

export const socket = io(SOCKET_URL, {
    path: "/socket.io",
    transports: ["websocket"],
    autoConnect: false, // We control when to connect
});
```

```javascript
// Updating auth token and connecting
export const connectSocket = (token) => {
    socket.auth = { token };
    socket.connect();
};
```

```javascript
// hooks/useSocket.js
import { useEffect, useState } from "react";
import { socket } from "../lib/socket";

export const useSocket = () => {
    const [isConnected, setIsConnected] = useState(socket.connected);

    useEffect(() => {
        function onConnect() {
            setIsConnected(true);
            console.log("Socket connected");
        }

        function onDisconnect() {
            setIsConnected(false);
            console.log("Socket disconnected");
        }

        socket.on("connect", onConnect);
        socket.on("disconnect", onDisconnect);

        // Retrieve token and connect if available
        const token = localStorage.getItem("jwt_token");
        if (token && !socket.connected) {
            socket.auth = { token };
            socket.connect();
        }

        return () => {
            socket.off("connect", onConnect);
            socket.off("disconnect", onDisconnect);
        };
    }, []);

    return { socket, isConnected };
};
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://trident-cas.sabn.xyz/socket-client-setup-and-authentication.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.