Skip to content

Commit 149aa3a

Browse files
LovesWorkingLovesWorking
authored
Merge pull request #6 from navalex/readmeUpdate
README.md update
2 parents 003c7f6 + 3a9676c commit 149aa3a

File tree

1 file changed

+117
-57
lines changed

1 file changed

+117
-57
lines changed

‎README.md

Lines changed: 117 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,31 @@
11
# React Query External Sync
2-
🌴Looking for a web/mobile developer? I'm actively seeking my next opportunity. Feel free to message me on LinkedIn! https://www.linkedin.com/in/lovesworking/
32

4-
![react-query-external-preview](https://github.com/LovesWorking/LovesWorking/assets/111514077/e8c119cc-44bc-48ba-a398-dfba30e44396)
3+
React Query devtool synced with Socket.IO, to debug your react-query outstide your React.js app easily.
4+
5+
## [Preview the devtool](https://github.com/LovesWorking/LovesWorking/assets/111514077/e8c119cc-44bc-48ba-a398-dfba30e44396)
6+
7+
## Table of content
8+
9+
- [Introduction](#introduction)
10+
- [Key Advantages](#key-advantages)
11+
- [Prerequisites](#prerequisites)
12+
- [Client Application](#client-application)
13+
- [Socket IO Server](#socket-io-server)
14+
- [Devtool Website](#devtool-website)
15+
- [Installation](#installation)
16+
+ [Client](#client)
17+
- [1. Install the package](#1-install-the-package)
18+
- [2. Connect your react-query to the socket](#2-connect-your-react-query-to-the-socket)
19+
- [3. Usages](#3-usages)
20+
+ [Socket IO Server](#socket-io-server)
21+
- [1. Install the package](#1-install-the-package-1)
22+
- [2. Setup Socket IO](#2-setup-socket-io)
23+
+ [React Query Dev Tools Server](#react-query-dev-tools-server)
24+
- [Ready to use Docker image](#ready-to-use-docker-image)
25+
- [1. Image link](#1-image-link)
26+
- [2. Environment variables](#2-environment-variables)
27+
- [3. Docker Compose example](#3-docker-compose-example)
28+
- [Contribution](#contribution)
529

630
## Introduction
731

@@ -13,26 +37,33 @@
1337
- **Continuous Evolution**: Built with expansion in mind, expect regular feature updates driven by community feedback and the evolving needs of modern development workflows.
1438
- **Enhanced Manipulation**: Future updates will introduce capabilities for precise state adjustments, such as directly inserting complete objects or arrays, object duplication, simultaneous state syncing across web, Android, and iOS and persistent state overrides, allowing values for specific data to remain until manually reverted.
1539

16-
## Getting Started
40+
## Prerequisites
1741

18-
### Prerequisites
42+
### Client Application
1943

20-
#### Client Application:
2144
- React version 18 or above.
2245
- React Query version 5.17.19 or above.
2346

24-
#### Socket IO Server:
47+
### Socket IO Server
48+
2549
- Socket.io version 4.7.4 or above.
2650

27-
### Installation
51+
### Devtool Website
52+
53+
- Any react.js ready server (vite, rca, ...)
2854

29-
Install the package using npm by running the following command in your client project directory:
55+
## Installation
56+
57+
### Client
58+
59+
#### 1. Install the package
3060

3161
```bash
3262
npm install react-query-external-sync
3363
```
3464

35-
## Usage
65+
#### 2. Connect your react-query to the socket
66+
3667
- Import the useAllQueries hook and utilize it within your client application to enable real-time synchronization with the external dashboard.
3768

3869
```javascript
@@ -49,83 +80,112 @@ const { connect, disconnect, isConnected, queries, socket, users } =
4980
socketURL: "http://localhost:4000",
5081
});
5182
```
83+
5284
- **query**: Contains user information for identifying and managing connections in the dashboard.
5385
- **queryClient**: Your application's React Query client instance.
5486
- **socketURL**: The URL where your Socket.io server is hosted.
5587

56-
### Connecting to the Server
57-
58-
Utilize the connect function to initiate a connection with the socket server. Monitor the connection status using isConnected.
59-
60-
### Disconnecting from the Server
61-
62-
Terminate the connection to the socket server by invoking the disconnect function.
63-
64-
### Accessing Queries
88+
#### 3. Usages
6589

66-
The queries property grants access to the synchronized query data, facilitating debugging and state management.
90+
- `.connect()`: initiate a connection with the socket server
91+
- `.disconnect()`: terminate the connection to the socket server by invoking the disconnect function
92+
- `.isConnected`: monitor the connection status
6793

6894
### Socket IO Server
6995

70-
Run the following command in your Node server directory:
96+
#### 1. Install the package
7197

7298
```bash
7399
npm install react-query-external-dash
74100
```
75101

76-
## Socket IO Setup:
102+
#### 2. Setup Socket IO
77103

78-
- After setting up your Socket.io server, integrate the socketHandle function to manage incoming and outgoing messages related to query state synchronization.
104+
- After setting up your Socket.io server, integrate the socketHandle function to manage incoming and outgoing messages related to query state synchronization.
105+
- **Basic socket io Nodejs server example**:
79106

80107
```javascript
81-
import { socketHandle } from "react-query-external-dash";
82-
83-
socketHandle({ io });
108+
import { socketHandle } from "react-query-external-dash"
109+
110+
import("socket.io").then(4000 => {
111+
const io = new socketIO.Server(socketPort, {
112+
cors: {
113+
// This origin is the devtool (see next section), change the port to fit your needs.
114+
// You'll also need to add the URL of your client if you have any CORS issue
115+
origin: ["http://localhost:4001"],
116+
credentials: true,
117+
},
118+
})
119+
120+
socketHandle({ io })
121+
122+
io.on("connection", client => {
123+
console.log(`'${client.handshake.query.username}' connected`)
124+
})
125+
})
84126
```
85127

86-
- **io**: The Socket.IO server instance.
87-
- **Basic socket io Nodejs server example**:
128+
### React Query Dev Tools Server
129+
130+
- Incorporate the ExternalDevTools component within any React.JS ready server
131+
- **Basic react-vite server example** _(we suppose here that the port is 4001)_:
88132

89133
```javascript
90-
const { socketHandle } = require("react-query-external-dash");
91-
const express = require("express");
92-
const http = require("http");
93-
const { Server } = require("socket.io");
94-
const app = express();
95-
const server = http.createServer(app);
96-
// Configure CORS policy for Socket.IO
97-
const io = new Server(server, {
98-
cors: {
99-
origin: "*", // Accept connections from any origin
100-
methods: ["GET", "POST"],
101-
},
102-
});
103-
socketHandle({ io });
104-
app.use(express.static("build"));
105-
const port = process.env.PORT || 4000;
106-
server.listen(port, () => console.log(`Server running on port ${port}`));
134+
import React from "react"
135+
import ReactDOM from "react-dom/client"
136+
import { ExternalDevTools } from "react-query-external-dash"
137+
138+
ReactDOM.createRoot(document.getElementById("root")!).render(
139+
<React.StrictMode>
140+
<ExternalDevTools
141+
socketURL={"http://localhost:4000"}
142+
query={{
143+
clientType: "server",
144+
username: "Admin",
145+
userType: "admin",
146+
}}
147+
/>
148+
</React.StrictMode>,
149+
)
150+
```
107151

152+
## Ready to use Docker image
108153

109-
```
154+
If you don't want to setup both Socket.IO + Dedicated React.js server to monitor your app, a Docker image is available to launch those both services at once, with custom ports and CORS urls.
110155

111-
## React Query Dev Tools Integration:
156+
### 1. Image link
112157

113-
- Incorporate the ExternalDevTools component within your server-side dashboard to display and interact with the synchronized React Query states.
158+
https://hub.docker.com/repository/docker/navalex/rq_devtool
114159

115-
```javascript
116-
import { ExternalDevTools } from "react-query-external-dash";
160+
### 2. Environment variables
161+
162+
- `SOCKET_PORT`: Port for the Socket.io server
163+
- `DT_PORT`: Port for the Vite server to access your devtool
164+
- `CORS_ORIGINS`: String to specify authorized url's for CORS in form of: "url1,url2,url3,..." (separate with coma without spaces). **Note that the devtool url is automaticly included in the CORS Policy.**
165+
166+
### 3. Docker Compose example
117167

118-
<ExternalDevTools
119-
query={{
120-
clientType: "server",
121-
username: "Admin",
122-
userType: "admin",
123-
}}
124-
socketURL="http://localhost:4000"// Use local ip if testing localy for Android ie http://192.168.4.21:4000
125-
/>
168+
- You'll also need to open both ports to use this image. We suggest to define those in environment variables.
126169

170+
```yaml
171+
services:
172+
rqDevtools:
173+
image: navalex/rq_devtool:latest
174+
ports:
175+
- ${RQ_DEVTOOLS_PORT}:${RQ_DEVTOOLS_PORT}
176+
- ${RQ_DEVTOOLS_SOCKET_PORT}:${RQ_DEVTOOLS_SOCKET_PORT}
177+
environment:
178+
DT_PORT: ${RQ_DEVTOOLS_PORT}
179+
SOCKET_PORT: ${RQ_DEVTOOLS_SOCKET_PORT}
180+
SOCKET_CORS: "http://localhost:8102,http://localhost:5173"
127181
```
128182
129183
## Contribution
130184
131185
I welcome contributions, feedback, and bug reports. Feel free to open an issue or pull request on this GitHub repository.
186+
187+
<br>
188+
<hr>
189+
<br>
190+
191+
🌴Looking for a web/mobile developer? I'm actively seeking my next opportunity. Feel free to message me on LinkedIn! https://www.linkedin.com/in/lovesworking/

0 commit comments

Comments
 (0)