Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/getditto/react-native-ditto-tools

Diagnostic and Debugging Tools for Ditto for React Native SDK
https://github.com/getditto/react-native-ditto-tools

Last synced: 3 months ago
JSON representation

Diagnostic and Debugging Tools for Ditto for React Native SDK

Awesome Lists containing this project

README 

          
# @dittolive/ditto-react-native-tools



## Diagonistic and Debugging Tools for Ditto in React Native 



> **⚠️ Platform Compatibility Notice**  

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



### Required Dependencies



This library requires the following peer dependencies to be installed in your app:



- `@dittolive/ditto` - Core Ditto SDK (>=4.11.6 - Tested on 4.11.6 and 4.12.2)

- `@dr.pogodin/react-native-fs` - File system operations for log export and data directory cleanup

- `react-native-zip-archive` - Directory compression for data export functionality



> [!warning] 

> Some tools require iOS version 15.5 or higher. You may need to update your iOS target version.  



> [!NOTE] 

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



## Installation



```sh

npm install @dittolive/ditto-react-native-tools @dittolive/ditto @dr.pogodin/react-native-fs react-native-zip-archive

```



or



```sh

yarn add @dittolive/ditto-react-native-tools @dittolive/ditto @dr.pogodin/react-native-fs react-native-zip-archive

```



### iOS Setup



After installing dependencies, run:



```sh

cd ios && pod install && cd ..

```



### Android Setup



For React Native 0.77.1+, auto-linking should handle Android setup automatically. If you encounter linking issues, clean your build:



```sh

cd android && ./gradlew clean && cd ..

```



## Platform Setup



After installing this library, you need to configure your React Native app for Ditto.



**Please follow the official Ditto React Native quickstart guide:**

