React Query External Sync

A powerful debugging tool for React Query state and device storage 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.

If you need internal React Query dev tools within the device you can use my other package here!

https://github.com/LovesWorking/react-native-react-query-devtools

✨ Features

• 🔄 Real-time React Query state synchronization
• 💾 Device storage monitoring with CRUD operations - MMKV, AsyncStorage, and SecureStorage
• 📱 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

📦 Installation

# Using npm
npm install --save-dev react-query-external-sync socket.io-client

# Using yarn
yarn add -D react-query-external-sync socket.io-client

# Using pnpm
pnpm add -D react-query-external-sync socket.io-client

🚀 Quick Start

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

import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { useSyncQueriesExternal } from "react-query-external-sync";
import { Platform } from "react-native";
import AsyncStorage from "@react-native-async-storage/async-storage";
import * as SecureStore from "expo-secure-store";
import { storage } from "./mmkv"; // Your MMKV instance

// Create your query client
const queryClient = new QueryClient();

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <AppContent />
    </QueryClientProvider>
  );
}

function AppContent() {
  // Unified storage queries and external sync - all in one hook!
  useSyncQueriesExternal({
    queryClient,
    socketURL: "http://localhost:42831",
    deviceName: Platform.OS,
    platform: Platform.OS,
    deviceId: Platform.OS,
    extraDeviceInfo: {
      appVersion: "1.0.0",
    },
    enableLogs: true,
    envVariables: {
      NODE_ENV: process.env.NODE_ENV,
    },
    // Storage monitoring with CRUD operations
    mmkvStorage: storage, // MMKV storage for ['#storage', 'mmkv', 'key'] queries + monitoring
    asyncStorage: AsyncStorage, // AsyncStorage for ['#storage', 'async', 'key'] queries + monitoring
    secureStorage: SecureStore, // SecureStore for ['#storage', 'secure', 'key'] queries + monitoring
    secureStorageKeys: [
      "userToken",
      "refreshToken",
      "biometricKey",
      "deviceId",
    ], // SecureStore keys to monitor
  });

  // Your app content
  return <YourApp />;
}

🔒 Production Safety

This package is automatically disabled in production builds.

// The package handles this internally:
if (process.env.NODE_ENV !== "production") {
  useSyncQueries = require("./new-sync/useSyncQueries").useSyncQueries;
} else {
  // In production, this becomes a no-op function
  useSyncQueries = () => ({
    isConnected: false,
    connect: () => {},
    disconnect: () => {},
    socket: null,
    users: [],
  });
}

💡 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.

⚙️ 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)
envVariables	object	No	Environment variables to sync with DevTools
mmkvStorage	MmkvStorage	No	MMKV storage instance for real-time monitoring
asyncStorage	AsyncStorage	No	AsyncStorage instance for polling-based monitoring
secureStorage	SecureStore	No	SecureStore instance for secure data monitoring
secureStorageKeys	string[]	No	Array of SecureStore keys to monitor (required if using secureStorage)

🐛 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:

// Simple approach for single devices
deviceId: Platform.OS, // Works if you only have one device per platform

// Better approach for multiple simulators/devices of same type
// Using AsyncStorage, MMKV, or another storage solution
const [deviceId, setDeviceId] = useState(Platform.OS);

useEffect(() => {
  const loadOrCreateDeviceId = async () => {
    // Try to load existing ID
    const storedId = await AsyncStorage.getItem('deviceId');

    if (storedId) {
      setDeviceId(storedId);
    } else {
      // First launch - generate and store a persistent ID
      const newId = `${Platform.OS}-${Date.now()}`;
      await AsyncStorage.setItem('deviceId', newId);
      setDeviceId(newId);
    }
  };

  loadOrCreateDeviceId();
}, []);

📄 License

MIT

---

Made with ❤️ by LovesWorking