You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
We welcome contributions! Whether it's bug fixes, feature improvements, or documentation updates, your help is appreciated.
4
+
5
+
This project follows the [Contributor Covenant](https://www.contributor-covenant.org/version/2/1/code_of_conduct/) Code of Conduct. By participating, you are expected to uphold this code.
6
+
7
+
## Commit Messages
8
+
9
+
We use [Conventional Commits](https://www.conventionalcommits.org/) for clear communication and automated versioning. Please format your commit messages as follows:
10
+
11
+
```
12
+
type(scope): description
13
+
14
+
[optional body]
15
+
[optional footer]
16
+
```
17
+
18
+
Where `type` is one of:
19
+
-`feat:` New features
20
+
-`fix:` Bug fixes
21
+
-`docs:` Documentation changes
22
+
-`chore:` Maintenance tasks
23
+
-`test:` Adding or updating tests
24
+
-`refactor:` Code changes that neither fix bugs nor add features
25
+
26
+
## Development
27
+
28
+
This library is built with [Nitro](https://mrousavy.github.io/nitro). After making changes to native code, you must run:
29
+
30
+
```bash
31
+
npm run codegen
32
+
```
33
+
34
+
This regenerates the necessary bindings between JavaScript and native code.
35
+
36
+
## Working on the Example App
37
+
38
+
Install dependencies:
39
+
```bash
40
+
npm install
41
+
```
42
+
43
+
Then, follow these steps to run the app on iOS:
44
+
```bash
45
+
cd ./example && npm run ios
46
+
```
47
+
48
+
or on Android:
49
+
```bash
50
+
cd ./example && npm run android
51
+
```
52
+
53
+
You can also open the example project directly in Xcode (`example/ios/NitroPlayground.xcworkspace`) or Android Studio (`example/android`) for native development.
54
+
55
+
Make sure to run the WebSocket server in the background:
56
+
```bash
57
+
cd ./example && bun server.ts
58
+
```
59
+
60
+
Otherwise, the app will not be able to connect to the server and will fail with a connection error.
> 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.
> This package requires React Native 0.76 and New Architecture. You must also install and configure [Nitro Modules](https://github.com/mrousavy/nitro) to use this package.
17
24
18
-
### TODOs
25
+
> [!WARNING]
26
+
> 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.
27
+
28
+
### Usage
29
+
30
+
This library implements the [WebSocket Web API](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket) and is meant to be a drop-in replacement for React Native's WebSocket implementation.
19
31
20
-
- Document things not implemented in spec, or different from spec
21
-
- Fix outstanding (and known) issues
22
-
- Figure out a better name and logo
23
-
- Stable release at [React Native London Conf](https://www.reactnativelondon.co.uk)
If you want to contribute, please reach out (you can find me on [X/Twitter](https://x.com/grabbou)).
36
+
// Using event listeners (recommended)
37
+
ws.addEventListener('open', (event) => {
38
+
console.log('Connected to server');
39
+
ws.send('Hello Server!');
40
+
});
41
+
42
+
// Or using event handlers
43
+
ws.onopen= (event) => {
44
+
console.log('Connected to server');
45
+
};
46
+
47
+
// Listen to messages
48
+
ws.addEventListener('message', (event) => {
49
+
console.log('Received:', event.data);
50
+
});
51
+
52
+
// Send different types of data
53
+
ws.send('Plain text message');
54
+
ws.send(newBlob(['Binary data']));
55
+
ws.send(newUint8Array([1, 2, 3, 4]));
56
+
57
+
// Close the connection when done
58
+
ws.close();
59
+
```
60
+
61
+
For more detailed information about the WebSocket API, check out the [MDN WebSocket documentation](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket).
28
62
29
63
### Differences with React Native
30
64
31
-
**Blob**
32
-
- Can create `Blob` from `ArrayBuffer`, `ArrayBufferView`, `Blob`, or `string`. With React Native, [you can only create Blob from string or another Blob](https://github.com/facebook/react-native/blob/main/packages/react-native/Libraries/Blob/BlobManager.js#L69-L73)
33
-
- Has `text()`, `arrayBuffer()`, and `stream()` methods. With React Native, you can only access the contents of `Blob` via [custom `data` field](https://github.com/facebook/react-native/blob/main/packages/react-native/Libraries/Blob/Blob.js#L75-L82)
34
-
- Does not depend on a native module. Uses `ArrayBuffer`s natively, thanks to Nitro Modules. With React Native, [Blob uses `RCTBlobManager` under the hood](https://github.com/facebook/react-native/blob/bd323929dc5be5666ee36043babec7d981a095dc/packages/react-native/Libraries/Blob/RCTBlobManager.h#L15) to create and hold references to the data
35
-
- Automatically deallocated when no longer in use. [You don't have to `close()` it manually](https://github.com/facebook/react-native/blob/bd323929dc5be5666ee36043babec7d981a095dc/packages/react-native/Libraries/Blob/Blob.js#L122-L138)
65
+
- Can create `Blob`s from `ArrayBuffer`, `ArrayBufferView` too. With React Native, [you can only create Blob from string or another Blob](https://github.com/facebook/react-native/blob/af384a914a4e9ef6a5d25b00bc14b0483e5af879/packages/react-native/Libraries/Blob/BlobManager.js#L69-L73)
66
+
- Each `Blob` has `text()`, `arrayBuffer()`, and `stream()` methods. With React Native, you can only access the contents of `Blob` via [custom `data` field](https://github.com/facebook/react-native/blob/af384a914a4e9ef6a5d25b00bc14b0483e5af879/packages/react-native/Libraries/Blob/Blob.js#L75-L82)
67
+
-`Blob` does not depend on a native module. Uses `ArrayBuffer`s natively, thanks to Nitro Modules. With React Native, [Blob uses `RCTBlobManager` under the hood](https://github.com/facebook/react-native/blob/bd323929dc5be5666ee36043babec7d981a095dc/packages/react-native/Libraries/Blob/RCTBlobManager.h#L15) to create and hold references to the data.
68
+
-`Blob` is automatically deallocated when no longer in use. [You don't have to `close()` it manually](https://github.com/facebook/react-native/blob/bd323929dc5be5666ee36043babec7d981a095dc/packages/react-native/Libraries/Blob/Blob.js#L122-L138)
69
+
- You can send `Blob`, `ArrayBuffer`, and `ArrayBufferView` objects directly. [With React Native, they are serialized and sent as base64 strings](https://github.com/facebook/react-native/blob/af384a914a4e9ef6a5d25b00bc14b0483e5af879/packages/react-native/Libraries/WebSocket/WebSocket.js#L201-L203)
70
+
- Uses direct callbacks per WebSocket instance. [React Native broadcasts all events to JS and filters by connection ID, which is less efficient](https://github.com/facebook/react-native/blob/af384a914a4e9ef6a5d25b00bc14b0483e5af879/packages/react-native/React/CoreModules/RCTWebSocketModule.mm#L144-L157)
36
71
37
-
**Websockets**
38
-
- Emits events (`open`, `message`, `error`, `close`) that extend from [`Event`](https://dom.spec.whatwg.org/#event)
39
-
- On iOS, uses built-in APIs for WebSockets (available on iOS 13+). React Native uses `SocketRocket` instead
40
-
- Uses callbacks instead of `RCTEventEmitter` to communicate new messages back to the JavaScript
72
+
### Benchmarks
41
73
42
-
### Compatibility table
74
+
> [!NOTE]
75
+
> Benchmarks shown below operate in controlled environments and may not accurately reflect real-world performance. Results can vary significantly based on factors such as:
76
+
> - Device model and OS version
77
+
> - Network conditions and latency
78
+
> - Message payload size and type
79
+
> - Application state and concurrent operations
43
80
44
-
The table below compares the features and APIs available in react-native-fast-ws against the [WebSocket specification](https://websockets.spec.whatwg.org/)and React Native's built-in WebSocket implementation. A ✅ indicates full support, ⚠️ indicates partial support with limitations, and ❌ indicates no support.
81
+
These benchmarks are provided to demonstrate theoretical performance benefits and should be used as a general reference rather than absolute performance indicators.
All tests were performed with local WebSocket server to minimize network variance. Each test was run 5 times and averaged.
57
102
58
-
Run the example app to test changes:
103
+
In the future, we would like to add benchmarks for CPU and memory usage, since that's where FastWS should shine. Your contributions are welcome!
59
104
60
-
```bash
61
-
// Start the demo server
62
-
bun server.ts
105
+
## Made with ❤️ at Callstack
63
106
64
-
// Run the app
65
-
cd example && npm run ios
66
-
```
107
+
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](https://callstack.com) is a group of React and React Native geeks, contact us at [[email protected]](mailto:[email protected]) if you need any help with these or just want to say hi!
67
108
68
-
You can also start the app from Xcode, in case you want to make changes to the native code. In that case, open `example/ios/NitroPlayground.xcworkspace` and hit run.
109
+
Like the project? ⚛️ [Join the team](https://callstack.com/careers/?utm_campaign=Senior_RN&utm_source=github&utm_medium=readme) who does amazing stuff for clients and drives React Native Open Source! 🔥
0 commit comments