React Query External Sync

A powerful debugging tool for React Query state in any React-based application. Whether you're building for mobile, web, desktop, TV, or VR - this package has you covered. It works seamlessly across all platforms where React runs, with zero configuration to disable in production.

Pairs perfectly with React Native DevTools for a complete development experience.

✨ Features

• 🔄 Real-time React Query state synchronization
• 📱 Works with any React-based framework (React, React Native, Expo, Next.js, etc.)
• 🖥️ Platform-agnostic: Web, iOS, Android, macOS, Windows, Linux, tvOS, VR - you name it!
• 🔌 Socket.IO integration for reliable communication
• 📊 Query status, data, and error monitoring
• ⚡️ Simple integration with minimal setup
• 🧩 Perfect companion to React Native DevTools
• 🛑 Zero-config production safety - automatically disabled in production builds
• 🚀 NEW: Remote Expo DevTools - Trigger Expo DevTools commands remotely without using the command line
• 🔧 Auto-implemented Expo commands - Default implementations for all Expo DevTools commands with no user setup required

📦 Installation

1# Using npm
2npm install --save-dev react-native-devtools-sync socket.io-client
3
4# Using yarn
5yarn add -D react-native-devtools-sync socket.io-client
6
7# Using pnpm
8pnpm add -D react-native-devtools-sync socket.io-client

🚀 Quick Start

Add the hook to your application where you set up your React Query context:

1import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
2import { useSyncQueriesExternal } from "react-query-external-sync";
3// Import Platform for React Native or use other platform detection for web/desktop
4import { Platform } from "react-native";
5
6// Create your query client
7const queryClient = new QueryClient();
8
9function App() {
10  return (
11    <QueryClientProvider client={queryClient}>
12      <AppContent />
13    </QueryClientProvider>
14  );
15}
16
17function AppContent() {
18  // Set up the sync hook - automatically disabled in production!
19  useSyncQueriesExternal({
20    queryClient,
21    socketURL: "http://localhost:42831", // Default port for React Native DevTools
22    deviceName: Platform?.OS || "web", // Platform detection
23    platform: Platform?.OS || "web", // Use appropriate platform identifier
24    deviceId: Platform?.OS || "web", // Use a PERSISTENT identifier (see note below)
25    extraDeviceInfo: {
26      // Optional additional info about your device
27      appVersion: "1.0.0",
28      // Add any relevant platform info
29    },
30    enableLogs: false,
31    // Enable AsyncStorage monitoring (optional)
32    asyncStorage: AsyncStorage,
33    // Enable network monitoring (optional)
34    networkMonitoring: {
35      fetch: true,
36      xhr: true,
37      websocket: false
38    },
39    // Enable Expo DevTools (optional)
40    expoDevTools: {
41      enabled: true
42    }
43  });
44
45  // Your app content
46  return <YourApp />;
47}

🔒 Production Safety

This package is automatically disabled in production builds.

1// The package handles this internally:
2if (process.env.NODE_ENV !== "production") {
3  useSyncQueries = require("./new-sync/useSyncQueries").useSyncQueries;
4} else {
5  // In production, this becomes a no-op function
6  useSyncQueries = () => ({
7    isConnected: false,
8    connect: () => {},
9    disconnect: () => {},
10    socket: null,
11    users: [],
12  });
13}

💡 Usage with DevTools

For the best experience, use this package with the React Native DevTools application:

1. Download and launch the DevTools application
2. Integrate this package in your React application
3. Start your application
4. DevTools will automatically detect and connect to your running application

Note: For optimal connection, launch DevTools before starting your application.

🚀 Remote Expo DevTools

This package now includes Remote Expo DevTools, allowing you to trigger Expo DevTools commands remotely without using the command line.

Setting up Expo DevTools

1. Enable Expo DevTools in your app:

1useSyncQueriesExternal({
2  // ... other options
3  expoDevTools: {
4    enabled: true
5  }
6});

2. Command handlers are now automatically implemented:

1import { useSyncQueriesExternal } from "react-query-external-sync";
2
3// Simply enable Expo DevTools - no implementation needed!
4useSyncQueriesExternal({
5  // ... other options
6  expoDevTools: {
7    enabled: true
8  }
9});

