Getting started

npm install react-native-fast-ws --save

[!NOTE] This package requires React Native 0.76 or higher. You must also install and configure Nitro Modules to use this package.

[!WARNING] This library is still under development. Use at your own risk. The API is experimental and subject to change. This project explores new ideas and approaches to WebSocket and Blob APIs, thanks to Nitro, and its scope may change.

Usage

This library implements the WebSocket Web API and is meant to be a drop-in replacement for React Native's WebSocket implementation.

import { WebSocket } from 'react-native-fast-ws';

// Create a new WebSocket instance
const ws = new WebSocket('wss://echo.websocket.org');

// Using event listeners (recommended)
ws.addEventListener('open', (event) => {
  console.log('Connected to server');
  ws.send('Hello Server!');
});

// Or using event handlers
ws.onopen = (event) => {
  console.log('Connected to server');
};

// Listen to messages
ws.addEventListener('message', (event) => {
  console.log('Received:', event.data);
});

// Send different types of data
ws.send('Plain text message');
ws.send(new Blob('string'));
ws.send(new Uint8Array([1, 2, 3, 4]));

// Close the connection when done
ws.close();

[!NOTE] When setting binaryType to 'blob', the library will dispatch MessageEvents with Blob objects. This is experimental and incompatible with React Native's Blob. We're working on a more comprehensive API for this and other networking modules. If you would like to stay informed, let us know.

For more detailed information about the WebSocket API, check out the MDN WebSocket documentation.

Differences with React Native

• Can create Blobs from ArrayBuffer, ArrayBufferView too. With React Native, you can only create Blob from string or another Blob
• Each Blob has text(), arrayBuffer(), and stream() methods. With React Native, you can only access the contents of Blob via custom data field
• Blob does not depend on a native module. Uses ArrayBuffers natively, thanks to Nitro Modules. With React Native, Blob uses RCTBlobManager under the hood to create and hold references to the data.
• Blob is automatically deallocated when no longer in use. You don't have to close() it manually
• You can send Blob, ArrayBuffer, and ArrayBufferView objects directly. With React Native, they are serialized and sent as base64 strings
• Uses direct callbacks per WebSocket instance. React Native broadcasts all events to JS and filters by connection ID, which is less efficient
• It will throw when attempting to close WebSocket connection with a code other than 1000 or outside of range 3000-4999. This is spec compliant behavior and something not supported by React Native's WebSocket implementation

Benchmarks

[!NOTE] Benchmarks shown below operate in controlled environments and may not accurately reflect real-world performance. Results can vary significantly based on factors such as:

• Device model and OS version
• Network conditions and latency
• Message payload size and type
• Application state and concurrent operations

These benchmarks are provided to demonstrate theoretical performance benefits and should be used as a general reference rather than absolute performance indicators.

You can browse the benchmark code here and check each message payload here.

Small JSON payload - Text

Small JSON payload - Binary

Large JSON payload - Text

Large JSON payload - Binary

Large Binary (Image - 234KB)

Methodology

All tests were performed with local WebSocket server to minimize network variance. Each test was run enough times to have 10 samples, after removing outliers.

In the future, we would like to add benchmarks for:

• CPU usage during message processing
• Memory footprint during large transfers
• Connection establishment time
• Concurrent connection handling
• Message latency under high load

Your contributions are welcome! Check out our contributing guidelines to help improve these benchmarks.

Made with ❤️ at Callstack

React Native FastWS is an open source project and will always remain free to use. If you think it's cool, please star it 🌟. Callstack is a group of React and React Native geeks, contact us at [email protected] if you need any help with these or just want to say hi!

Like the project? ⚛️ Join the team who does amazing stuff for clients and drives React Native Open Source! 🔥