[React Native Setup](https://docs.ditto.live/sdk/latest/quickstarts/react-native)



## Usage



```typescript

import React from 'react';

import { PeersList, DiskUsage, SystemSettings, QueryEditor } from '@dittolive/ditto-react-native-tools';

import { Ditto } from '@dittolive/ditto';



// Initialize your Ditto instance

const ditto = new Ditto({

  type: 'offlinePlayground',

  appID: 'your-app-id',

  offlineToken: 'your-offline-token',

});



function App() {

  return (

    <>

      

    >

  );

}

```



> [!NOTE] 

> Ditto instance should always be kept in a [provider](https://react.dev/reference/react/createContext#provider). 



## Components



### PeersList



Display and monitor Ditto peer connections in real-time.



```typescript

import { PeersList } from '@dittolive/ditto-react-native-tools';



```



**Props:**

- `ditto` (required): Your Ditto instance

- `showConnectionDetails?: boolean` - Whether to show detailed connection information (default: true)

- `style?: ViewStyle` - Custom styling for the main container

- `headerComponent?: () => React.ReactElement` - Optional header component



**Style Customization:**

The component's styling is controlled through built-in StyleSheet with the following key areas that can be customized via the `style` prop:

- **Main container**: Background color, flex properties, padding

- **List content**: Bottom padding and scroll behavior

- **Peer items**: Card-style containers with shadows and rounded corners

- **Loading/Error states**: Centered content with appropriate typography



```typescript

// Example custom styling



```



### DiskUsage



Monitor and display Ditto's disk usage breakdown with export functionality.



```typescript

import { DiskUsage } from '@dittolive/ditto-react-native-tools';



```



**Props:**

- `ditto` (required): Your Ditto instance

- `style?: ViewStyle` - Custom styling for the main container



**Features:**

- **Automatic Log Export**: The "Export Logs" button uses Ditto's built-in `Logger.exportToFile()` method to save log files

- **Disk Usage Display**: Shows real-time disk usage breakdown for different Ditto components (store, replication, attachments, auth)

- **Last Updated Time**: Footer displays when the data was last refreshed



**Style Customization:**

The component's styling is controlled through built-in StyleSheet with the following key areas that can be customized via the `style` prop:

- **Main container**: Background color, flex properties, padding

- **Content layout**: Card-style containers with proper spacing

- **Usage displays**: Progress bars, labels, and value formatting

- **Action buttons**: Export button styling and disabled states

- **Footer information**: Last updated timestamp styling



```typescript

// Example custom styling



```



### SystemSettings



Display all Ditto system settings using the `SHOW ALL` DQL statement. Self-contained component with built-in refresh functionality.



```typescript

import { SystemSettings } from '@dittolive/ditto-react-native-tools';



```



**Props:**

- `ditto` (required): Your Ditto instance

- `style?: ViewStyle` - Custom styling for the main container



**Features:**

- **Self-contained**: No callbacks required - handles all interactions internally

- **System Settings Display**: Shows all Ditto system settings from SHOW ALL DQL query

- **Real-time Search**: Built-in search functionality with instant filtering

- **Search Capabilities**: Case-insensitive search across both setting keys and values

- **Smart Count Display**: Shows filtered results count (e.g., "5 of 141 settings")

- **Refresh Functionality**: Built-in refresh button to reload settings

- **Performance Optimized**: Uses FlatList virtualization and in-memory filtering for 200+ settings

- **Loading States**: Automatic loading, error, and empty state handling

- **Visual Design**: Clean search interface with bordered input and proper typography



**Style Customization:**

The component's styling is controlled through built-in StyleSheet with the following key areas that can be customized via the `style` prop:

- **Main container**: Background color, flex properties, padding

- **Header section**: Settings count and refresh button layout

- **Settings list**: Individual setting items with key-value pairs

- **Loading/Error states**: Centered content with appropriate messaging

- **Footer information**: Last updated timestamp styling



**Search Functionality:**

The component includes a built-in search feature that:

- Filters settings in real-time as you type

- Searches both setting keys and values

- Shows "X of Y settings" when actively searching

- Displays "No settings match 'searchterm'" for no results

- Includes a clear button (iOS) to reset the search

- Maintains search state while refreshing data



```typescript

// Example custom styling



```



### QueryEditor



Execute DQL (Document Query Language) queries against your Ditto store with a comprehensive interface for query input, execution, and results display.



```typescript

import { QueryEditor } from '@dittolive/ditto-react-native-tools';



```



**Props:**

- `ditto` (required): Your Ditto instance

- `style?: ViewStyle` - Custom styling for the main container



**Features:**

- **Multi-line Query Input**: 3-line TextInput with word wrap and scrollable content for complex DQL queries

- **Smart Execution**: Run button is disabled when query is empty, with loading state during execution

- **Results Display**: Supports both SELECT queries (data results) and mutating queries (INSERT/UPDATE/DELETE with affected count)

- **Performance Optimized**: Handles large result sets (20,000+ records) with FlatList virtualization

- **Expandable JSON View**: Click any result row to view full JSON details in expandable format

- **Export Functionality**: Share query results as formatted JSON using React Native's Share API

- **Cross-platform Compatible**: Works on both iOS and Android with native share dialogs



**Supported Query Types:**

- **SELECT queries**: Display results in a scrollable list with expandable JSON details

- **INSERT/UPDATE/DELETE**: Show affected record count and operation success status

- **SHOW statements**: Display system information and configuration



**Style Customization:**

The QueryEditor component consists of three sub-components, each accepting custom styles:



```typescript

interface QueryEditorStyles {

  container?: ViewStyle;           // Main container

  editorView?: ViewStyle;          // Query input section  

  headerView?: ViewStyle;          // Buttons section

  resultsView?: ViewStyle;         // Results display section

}



```



**Performance Features:**

- **Virtual Scrolling**: Uses FlatList with `getItemLayout` for optimal performance with large datasets

- **Memory Management**: Results are dematerialized to prevent memory leaks

- **Efficient Rendering**: Only visible rows are rendered, supporting 20,000+ records smoothly

- **Smart Loading States**: Execution and sharing buttons show activity indicators during operations



**Usage Examples:**



```typescript

// Basic usage for query testing



// With custom container styling



// Example queries to try:

// SELECT * FROM myCollection

// INSERT INTO myCollection (name, value) VALUES ('test', 123)

// UPDATE myCollection SET value = 456 WHERE name = 'test'

// DELETE FROM myCollection WHERE name = 'test'

// SHOW ALL

```



# Example App



This repository includes a fully functional example app demonstrating all features. See the [example directory](./example) for setup instructions and implementation details.



## Development of the Library



### Testing Changes During Development



When making changes to the root library code and testing them in the example app, the project is setup with symlinks for testing.   



package.json:

```json

    "@dittolive/ditto-react-native-tools": "file:.."

```



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



```js

    // Explicitly map only the modules we need from the library

    extraNodeModules: (() => {

      const modules = [

        'react',

        'react-native',

        '@dittolive/ditto',

        '@dr.pogodin/react-native-fs',

        'react-native-zip-archive',

      ];

      const result = {};

      for (const mod of modules) {

        try {

          // Try to resolve the module from the example app first, then from the library

          let resolvedPath;

          try {

            resolvedPath = path.dirname(require.resolve(`${mod}/package.json`, { paths: [path.resolve(__dirname, 'node_modules')] }));

          } catch (e) {

            resolvedPath = path.dirname(require.resolve(`${mod}/package.json`, { paths: [path.resolve(libraryPath, 'node_modules')] }));

          }

          if (fs.existsSync(resolvedPath)) {

            result[mod] = resolvedPath;

          }

        } catch (e) {

          // Module not found, skip

        }

      }

      return result;

    })(),

    

    // Enable symlinks (default in RN 0.77.1, but explicit for clarity)

    unstable_enableSymlinks: true,

```



#### Development for the Library Workflow



After the initial setup, changes to the library source code will be immediately available in the example app:



1. **Make changes** to the library source code in `src/`



2. **Clean all caches and reset development environment**:

   ```bash

   cd example

   ./clear-cache.sh

   ```



3. **Start Metro** (if not already running):

   ```bash

   npx react-native start --reset-cache

   ```



4. **Run the app**:

   ```bash

   # In a new terminal:

   yarn ios --simulator="iPhone 16 Pro"

   # or

   yarn android

   ```



> **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!



> **Important**: The Metro configuration includes a custom resolver that directly points to the library's TypeScript source files, enabling live updates without compilation.



### Deploying example app to connected Android Device



To build and deploy the example app to a connected Android device:



#### Prerequisites



1. **Enable Developer Mode** on your Android device:

   - Go to Settings → About phone

   - Tap "Build number" 7 times

   - Go back to Settings → Developer options

   - Enable "USB debugging"



2. **Connect your device** via USB and verify connection:

   ```bash

   adb devices

   ```

   You should see your device listed (e.g., `R5CN30DYCWA device`)



#### Building and Installing



There are two methods to deploy to your device:



##### Method 1: Direct Installation (Recommended if yarn android fails)



1. **Clean previous builds** (if needed):

   ```bash

   cd example/android

   ./gradlew clean

   ```



2. **Build the APK**:

   ```bash

   ./gradlew assembleDebug

   ```



3. **Install the APK**:

   ```bash

   adb install app/build/outputs/apk/debug/app-debug.apk

   ```



4. **Start Metro bundler**:

   ```bash

   cd ../  # Back to example directory

   npx react-native start --reset-cache

   ```



5. **Launch the app**:

   ```bash

   adb shell monkey -p com.ditto.example -c android.intent.category.LAUNCHER 1

   ```



##### Method 2: Using React Native CLI



```bash

cd example

yarn android

```



This command will automatically build and deploy to the connected device.



#### Troubleshooting



- **App not launching**: Make sure the Metro bundler is running before launching the app

- **Device not found**: Ensure USB debugging is enabled and the device is properly connected



#### Reverting to Normal Dependencies



If you need to revert to the standard `file:..` dependency:



```bash

cd example

yarn unlink "@dittolive/ditto-react-native-tools"

yarn install --force

```



### Environment Variables



The example app uses environment variables for Ditto configuration. After changing values in the `.env` file:



1. **Restart Metro** with cache reset:

   ```bash

   npx react-native start --reset-cache

   ```



2. **Rebuild the app** to pick up the new environment values:

   ```bash

   yarn ios --simulator="iPhone 16 Pro"

   ```



> **Note**: Environment variables are compiled into the JavaScript bundle at build time, so you must rebuild the app after changing `.env` values.



# Credits



This library utilizes the following open-source projects:

- **[@dr.pogodin/react-native-fs](https://github.com/dr-pogodin-react-native/react-native-fs)** - File system access for React Native apps

- **[react-native-zip-archive](https://github.com/mockingbot/react-native-zip-archive)** - ZIP archive creation and extraction for React Native



We greatly appreciate the maintainers and contributors of these projects for making this library possible.



## Core Dependencies

- **[Ditto](https://github.com/getditto/ditto)** - Edge sync platform for building real-time collaborative apps