⚡ react-native-real-time-nitro

High-performance WebSocket client for React Native

A blazing-fast WebSocket library built with native C++ for maximum performance

---

✨ Features

---

📦 Installation

$3

This library requires react-native-nitro-modules as a peer dependency:

``bash
npm install react-native-nitro-modules react-native-real-time-nitro
`

or

`bash
yarn add react-native-nitro-modules react-native-real-time-nitro
`

$3

---

🚀 Quick Start

`typescript
import { createWebSocket } from 'react-native-real-time-nitro'

const ws = createWebSocket()

// 📡 Setup callbacks
ws.onOpen = () => console.log('✅ Connected')
ws.onMessage = (msg) => console.log('📨 Received:', msg)
ws.onError = (error) => console.error('❌ Error:', error)
ws.onClose = (code, reason) => console.log('🔌 Closed:', code, reason)

// 🔗 Connect
await ws.connect('wss://echo.websocket.org')

// 📤 Send message
ws.send('Hello!')

// 👋 Close when done
ws.close(1000, 'Done')
`

---

📚 API Reference

$3

#### createWebSocket(): WebSocket

Creates a new WebSocket instance.

`typescript
import { createWebSocket } from 'react-native-real-time-nitro'

const ws = createWebSocket()
`

---

$3

---

$3

| Property | Type | Description |
|----------|------|-------------|
| state | WebSocketState (readonly) | Current connection state |
| url | string (readonly) | Connected WebSocket URL |

#### Connection States

`typescript
enum WebSocketState {
CONNECTING = 0, // 🔄 Connection in progress
OPEN = 1, // ✅ Connected and ready
CLOSING = 2, // ⏳ Closing in progress
CLOSED = 3 // 🔌 Connection closed
}
`

Example:
`typescript
if (ws.state === 1) {
ws.send('Message')
}
`

---

$3

| Callback | Parameters | Description |
|----------|------------|-------------|
| onOpen | () => void | ✅ Connection established |
| onMessage | (message: string) => void | 📨 Text message received |
| onBinaryMessage | (data: ArrayBuffer) => void | 📦 Binary data received |
| onError | (error: string) => void | ❌ Error occurred |
| onClose | (code: number, reason: string) => void | 🔌 Connection closed |

Example:
`typescript
ws.onOpen = () => console.log('✅ Connected!')
ws.onMessage = (msg) => console.log('📨', msg)
ws.onBinaryMessage = (data) => console.log('📦', new Uint8Array(data))
ws.onError = (error) => console.error('❌', error)
ws.onClose = (code, reason) => console.log('🔌', code, reason)
`

---

💡 Examples

$3

`typescript
import { createWebSocket } from 'react-native-real-time-nitro'
import { useEffect } from 'react'

export default function Chat() {
useEffect(() => {
const ws = createWebSocket()

ws.onOpen = () => {
console.log('✅ Connected to chat')
ws.send('Hello everyone!')
}

ws.onMessage = (msg) => {
console.log('💬 New message:', msg)
}

ws.connect('wss://chat-server.com')

return () => ws.close()
}, [])

return
}
`

$3

`typescript
const ws = createWebSocket()

ws.onBinaryMessage = (data) => {
const view = new Uint8Array(data)
console.log('📦 Received bytes:', view)
}

ws.onOpen = () => {
// Send binary data
const buffer = new ArrayBuffer(8)
const view = new Uint8Array(buffer)
view[0] = 0x48 // 'H'
view[1] = 0x65 // 'e'
view[2] = 0x6C // 'l'
view[3] = 0x6C // 'l'
view[4] = 0x6F // 'o'
ws.sendBinary(buffer)
}

await ws.connect('wss://binary-server.com')
`

$3

`typescript
const ws = createWebSocket()

// ✅ Use bundled CA certificates (recommended)
await ws.connect('wss://secure-server.com')

// 🔧 Or use custom certificate
ws.setCAPath('/path/to/custom-cert.pem')
await ws.connect('wss://secure-server.com')

// 🚨 Dev only: Disable verification
ws.setCAPath('')
await ws.connect('wss://dev-server.com')
`

$3

`typescript
const ws = createWebSocket()

// Send ping every 30 seconds (30000 milliseconds)
ws.setPingInterval(30000)

await ws.connect('wss://server.com')
`

---

🔍 Common Close Codes

| Code | Name | Description |
|------|------|-------------|
| 1000 | 🟢 Normal Closure | Normal closure; connection completed |
| 1001 | 🚪 Going Away | Endpoint going away (e.g., server shutdown) |
| 1002 | ❌ Protocol Error | Protocol error detected |
| 1003 | 🚫 Unsupported Data | Unsupported data type received |
| 1006 | ⚠️ Abnormal Closure | Abnormal closure (no close frame) |
| 1008 | 🛑 Policy Violation | Message violates policy |
| 1009 | 📏 Message Too Big | Message too large to process |
| 1011 | 💥 Internal Error | Internal server error |

---

🛠️ Troubleshooting

$3

> Problem: Cannot connect to WebSocket server

Solutions:
- ✅ Verify URL starts with ws:// or wss://
- ✅ Check server is running and accessible
- ✅ For SSL issues, try ws.setCAPath('') (dev only)
- ✅ Check network connectivity

$3

> Problem: send() doesn't work

Solutions:
- ✅ Ensure ws.state === 1 (OPEN state)
- ✅ Check onError callback for error messages
- ✅ Verify server is accepting messages
- ✅ Wait for onOpen callback before sending

$3

> Problem: Certificate verification fails

Solutions:
- ✅ Use setCAPath() with valid certificate bundle
- ✅ Ensure certificate includes intermediate certificates
- ✅ For development, disable with setCAPath('')`
- ✅ Check certificate expiration date

---

📄 License

MIT © Hoang Tuan

---

🔗 Links

---

Made with ❤️ by Hoang Tuan

_{Built with Nitro Modules • libwebsockets • mbedTLS}