The library now includes default implementations for all Expo commands that will automatically detect and use the appropriate APIs based on your environment. These implementations will:

• Try to use Expo's APIs first if available
• Fall back to React Native's DevSettings and NativeModules if needed
• Provide helpful console messages if no implementation is found

If you need custom behavior, you can still override any command:

1import { 
2  setExpoCommandImplementations,
3  useSyncQueriesExternal 
4} from "react-query-external-sync";
5
6// Override only the commands you need custom behavior for
7setExpoCommandImplementations({
8  reload: async () => {
9    console.log("Custom reload implementation");
10    // Your custom implementation
11    await YourCustomReloadFunction();
12  },
13  // You can override just one or a few commands
14  // Other commands will use the default implementations
15});

3. Use the DevTools UI to trigger commands remotely:
   • Connect to your device
   • Click the Expo DevTools button in the dashboard
   • Select a command to execute remotely

Available Commands

• reload: Reload the app
• toggle-inspector: Toggle the element inspector
• toggle-performance-monitor: Toggle the performance monitor
• toggle-element-inspector: Toggle the element inspector
• clear-cache: Clear the app cache
• toggle-remote-debugging: Toggle remote debugging
• open-dev-menu: Open the developer menu
• take-screenshot: Take a screenshot
• shake-device: Simulate device shake

⚙️ Configuration Options

The useSyncQueriesExternal hook accepts the following options:

Option	Type	Required	Description
queryClient	QueryClient	Yes	Your React Query client instance
socketURL	string	Yes	URL of the socket server (e.g., 'http://localhost:42831')
deviceName	string	Yes	Human-readable name for your device
platform	string	Yes	Platform identifier ('ios', 'android', 'web', 'macos', 'windows', etc.)
deviceId	string	Yes	Unique identifier for your device
extraDeviceInfo	object	No	Additional device metadata to display in DevTools
enableLogs	boolean	No	Enable console logging for debugging (default: false)
asyncStorage	AsyncStorage	No	AsyncStorage implementation for monitoring
networkMonitoring	NetworkMonitoringOptions	No	Configure network request monitoring
expoDevTools	ExpoDevToolsOptions	No	Configure Expo DevTools integration

🐛 Troubleshooting

Quick Checklist

1. DevTools Connection

   • Look for "Connected" status in the top-left corner of the DevTools app
   • If it shows "Disconnected", restart the DevTools app

2. No Devices Appearing

   • Verify the Socket.IO client is installed (npm list socket.io-client)
   • Ensure the hook is properly set up in your app
   • Check that socketURL matches the DevTools port (default: 42831)
   • Restart both your app and the DevTools

3. Data Not Syncing

   • Confirm you're passing the correct queryClient instance
   • Set enableLogs: true to see connection information

That's it! If you're still having issues, visit the GitHub repository for support.

⚠️ Important Note About Device IDs

The deviceId parameter must be persistent across app restarts and re-renders. Using a value that changes (like Date.now()) will cause each render to be treated as a new device.

Recommended approaches:

1// Simple approach for single devices
2deviceId: Platform.OS, // Works if you only have one device per platform
3
4// Better approach for multiple simulators/devices of same type
5// Using AsyncStorage, MMKV, or another storage solution
6const [deviceId, setDeviceId] = useState(Platform.OS);
7
8useEffect(() => {
9  const loadOrCreateDeviceId = async () => {
10    // Try to load existing ID
11    const storedId = await AsyncStorage.getItem('deviceId');
12
13    if (storedId) {
14      setDeviceId(storedId);
15    } else {
16      // First launch - generate and store a persistent ID
17      const newId = `${Platform.OS}-${Date.now()}`;
18      await AsyncStorage.setItem('deviceId', newId);
19      setDeviceId(newId);
20    }
21  };
22
23  loadOrCreateDeviceId();
24}, []);

🙏 Acknowledgements

This project is a fork with added features. A huge thank you to LovesWorking for creating the original React Query External Sync package, which provided an excellent foundation for this enhanced version. Your work has been instrumental in making React Query debugging easier and more powerful.

📄 License

MIT

---

Original package by LovesWorking
Enhanced with Remote Expo DevTools functionality