Add new dev tools sync hook

Author: LovesWorking

README.md

@@ -1,123 +1,181 @@
 # React Query External Sync
 
-A tool for syncing React Query state to an external React Query Dev Tools instance.
+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.
 
-## Features
+Pairs perfectly with [React Native DevTools](https://github.com/LovesWorking/rn-better-dev-tools) for a complete development experience.
 
-- Works in both React Native and browser/web environments
-- Syncs React Query state between your app and external dev tools
-- Automatically detects platform (iOS, Android, Web, etc.)
-- Handles platform-specific networking (like Android emulator's 10.0.2.2 for localhost)
-- Uses appropriate storage mechanisms based on environment
+![React Query External Sync Demo](https://github.com/user-attachments/assets/39e5c417-be4d-46af-8138-3589d73fce9f)
 
-## Installation
+## ✨ Features
 
-```bash
-npm install react-query-external-sync
-# or
-yarn add react-query-external-sync
-```
-
-### React Native Requirements
+- 🔄 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
 
-If you're using this in a React Native project, you'll need to install the following optional dependencies:
+## 📦 Installation
 
 ```bash
-npm install react-native @react-native-async-storage/async-storage
-# or
-yarn add react-native @react-native-async-storage/async-storage
+# 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
 ```
 
-## Usage
+## 🚀 Quick Start
+
+Add the hook to your application where you set up your React Query context:
 
 ```jsx
-import { useQuerySyncSocket } from 'react-query-external-sync';
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { useSyncQueriesExternal } from "react-query-external-sync";
+// Import Platform for React Native or use other platform detection for web/desktop
+import { Platform } from "react-native";
 
-function App() {
-  // Set up the sync socket
-  useQuerySyncSocket({
-    deviceName: 'MyApp', // Name to identify this device
-    socketURL: 'http://localhost:42831', // URL to your dev tools instance
-  });
+// Create your query client
+const queryClient = new QueryClient();
 
+function App() {
   return (
-    // Your app components
+    <QueryClientProvider client={queryClient}>
+      <AppContent />
+    </QueryClientProvider>
   );
 }
+
+function AppContent() {
+  // Set up the sync hook - automatically disabled in production!
+  useSyncQueriesExternal({
+    queryClient,
+    socketURL: "http://localhost:42831", // Default port for React Native DevTools
+    deviceName: Platform?.OS || "web", // Platform detection
+    platform: Platform?.OS || "web", // Use appropriate platform identifier
+    deviceId: Platform?.OS || "web", // Use a PERSISTENT identifier (see note below)
+    extraDeviceInfo: {
+      // Optional additional info about your device
+      appVersion: "1.0.0",
+      // Add any relevant platform info
+    },
+    enableLogs: false,
+  });
+
+  // Your app content
+  return <YourApp />;
+}
+```
+
+## 🔒 Production Safety
+
+This package is automatically disabled in production builds.
+
+```jsx
+// 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: [],
+  });
+}
 ```
 
-## How It Works
+## 💡 Usage with DevTools
 
-This package provides a cross-platform solution for syncing React Query state to external tools:
+For the best experience, use this package with the [React Native DevTools](https://github.com/LovesWorking/rn-better-dev-tools) application:
 
-1. **Platform Detection**: Automatically detects if running in React Native or web environment
-2. **Storage Abstraction**: Uses the appropriate storage mechanism:
-   - React Native: AsyncStorage (if available)
-   - Web: localStorage
-   - Fallback: In-memory storage
-3. **Network Configuration**: Handles platform-specific networking requirements
-   - For Android emulators: Maps localhost to 10.0.2.2
-   - For other environments: Uses the provided URL
+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
 
-## Advanced Configuration
+> **Note**: For optimal connection, launch DevTools before starting your application.
 
-### Custom Platform Detection
+## ⚙️ Configuration Options
 
-If you need to override the built-in platform detection:
+The `useSyncQueriesExternal` hook accepts the following options:
 
-```jsx
-import {
-  useQuerySyncSocket,
-  setPlatformOverride,
-} from "react-query-external-sync";
+| 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)                   |
 
-// Set a custom platform
-setPlatformOverride({ os: "customOS", name: "Custom Platform" });
+## 🐛 Troubleshooting
 
-// Use normally after setting override
-function App() {
-  useQuerySyncSocket({
-    deviceName: "MyCustomPlatformApp",
-    socketURL: "http://localhost:3000",
-  });
+### 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
 
-### Custom Storage
+2. **No Devices Appearing**
 
-If you need to provide a custom storage implementation:
+   - 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](https://github.com/LovesWorking/react-query-external-sync/issues) 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:**
 
 ```jsx
-import {
-  useQuerySyncSocket,
-  setCustomStorage,
-} from "react-query-external-sync";
-
-// Set a custom storage implementation
-setCustomStorage({
-  getItem: async (key) => {
-    /* your implementation */
-  },
-  setItem: async (key, value) => {
-    /* your implementation */
-  },
-  removeItem: async (key) => {
-    /* your implementation */
-  },
-});
-
-// Use normally after setting custom storage
-function App() {
-  // ...
-}
+// 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
+## 📄 License
 
 MIT
 
-<br>
-<hr>
-<br>
+---
+
+Made with ❤️ by [LovesWorking](https://github.com/LovesWorking)

src/new-sync/index.ts

@@ -0,0 +1,2 @@
+// Export the main hook
+export { useMySocket as useQuerySyncSocket } from "./useMySocket";