LovesWorking / react-query-external-sync

A tool that can be used by anyone to manage React Query state externally. Works with React, React Native with a familiar UI to the React Query Dev Tools.

React Query External Sync

React Query devtool synced with Socket.IO, to debug your react-query outstide your app easily.

Preview the devtool

Table of content

• Introduction
  • Key Advantages
• Prerequisites
  • Client Application
  • Socket IO Server
  • Devtool Website
• Installation
  • Client
    • 1. Install the package
    • 2. Connect your react-query to the socket
    • 3. Usages
  • Socket IO Server
    • 1. Install the package
    • 2. Setup Socket IO
  • React Query Dev Tools Server
• Ready to use Docker image
  • 1. Image link
  • 2. Environment variables
  • 3. Docker Compose example
• Contribution

Introduction

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.

Key Advantages:

• Real-time UI Updates: Instantly see how state changes affect your application's UI without backend alterations.
• Broad Accessibility: Enables all team members, including QA, designers, and business professionals, to tweak and test API-driven UI components on the fly.
• Continuous Evolution: Built with expansion in mind, expect regular feature updates driven by community feedback and the evolving needs of modern development workflows.
• 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.

Prerequisites

Client Application

• React version 18 or above.
• React Query version 5.17.19 or above.

Socket IO Server

• Socket.io version 4.7.4 or above.

Devtool Website

• Any react.js ready server (vite, rca, ...)

Installation

Client

1. Install the package

npm install react-query-external-sync

2. Connect your react-query to the socket

• Import the useAllQueries hook and utilize it within your client application to enable real-time synchronization with the external dashboard.

import { useAllQueries } from "react-query-external-sync";

const { connect, disconnect, isConnected, queries, socket, users } =
    useAllQueries({
      query: {
        username: "myUsername",
        userType: "User", // Role of the user
        clientType: "client", // client | server
      },
      queryClient,
      socketURL: "http://localhost:4000",
    });

• query: Contains user information for identifying and managing connections in the dashboard.
• queryClient: Your application's React Query client instance.
• socketURL: The URL where your Socket.io server is hosted.

3. Usages

• .connect(): initiate a connection with the socket server
• .disconnect(): terminate the connection to the socket server by invoking the disconnect function
• .isConnected: monitor the connection status

Socket IO Server

1. Install the package

npm install react-query-external-dash

2. Setup Socket IO

• After setting up your Socket.io server, integrate the socketHandle function to manage incoming and outgoing messages related to query state synchronization.
• Basic socket io Nodejs server example:

import { socketHandle } from "react-query-external-dash"

import("socket.io").then(4000 => {
    const io = new socketIO.Server(socketPort, {
        cors: {
            // This origin is the devtool (see next section), change the port to fit your needs.
            // You'll also need to add the URL of your client if you have any CORS issue
            origin: ["http://localhost:4001"],
            credentials: true,
        },
    })

    socketHandle({ io })

    io.on("connection", client => {
        console.log(`'${client.handshake.query.username}' connected`)
    })
})

React Query Dev Tools Server

• Incorporate the ExternalDevTools component within any React.JS ready server
• Basic react-vite server example (we suppose here that the port is 4001):

import React from "react"
import ReactDOM from "react-dom/client"
import { ExternalDevTools } from "react-query-external-dash"

ReactDOM.createRoot(document.getElementById("root")!).render(
    <React.StrictMode>
        <ExternalDevTools
            socketURL={"http://localhost:4000"}
            query={{
                clientType: "server",
                username: "Admin",
                userType: "admin",
            }}
        />
    </React.StrictMode>,
)

Ready to use Docker image

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.

1. Image link

https://hub.docker.com/repository/docker/navalex/rq_devtool

2. Environment variables

• SOCKET_PORT: Port for the Socket.io server
• DT_PORT: Port for the Vite server to access your devtool
• 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.

3. Docker Compose example

• You'll also need to open both ports to use this image. We suggest to define those in environment variables.

services:
    rqDevtools:
        image: navalex/rq_devtool:latest
        ports:
            - ${RQ_DEVTOOLS_PORT}:${RQ_DEVTOOLS_PORT}
            - ${RQ_DEVTOOLS_SOCKET_PORT}:${RQ_DEVTOOLS_SOCKET_PORT}
        environment:
            DT_PORT: ${RQ_DEVTOOLS_PORT}
            SOCKET_PORT: ${RQ_DEVTOOLS_SOCKET_PORT}
            SOCKET_CORS: "http://localhost:8102,http://localhost:5173"

Contribution

I welcome contributions, feedback, and bug reports. Feel free to open an issue or pull request on this GitHub repository.

---

🌴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/