Skip to content

Commit b6300df

Browse files
navalexnavalex
committed
Update Readme with TOC, Docker image and easier install guide
1 parent 003c7f6 commit b6300df

File tree

1 file changed

+110
-55
lines changed

1 file changed

+110
-55
lines changed

‎README.md‎

Lines changed: 110 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,29 @@
33

44
![react-query-external-preview](https://github.com/LovesWorking/LovesWorking/assets/111514077/e8c119cc-44bc-48ba-a398-dfba30e44396)
55

6+
## Table of content
7+
8+
- [Introduction](#introduction)
9+
- [Key Advantages](#key-advantages)
10+
- [Prerequisites](#prerequisites)
11+
- [Client Application](#client-application)
12+
- [Socket IO Server](#socket-io-server)
13+
- [Devtool Website](#devtool-website)
14+
- [Installation](#installation)
15+
+ [Client](#client)
16+
- [1. Install the package](#1-install-the-package)
17+
- [2. Connect your react-query to the socket](#2-connect-your-react-query-to-the-socket)
18+
- [3. Usages](#3-usages)
19+
+ [Socket IO Server](#socket-io-server)
20+
- [1. Install the package](#1-install-the-package-1)
21+
- [2. Setup Socket IO](#2-setup-socket-io)
22+
+ [React Query Dev Tools Server](#react-query-dev-tools-server)
23+
- [Ready to use Docker image](#ready-to-use-docker-image)
24+
- [1. Image link](#1-image-link)
25+
- [2. Environment variables](#2-environment-variables)
26+
- [3. Docker Compose example](#3-docker-compose-example)
27+
- [Contribution](#contribution)
28+
629
## Introduction
730

831
**React Query External Sync** is a dynamic tool for managing React Query state outside the usual confines of React Query Dev Tools. Ideal for React projects, it offers a live state management solution that's accessible to both developers, qa and non-technical team members.
@@ -13,26 +36,35 @@
1336
- **Continuous Evolution**: Built with expansion in mind, expect regular feature updates driven by community feedback and the evolving needs of modern development workflows.
1437
- **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.
1538

16-
## Getting Started
39+
<hr>
40+
41+
## Prerequisites
1742

18-
### Prerequisites
43+
### Client Application
1944

20-
#### Client Application:
2145
- React version 18 or above.
2246
- React Query version 5.17.19 or above.
2347

24-
#### Socket IO Server:
48+
### Socket IO Server
49+
2550
- Socket.io version 4.7.4 or above.
2651

27-
### Installation
52+
### Devtool Website
53+
54+
- Any react.js ready server (vite, rca, ...)
55+
56+
## Installation
2857

29-
Install the package using npm by running the following command in your client project directory:
58+
### Client
59+
60+
#### 1. Install the package
3061

3162
```bash
3263
npm install react-query-external-sync
3364
```
3465

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

3870
```javascript
@@ -49,81 +81,104 @@ const { connect, disconnect, isConnected, queries, socket, users } =
4981
socketURL: "http://localhost:4000",
5082
});
5183
```
84+
5285
- **query**: Contains user information for identifying and managing connections in the dashboard.
5386
- **queryClient**: Your application's React Query client instance.
5487
- **socketURL**: The URL where your Socket.io server is hosted.
5588

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
89+
#### 3. Usages
6190

62-
Terminate the connection to the socket server by invoking the disconnect function.
63-
64-
### Accessing Queries
65-
66-
The queries property grants access to the synchronized query data, facilitating debugging and state management.
91+
- `.connect()`: initiate a connection with the socket server
92+
- `.disconnect()`: terminate the connection to the socket server by invoking the disconnect function
93+
- `.isConnected`: monitor the connection status
6794

6895
### Socket IO Server
6996

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

7299
```bash
73100
npm install react-query-external-dash
74101
```
75102

76-
## Socket IO Setup:
103+
#### 2. Setup Socket IO
77104

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

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

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

89134
```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}`));
135+
import React from "react"
136+
import ReactDOM from "react-dom/client"
137+
import { ExternalDevTools } from "react-query-external-dash"
138+
139+
ReactDOM.createRoot(document.getElementById("root")!).render(
140+
<React.StrictMode>
141+
<ExternalDevTools
142+
socketURL={"http://localhost:4000"}
143+
query={{
144+
clientType: "server",
145+
username: "Admin",
146+
userType: "admin",
147+
}}
148+
/>
149+
</React.StrictMode>,
150+
)
151+
```
107152

153+
## Ready to use Docker image
108154

109-
```
155+
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.
110156

111-
## React Query Dev Tools Integration:
157+
### 1. Image link
112158

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

115-
```javascript
116-
import { ExternalDevTools } from "react-query-external-dash";
161+
### 2. Environment variables
162+
163+
- `SOCKET_PORT`: Port for the Socket.io server
164+
- `DT_PORT`: Port for the Vite server to access your devtool
165+
- `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.**
166+
167+
### 3. Docker Compose example
117168

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-
/>
169+
- You'll also need to open both ports to use this image. We suggest to define those in environment variables.
126170

171+
```yaml
172+
services:
173+
rqDevtools:
174+
image: navalex/rq_devtool:latest
175+
ports:
176+
- ${RQ_DEVTOOLS_PORT}:${RQ_DEVTOOLS_PORT}
177+
- ${RQ_DEVTOOLS_SOCKET_PORT}:${RQ_DEVTOOLS_SOCKET_PORT}
178+
environment:
179+
DT_PORT: ${RQ_DEVTOOLS_PORT}
180+
SOCKET_PORT: ${RQ_DEVTOOLS_SOCKET_PORT}
181+
SOCKET_CORS: "http://localhost:8102,http://localhost:5173"
127182
```
128183
129184
## Contribution

0 commit comments

Comments
 (0)