{"id":47880331,"url":"https://github.com/getditto/react-native-ditto-tools","last_synced_at":"2026-04-04T01:44:32.843Z","repository":{"id":308543092,"uuid":"1031863282","full_name":"getditto/react-native-ditto-tools","owner":"getditto","description":"Diagnostic and Debugging Tools for Ditto for React Native SDK","archived":false,"fork":false,"pushed_at":"2026-03-02T20:43:36.000Z","size":2872,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-04-04T01:44:29.825Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/getditto.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-04T12:51:43.000Z","updated_at":"2026-03-02T20:43:39.000Z","dependencies_parsed_at":"2025-08-06T14:42:04.738Z","dependency_job_id":"20033c2e-9e73-4cea-ad29-cccd2bbf3d14","html_url":"https://github.com/getditto/react-native-ditto-tools","commit_stats":null,"previous_names":["getditto/react-native-ditto-tools"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/getditto/react-native-ditto-tools","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getditto%2Freact-native-ditto-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getditto%2Freact-native-ditto-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getditto%2Freact-native-ditto-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getditto%2Freact-native-ditto-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/getditto","download_url":"https://codeload.github.com/getditto/react-native-ditto-tools/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getditto%2Freact-native-ditto-tools/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31384845,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T01:22:39.193Z","status":"ssl_error","status_checked_at":"2026-04-04T01:22:33.970Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-04T01:44:32.189Z","updated_at":"2026-04-04T01:44:32.834Z","avatar_url":"https://github.com/getditto.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @dittolive/ditto-react-native-tools\n\n## Diagonistic and Debugging Tools for Ditto in React Native \n\n\u003e **⚠️ Platform Compatibility Notice**  \n\u003e These tools currently do not support the **React Native MacOS platform**. They are designed for mobile (iOS, Android) platforms where Ditto's peer-to-peer functionality and file system access are available.\n\n### Required Dependencies\n\nThis library requires the following peer dependencies to be installed in your app:\n\n- `@dittolive/ditto` - Core Ditto SDK (\u003e=4.11.6 - Tested on 4.11.6 and 4.12.2)\n- `@dr.pogodin/react-native-fs` - File system operations for log export and data directory cleanup\n- `react-native-zip-archive` - Directory compression for data export functionality\n\n\u003e [!warning] \n\u003e Some tools require iOS version 15.5 or higher. You may need to update your iOS target version.  \n\n\u003e [!NOTE] \n\u003e The required version of `@dr.pogodin/react-native-fs` depends on your React Native version. Please refer to the [@dr.pogodin/react-native-fs releases](https://github.com/birdofpreyru/react-native-fs/releases) to select the correct version for your project.\n\n## Installation\n\n```sh\nnpm install @dittolive/ditto-react-native-tools @dittolive/ditto @dr.pogodin/react-native-fs react-native-zip-archive\n```\n\nor\n\n```sh\nyarn add @dittolive/ditto-react-native-tools @dittolive/ditto @dr.pogodin/react-native-fs react-native-zip-archive\n```\n\n### iOS Setup\n\nAfter installing dependencies, run:\n\n```sh\ncd ios \u0026\u0026 pod install \u0026\u0026 cd ..\n```\n\n### Android Setup\n\nFor React Native 0.77.1+, auto-linking should handle Android setup automatically. If you encounter linking issues, clean your build:\n\n```sh\ncd android \u0026\u0026 ./gradlew clean \u0026\u0026 cd ..\n```\n\n## Platform Setup\n\nAfter installing this library, you need to configure your React Native app for Ditto.\n\n**Please follow the official Ditto React Native quickstart guide:**\n[React Native Setup](https://docs.ditto.live/sdk/latest/quickstarts/react-native)\n\n## Usage\n\n```typescript\nimport React from 'react';\nimport { PeersList, DiskUsage, SystemSettings, QueryEditor } from '@dittolive/ditto-react-native-tools';\nimport { Ditto } from '@dittolive/ditto';\n\n// Initialize your Ditto instance\nconst ditto = new Ditto({\n  type: 'offlinePlayground',\n  appID: 'your-app-id',\n  offlineToken: 'your-offline-token',\n});\n\nfunction App() {\n  return (\n    \u003c\u003e\n      \u003cPeersList \n        ditto={ditto}\n      /\u003e\n    \u003c/\u003e\n  );\n}\n```\n\n\u003e [!NOTE] \n\u003e Ditto instance should always be kept in a [provider](https://react.dev/reference/react/createContext#provider). \n\n## Components\n\n### PeersList\n\nDisplay and monitor Ditto peer connections in real-time.\n\n```typescript\nimport { PeersList } from '@dittolive/ditto-react-native-tools';\n\n\u003cPeersList \n  ditto={ditto}\n  showConnectionDetails={true}\n  style={{ flex: 1 }}\n/\u003e\n```\n\n**Props:**\n- `ditto` (required): Your Ditto instance\n- `showConnectionDetails?: boolean` - Whether to show detailed connection information (default: true)\n- `style?: ViewStyle` - Custom styling for the main container\n- `headerComponent?: () =\u003e React.ReactElement` - Optional header component\n\n**Style Customization:**\nThe component's styling is controlled through built-in StyleSheet with the following key areas that can be customized via the `style` prop:\n- **Main container**: Background color, flex properties, padding\n- **List content**: Bottom padding and scroll behavior\n- **Peer items**: Card-style containers with shadows and rounded corners\n- **Loading/Error states**: Centered content with appropriate typography\n\n```typescript\n// Example custom styling\n\u003cPeersList \n  ditto={ditto}\n  style={{ \n    flex: 1, \n    backgroundColor: '#1a1a1a',  // Dark theme background\n    paddingHorizontal: 8         // Reduce horizontal margins\n  }}\n/\u003e\n```\n\n### DiskUsage\n\nMonitor and display Ditto's disk usage breakdown with export functionality.\n\n```typescript\nimport { DiskUsage } from '@dittolive/ditto-react-native-tools';\n\n\u003cDiskUsage \n  ditto={ditto}\n  style={{ flex: 1 }}\n/\u003e\n```\n\n**Props:**\n- `ditto` (required): Your Ditto instance\n- `style?: ViewStyle` - Custom styling for the main container\n\n**Features:**\n- **Automatic Log Export**: The \"Export Logs\" button uses Ditto's built-in `Logger.exportToFile()` method to save log files\n- **Disk Usage Display**: Shows real-time disk usage breakdown for different Ditto components (store, replication, attachments, auth)\n- **Last Updated Time**: Footer displays when the data was last refreshed\n\n**Style Customization:**\nThe component's styling is controlled through built-in StyleSheet with the following key areas that can be customized via the `style` prop:\n- **Main container**: Background color, flex properties, padding\n- **Content layout**: Card-style containers with proper spacing\n- **Usage displays**: Progress bars, labels, and value formatting\n- **Action buttons**: Export button styling and disabled states\n- **Footer information**: Last updated timestamp styling\n\n```typescript\n// Example custom styling\n\u003cDiskUsage \n  ditto={ditto}\n  style={{ \n    flex: 1, \n    backgroundColor: '#f8f9fa',  // Light gray background\n    padding: 16                   // Add container padding\n  }}\n/\u003e\n```\n\n### SystemSettings\n\nDisplay all Ditto system settings using the `SHOW ALL` DQL statement. Self-contained component with built-in refresh functionality.\n\n```typescript\nimport { SystemSettings } from '@dittolive/ditto-react-native-tools';\n\n\u003cSystemSettings \n  ditto={ditto}\n  style={{ flex: 1, backgroundColor: '#f5f5f5' }}\n/\u003e\n```\n\n**Props:**\n- `ditto` (required): Your Ditto instance\n- `style?: ViewStyle` - Custom styling for the main container\n\n**Features:**\n- **Self-contained**: No callbacks required - handles all interactions internally\n- **System Settings Display**: Shows all Ditto system settings from SHOW ALL DQL query\n- **Real-time Search**: Built-in search functionality with instant filtering\n- **Search Capabilities**: Case-insensitive search across both setting keys and values\n- **Smart Count Display**: Shows filtered results count (e.g., \"5 of 141 settings\")\n- **Refresh Functionality**: Built-in refresh button to reload settings\n- **Performance Optimized**: Uses FlatList virtualization and in-memory filtering for 200+ settings\n- **Loading States**: Automatic loading, error, and empty state handling\n- **Visual Design**: Clean search interface with bordered input and proper typography\n\n**Style Customization:**\nThe component's styling is controlled through built-in StyleSheet with the following key areas that can be customized via the `style` prop:\n- **Main container**: Background color, flex properties, padding\n- **Header section**: Settings count and refresh button layout\n- **Settings list**: Individual setting items with key-value pairs\n- **Loading/Error states**: Centered content with appropriate messaging\n- **Footer information**: Last updated timestamp styling\n\n**Search Functionality:**\nThe component includes a built-in search feature that:\n- Filters settings in real-time as you type\n- Searches both setting keys and values\n- Shows \"X of Y settings\" when actively searching\n- Displays \"No settings match 'searchterm'\" for no results\n- Includes a clear button (iOS) to reset the search\n- Maintains search state while refreshing data\n\n```typescript\n// Example custom styling\n\u003cSystemSettings \n  ditto={ditto}\n  style={{ \n    flex: 1, \n    backgroundColor: '#1a1a1a',  // Dark theme background\n    paddingTop: 20               // Add top spacing\n  }}\n/\u003e\n```\n\n### QueryEditor\n\nExecute DQL (Document Query Language) queries against your Ditto store with a comprehensive interface for query input, execution, and results display.\n\n```typescript\nimport { QueryEditor } from '@dittolive/ditto-react-native-tools';\n\n\u003cQueryEditor \n  ditto={ditto}\n  style={{ flex: 1 }}\n/\u003e\n```\n\n**Props:**\n- `ditto` (required): Your Ditto instance\n- `style?: ViewStyle` - Custom styling for the main container\n\n**Features:**\n- **Multi-line Query Input**: 3-line TextInput with word wrap and scrollable content for complex DQL queries\n- **Smart Execution**: Run button is disabled when query is empty, with loading state during execution\n- **Results Display**: Supports both SELECT queries (data results) and mutating queries (INSERT/UPDATE/DELETE with affected count)\n- **Performance Optimized**: Handles large result sets (20,000+ records) with FlatList virtualization\n- **Expandable JSON View**: Click any result row to view full JSON details in expandable format\n- **Export Functionality**: Share query results as formatted JSON using React Native's Share API\n- **Cross-platform Compatible**: Works on both iOS and Android with native share dialogs\n\n**Supported Query Types:**\n- **SELECT queries**: Display results in a scrollable list with expandable JSON details\n- **INSERT/UPDATE/DELETE**: Show affected record count and operation success status\n- **SHOW statements**: Display system information and configuration\n\n**Style Customization:**\nThe QueryEditor component consists of three sub-components, each accepting custom styles:\n\n```typescript\ninterface QueryEditorStyles {\n  container?: ViewStyle;           // Main container\n  editorView?: ViewStyle;          // Query input section  \n  headerView?: ViewStyle;          // Buttons section\n  resultsView?: ViewStyle;         // Results display section\n}\n\n\u003cQueryEditor \n  ditto={ditto}\n  style={{\n    container: { flex: 1, backgroundColor: '#f8f9fa' },\n    editorView: { backgroundColor: 'white', padding: 16 },\n    headerView: { backgroundColor: '#e9ecef', borderBottomWidth: 1 },\n    resultsView: { flex: 1, backgroundColor: 'white' }\n  }}\n/\u003e\n```\n\n**Performance Features:**\n- **Virtual Scrolling**: Uses FlatList with `getItemLayout` for optimal performance with large datasets\n- **Memory Management**: Results are dematerialized to prevent memory leaks\n- **Efficient Rendering**: Only visible rows are rendered, supporting 20,000+ records smoothly\n- **Smart Loading States**: Execution and sharing buttons show activity indicators during operations\n\n**Usage Examples:**\n\n```typescript\n// Basic usage for query testing\n\u003cQueryEditor ditto={ditto} /\u003e\n\n// With custom container styling\n\u003cQueryEditor \n  ditto={ditto}\n  style={{ \n    flex: 1, \n    backgroundColor: '#f5f5f5',\n    margin: 10 \n  }}\n/\u003e\n\n// Example queries to try:\n// SELECT * FROM myCollection\n// INSERT INTO myCollection (name, value) VALUES ('test', 123)\n// UPDATE myCollection SET value = 456 WHERE name = 'test'\n// DELETE FROM myCollection WHERE name = 'test'\n// SHOW ALL\n```\n\n# Example App\n\nThis repository includes a fully functional example app demonstrating all features. See the [example directory](./example) for setup instructions and implementation details.\n\n## Development of the Library\n\n### Testing Changes During Development\n\nWhen making changes to the root library code and testing them in the example app, the project is setup with symlinks for testing.   \n\npackage.json:\n```json\n    \"@dittolive/ditto-react-native-tools\": \"file:..\"\n```\n\nTo stop packages from bleeding from the library to the example app, the example app's metro.config.js is setup to only use the modules we need from the library:\n\n```js\n    // Explicitly map only the modules we need from the library\n    extraNodeModules: (() =\u003e {\n      const modules = [\n        'react',\n        'react-native',\n        '@dittolive/ditto',\n        '@dr.pogodin/react-native-fs',\n        'react-native-zip-archive',\n      ];\n      const result = {};\n      for (const mod of modules) {\n        try {\n          // Try to resolve the module from the example app first, then from the library\n          let resolvedPath;\n          try {\n            resolvedPath = path.dirname(require.resolve(`${mod}/package.json`, { paths: [path.resolve(__dirname, 'node_modules')] }));\n          } catch (e) {\n            resolvedPath = path.dirname(require.resolve(`${mod}/package.json`, { paths: [path.resolve(libraryPath, 'node_modules')] }));\n          }\n          if (fs.existsSync(resolvedPath)) {\n            result[mod] = resolvedPath;\n          }\n        } catch (e) {\n          // Module not found, skip\n        }\n      }\n      return result;\n    })(),\n    \n    // Enable symlinks (default in RN 0.77.1, but explicit for clarity)\n    unstable_enableSymlinks: true,\n```\n\n\n#### Development for the Library Workflow\n\nAfter the initial setup, changes to the library source code will be immediately available in the example app:\n\n1. **Make changes** to the library source code in `src/`\n\n2. **Clean all caches and reset development environment**:\n   ```bash\n   cd example\n   ./clear-cache.sh\n   ```\n\n3. **Start Metro** (if not already running):\n   ```bash\n   npx react-native start --reset-cache\n   ```\n\n4. **Run the app**:\n   ```bash\n   # In a new terminal:\n   yarn ios --simulator=\"iPhone 16 Pro\"\n   # or\n   yarn android\n   ```\n\n\u003e **Note**: With this setup, changes to the library code are immediately reflected in the example app through Fast Refresh. No need to rebuild or reinstall the library after each change!\n\n\u003e **Important**: The Metro configuration includes a custom resolver that directly points to the library's TypeScript source files, enabling live updates without compilation.\n\n### Deploying example app to connected Android Device\n\nTo build and deploy the example app to a connected Android device:\n\n#### Prerequisites\n\n1. **Enable Developer Mode** on your Android device:\n   - Go to Settings → About phone\n   - Tap \"Build number\" 7 times\n   - Go back to Settings → Developer options\n   - Enable \"USB debugging\"\n\n2. **Connect your device** via USB and verify connection:\n   ```bash\n   adb devices\n   ```\n   You should see your device listed (e.g., `R5CN30DYCWA device`)\n\n#### Building and Installing\n\nThere are two methods to deploy to your device:\n\n##### Method 1: Direct Installation (Recommended if yarn android fails)\n\n1. **Clean previous builds** (if needed):\n   ```bash\n   cd example/android\n   ./gradlew clean\n   ```\n\n2. **Build the APK**:\n   ```bash\n   ./gradlew assembleDebug\n   ```\n\n3. **Install the APK**:\n   ```bash\n   adb install app/build/outputs/apk/debug/app-debug.apk\n   ```\n\n4. **Start Metro bundler**:\n   ```bash\n   cd ../  # Back to example directory\n   npx react-native start --reset-cache\n   ```\n\n5. **Launch the app**:\n   ```bash\n   adb shell monkey -p com.ditto.example -c android.intent.category.LAUNCHER 1\n   ```\n\n##### Method 2: Using React Native CLI\n\n```bash\ncd example\nyarn android\n```\n\nThis command will automatically build and deploy to the connected device.\n\n#### Troubleshooting\n\n- **App not launching**: Make sure the Metro bundler is running before launching the app\n- **Device not found**: Ensure USB debugging is enabled and the device is properly connected\n\n#### Reverting to Normal Dependencies\n\nIf you need to revert to the standard `file:..` dependency:\n\n```bash\ncd example\nyarn unlink \"@dittolive/ditto-react-native-tools\"\nyarn install --force\n```\n\n### Environment Variables\n\nThe example app uses environment variables for Ditto configuration. After changing values in the `.env` file:\n\n1. **Restart Metro** with cache reset:\n   ```bash\n   npx react-native start --reset-cache\n   ```\n\n2. **Rebuild the app** to pick up the new environment values:\n   ```bash\n   yarn ios --simulator=\"iPhone 16 Pro\"\n   ```\n\n\u003e **Note**: Environment variables are compiled into the JavaScript bundle at build time, so you must rebuild the app after changing `.env` values.\n\n# Credits\n\nThis library utilizes the following open-source projects:\n- **[@dr.pogodin/react-native-fs](https://github.com/dr-pogodin-react-native/react-native-fs)** - File system access for React Native apps\n- **[react-native-zip-archive](https://github.com/mockingbot/react-native-zip-archive)** - ZIP archive creation and extraction for React Native\n\nWe greatly appreciate the maintainers and contributors of these projects for making this library possible.\n\n## Core Dependencies\n- **[Ditto](https://github.com/getditto/ditto)** - Edge sync platform for building real-time collaborative apps","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgetditto%2Freact-native-ditto-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgetditto%2Freact-native-ditto-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgetditto%2Freact-native-ditto-tools/lists"}