React Socketeer

A powerful React library for Socket.IO integration with built-in real-time communication features.

Table of Contents

• Features
• Installation
• Quick Start
  • 1. Wrap your app with SocketProvider
  • 2. Use hooks in your components
• Next.js Integration
  • Installation for Next.js
  • Setting up the Socket Server
  • Client-Side Integration
• Core Features
  • Type-Safe User Data
  • Available Hooks
• Advanced Usage
  • Custom Socket Configuration
  • Server Setup Example
• API Reference
  • SocketProvider Props
  • useSocket() Return Values
• Troubleshooting
• Contributing
• License

Features

• 🚀 Real-time messaging (global/private/room)
• 👥 User presence tracking
• 🔒 Type-safe API with TypeScript support
• ⚡ React hooks for easy integration
• 🔄 Automatic reconnection handling
• 🛠️ Extensible with custom user data

Installation

npm install react-socketeer socket.io-client
# or
yarn add react-socketeer socket.io-client

Quick Start

1. Wrap your app with SocketProvider

import { SocketProvider } from 'react-socketeer';

function App() {
  return (
    <SocketProvider socketUrl="http://localhost:3000">
      <ChatApp />
    </SocketProvider>
  );
}

2. Use hooks in your components

import { useSocket, useGlobalChat } from 'react-socketeer';

function ChatApp() {
  const { isConnected, handleLogin } = useSocket();
  const { messages, sendMessage } = useGlobalChat();

  return (
    <div>
      {messages.map((msg) => (
        <div key={msg.timestamp}>{msg.username}: {msg.text}</div>
      ))}
      <button onClick={() => sendMessage('Hello!')}>Send</button>
    </div>
  );
}

Core Features

Type-Safe User Data

Define custom user data types and use them throughout your app:

interface UserProfile {
  age: number;
  preferences: {
    theme: 'light' | 'dark';
    notifications: boolean;
  };
}

// In your component
const { setUserData, userData } = useSocket<UserProfile>();

// Update user data
setUserData({
  age: 30,
  preferences: {
    theme: 'dark',
    notifications: true
  }
});

Available Hooks

1. useSocket() - Core socket functionality
2. useGlobalChat() - Global messaging
3. usePrivateChat() - Direct messaging
4. useRoom() - Room-based communication

Next.js Integration

Installation for Next.js

npm install react-socketeer socket.io-client socket.io
# or
yarn add react-socketeer socket.io-client socket.io
# or
pnpm add react-socketeer socket.io-client socket.io

# Run the setup command
npx react-socketeer setup-nextjs [options]

Setting up the Socket Server

Create a custom server file in your Next.js project:

// server.ts
import { createServer } from 'http'
import { parse } from 'url'
import next from 'next'
import { Server as SocketIOServer } from 'socket.io'

const dev = process.env.NODE_ENV !== 'production'
const app = next({ dev })
const handle = app.getRequestHandler()

app.prepare().then(() => {
  const server = createServer((req, res) => {
    const parsedUrl = parse(req.url!, true)
    handle(req, res, parsedUrl)
  })
  
  const io = new SocketIOServer(server, {
    cors: {
      origin: '*',
      methods: ['GET', 'POST']
    }
  })
  
  io.on('connection', (socket) => {
    console.log('Client connected')
    
    socket.on('login', (username) => {
      socket.username = username
      io.emit('user_joined', { username })
    })
    
    socket.on('send_message', (message) => {
      io.emit('new_message', {
        username: socket.username,
        text: message,
        timestamp: Date.now()
      })
    })
    
    socket.on('disconnect', () => {
      console.log('Client disconnected')
    })
  })
  
  server.listen(3000, () => {
    console.log('> Ready on http://localhost:3000')
  })
})

Update your package.json to use the custom server:

"scripts": {
  "dev": "ts-node --project tsconfig.server.json server.ts",
  "build": "next build",
  "start": "NODE_ENV=production ts-node --project tsconfig.server.json server.ts"
}

Client-Side Integration

Create a SocketProvider component in your Next.js app:

// app/providers.tsx
'use client'

import { SocketProvider as BaseSocketProvider } from 'react-socketeer'

export function SocketProvider({ children }: { children: React.ReactNode }) {
  return (
    <BaseSocketProvider 
      socketUrl={process.env.NEXT_PUBLIC_SOCKET_URL || 'http://localhost:3000'}
    >
      {children}
    </BaseSocketProvider>
  )
}

Wrap your app with the provider in your layout:

// app/layout.tsx
import { SocketProvider } from './providers'

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <SocketProvider>
          {children}
        </SocketProvider>
      </body>
    </html>
  )
}

Use the hooks in your client components:

// app/chat.tsx
'use client'

import { useState } from 'react'
import { useSocket, useGlobalChat } from 'react-socketeer'

export default function ChatComponent() {
  const { isConnected, handleLogin } = useSocket()
  const { messages, sendMessage } = useGlobalChat()
  const [username, setUsername] = useState('')
  const [message, setMessage] = useState('')
  
  const handleLoginSubmit = (e: React.FormEvent) => {
    e.preventDefault()
    if (username) handleLogin(username)
  }
  
  const handleSendMessage = (e: React.FormEvent) => {
    e.preventDefault()
    if (message) {
      sendMessage(message)
      setMessage('')
    }
  }
  
  return (
    <div>
      {!isConnected ? (
        <form onSubmit={handleLoginSubmit}>
          <input 
            value={username}
            onChange={(e) => setUsername(e.target.value)}
            placeholder="Enter username"
          />
          <button type="submit">Join Chat</button>
        </form>
      ) : (
        <div>
          <div>
            {messages.map((msg, i) => (
              <div key={i}>
                <strong>{msg.username}:</strong> {msg.text}
              </div>
            ))}
          </div>
          <form onSubmit={handleSendMessage}>
            <input
              value={message}
              onChange={(e) => setMessage(e.target.value)}
              placeholder="Type a message"
            />
            <button type="submit">Send</button>
          </form>
        </div>
      )}
    </div>
  )
}

Advanced Usage

Custom Socket Configuration

<SocketProvider
  socketUrl="http://localhost:3000"
  socketOptions={{
    reconnection: true,
    reconnectionAttempts: 5,
    transports: ['websocket']
  }}
>
  {children}
</SocketProvider>

Server Setup Example

const io = require('socket.io')(server);

io.on('connection', (socket) => {
  socket.on('login', (username) => {
    socket.username = username;
    io.emit('user_joined', { username });
  });

  socket.on('send_message', (message) => {
    io.emit('new_message', {
      username: socket.username,
      text: message,
      timestamp: Date.now()
    });
  });
});

API Reference

SocketProvider Props

| Prop | Type | Description | |------|------|-------------| | socketUrl | string | Socket server URL | | socketOptions | object | Socket.IO client options | | userDataTransformer | function | Transforms incoming user data |

useSocket() Return Values

| Property | Type | Description | |----------|------|-------------| | socket | Socket | Socket.IO instance | | isConnected | boolean | Connection status | | setUserData | function | Update user data | | userData | T | Current user data | | ... | ... | ... |

Troubleshooting

Connection Issues:

• Verify server is running
• Check CORS settings
• Enable debug mode: socketOptions: { debug: true }

Type Errors:

• Ensure proper type definitions
• Use generic types consistently

Contributing

PRs welcome! Please follow existing code style and add tests for new features.

License

MIT