react-native-pdf-jsi/INTEGRATION_GUIDE.md

🚀 Ultra-fast React Native PDF viewer with JSI (JavaScript Interface) integration for maximum performance. Features lazy loading, smart caching, progressive loading, and zero-bridge overhead operations. Perfect for large PDF files with 30-day persistent c

# Enhanced PDF JSI Integration Guide

## Overview

This guide shows you how to integrate and use the Enhanced PDF JSI functionality in your React Native application. The JSI integration provides **22.5x faster** PDF operations compared to traditional bridge-based methods.

## 🚀 Quick Start

### 1. Import JSI Components

```javascript
// Basic imports
import { PDFJSI, EnhancedPdfView, usePDFJSI } from 'react-native-pdf';

// Or import individual methods
import { 
    renderPageDirect, 
    getPageMetrics, 
    preloadPagesDirect 
} from 'react-native-pdf';
```

### 2. Check JSI Availability

```javascript
import { PDFJSI } from 'react-native-pdf';

const checkJSI = async () => {
    const isAvailable = await PDFJSI.checkJSIAvailability();
    console.log('JSI Available:', isAvailable);
    
    if (isAvailable) {
        console.log('🚀 High-performance mode enabled!');
    } else {
        console.log('📱 Using standard bridge mode');
    }
};
```

## 📱 Usage Examples

### Method 1: Direct JSI Usage

```javascript
import { PDFJSI } from 'react-native-pdf';

const MyPDFComponent = () => {
    const handleRenderPage = async () => {
        try {
            const result = await PDFJSI.renderPageDirect(
                'pdf_123',     // PDF ID
                1,             // Page number
                2.0,           // Scale factor
                base64Data     // Base64 PDF data
            );
            
            if (result.success) {
                console.log('Page rendered successfully!');
                // Use result.data for the rendered page
            }
        } catch (error) {
            console.error('Render failed:', error);
        }
    };
    
    return (
        <TouchableOpacity onPress={handleRenderPage}>
            <Text>Render Page</Text>
        </TouchableOpacity>
    );
};
```

### Method 2: Hook-based Usage

```javascript
import { usePDFJSI } from 'react-native-pdf';

const MyPDFComponent = () => {
    const {
        isJSIAvailable,
        isInitialized,
        renderPage,
        getPageMetrics,
        preloadPages,
        searchText
    } = usePDFJSI({
        autoInitialize: true,
        enablePerformanceTracking: true
    });
    
    const handleOperations = async () => {
        if (!isJSIAvailable) return;
        
        try {
            // Render page
            const renderResult = await renderPage('pdf_123', 1, 2.0, base64Data);
            
            // Get page metrics
            const metrics = await getPageMetrics('pdf_123', 1);
            
            // Preload pages
            await preloadPages('pdf_123', 1, 5);
            
            // Search text
            const searchResults = await searchText('pdf_123', 'search term', 1, 10);
            
        } catch (error) {
            console.error('JSI operations failed:', error);
        }
    };
    
    return (
        <View>
            <Text>JSI Status: {isJSIAvailable ? 'Available' : 'Not Available'}</Text>
            <TouchableOpacity onPress={handleOperations}>
                <Text>Run JSI Operations</Text>
            </TouchableOpacity>
        </View>
    );
};
```

### Method 3: Enhanced PDF View

```javascript
import { EnhancedPdfView } from 'react-native-pdf';

const MyPDFViewer = () => {
    return (
        <EnhancedPdfView
            source={{ uri: 'https://example.com/document.pdf' }}
            style={{ flex: 1 }}
            onLoadComplete={(numberOfPages) => {
                console.log(`PDF loaded: ${numberOfPages} pages`);
            }}
            onPageChanged={(page) => {
                console.log(`Current page: ${page}`);
            }}
            // JSI-specific props
            jsiEnabled={true}
            enablePerformanceTracking={true}
            enableSmartCaching={true}
        />
    );
};
```

## 🔧 Advanced Features

### Performance Monitoring

```javascript
import { PDFJSI } from 'react-native-pdf';

const PerformanceMonitor = () => {
    const [metrics, setMetrics] = useState(null);
    
    const updateMetrics = async () => {
        try {
            // Get JSI statistics
            const stats = await PDFJSI.getJSIStats();
            console.log('JSI Stats:', stats);
            
            // Get performance metrics
            const perfMetrics = await PDFJSI.getPerformanceMetrics('pdf_123');
            setMetrics(perfMetrics);
            
            // Get performance history
            const history = PDFJSI.getPerformanceHistory();
            console.log('Performance History:', history);
            
        } catch (error) {
            console.error('Error getting metrics:', error);
        }
    };
    
    return (
        <View>
            <TouchableOpacity onPress={updateMetrics}>
                <Text>Update Metrics</Text>
            </TouchableOpacity>
            
            {metrics && (
                <Text>Performance: {JSON.stringify(metrics, null, 2)}</Text>
            )}
        </View>
    );
};
```

### Cache Management

```javascript
import { PDFJSI } from 'react-native-pdf';

const CacheManager = () => {
    const handleCacheOperations = async () => {
        try {
            // Get cache metrics
            const cacheMetrics = await PDFJSI.getCacheMetrics('pdf_123');
            console.log('Cache Metrics:', cacheMetrics);
            
            // Clear specific cache type
            await PDFJSI.clearCacheDirect('pdf_123', 'base64');
            
            // Clear all caches
            await PDFJSI.clearCacheDirect('pdf_123', 'all');
            
            // Optimize memory
            await PDFJSI.optimizeMemory('pdf_123');
            
        } catch (error) {
            console.error('Cache operations failed:', error);
        }
    };
    
    return (
        <TouchableOpacity onPress={handleCacheOperations}>
            <Text>Manage Cache</Text>
        </TouchableOpacity>
    );
};
```

### Text Search

```javascript
import { PDFJSI } from 'react-native-pdf';

const TextSearch = () => {
    const [searchTerm, setSearchTerm] = useState('');
    const [results, setResults] = useState([]);
    
    const handleSearch = async () => {
        try {
            const searchResults = await PDFJSI.searchTextDirect(
                'pdf_123',
                searchTerm,
                1,    // Start page
                10    // End page
            );
            
            setResults(searchResults);
            console.log(`Found ${searchResults.length} matches`);
            
        } catch (error) {
            console.error('Search failed:', error);
        }
    };
    
    return (
        <View>
            <TextInput
                value={searchTerm}
                onChangeText={setSearchTerm}
                placeholder="Enter search term"
            />
            <TouchableOpacity onPress={handleSearch}>
                <Text>Search</Text>
            </TouchableOpacity>
            
            {results.map((result, index) => (
                <Text key={index}>
                    Page {result.page}: {result.text}
                </Text>
            ))}
        </View>
    );
};
```

## 🎯 Performance Optimization

### Preloading Strategy

```javascript
import { PDFJSI } from 'react-native-pdf';

const SmartPreloader = () => {
    const preloadPages = async (pdfId, currentPage) => {
        try {
            // Preload current page ± 2 pages
            const startPage = Math.max(1, currentPage - 2);
            const endPage = currentPage + 2;
            
            await PDFJSI.preloadPagesDirect(pdfId, startPage, endPage);
            console.log(`Preloaded pages ${startPage}-${endPage}`);
            
        } catch (error) {
            console.error('Preload failed:', error);
        }
    };
    
    return preloadPages;
};
```

### Quality Control

```javascript
import { PDFJSI } from 'react-native-pdf';

const QualityController = () => {
    const setQuality = async (quality) => {
        try {
            // Quality levels: 1 (low), 2 (medium), 3 (high)
            await PDFJSI.setRenderQuality('pdf_123', quality);
            console.log(`Render quality set to: ${quality}`);
            
        } catch (error) {
            console.error('Quality setting failed:', error);
        }
    };
    
    return (
        <View>
            <TouchableOpacity onPress={() => setQuality(1)}>
                <Text>Low Quality (Fast)</Text>
            </TouchableOpacity>
            <TouchableOpacity onPress={() => setQuality(2)}>
                <Text>Medium Quality</Text>
            </TouchableOpacity>
            <TouchableOpacity onPress={() => setQuality(3)}>
                <Text>High Quality (Slow)</Text>
            </TouchableOpacity>
        </View>
    );
};
```

## 🔄 Migration from Bridge Mode

### Before (Bridge Mode)
```javascript
import Pdf from 'react-native-pdf';

// Traditional bridge-based usage
<Pdf
    source={{ uri: 'https://example.com/document.pdf' }}
    style={{ flex: 1 }}
/>
```

### After (JSI Mode)
```javascript
import { EnhancedPdfView } from 'react-native-pdf';

// Enhanced JSI-based usage
<EnhancedPdfView
    source={{ uri: 'https://example.com/document.pdf' }}
    style={{ flex: 1 }}
    jsiEnabled={true}
    enablePerformanceTracking={true}
/>
```

## 🛠️ Troubleshooting

### Common Issues

1. **JSI Not Available**
   ```javascript
   // Always check availability first
   const isAvailable = await PDFJSI.checkJSIAvailability();
   if (!isAvailable) {
       // Fallback to bridge mode
       console.log('Using bridge mode');
   }
   ```

2. **Performance Issues**
   ```javascript
   // Check performance metrics
   const metrics = await PDFJSI.getPerformanceMetrics('pdf_123');
   console.log('Performance:', metrics);
   
   // Clear caches if needed
   await PDFJSI.clearCacheDirect('pdf_123', 'all');
   ```

3. **Memory Issues**
   ```javascript
   // Optimize memory usage
   await PDFJSI.optimizeMemory('pdf_123');
   
   // Set lower render quality
   await PDFJSI.setRenderQuality('pdf_123', 1);
   ```

## 📊 Performance Comparison

| Operation | Bridge Mode | JSI Mode | Improvement |
|-----------|-------------|----------|-------------|
| Page Render | 45ms | 2ms | **22.5x faster** |
| Page Metrics | 12ms | 0.5ms | **24x faster** |
| Cache Access | 8ms | 0.1ms | **80x faster** |
| Text Search | 120ms | 15ms | **8x faster** |

## 🎉 Best Practices

1. **Always check JSI availability** before using JSI methods
2. **Use preloading** for better user experience
3. **Monitor performance** with built-in metrics
4. **Clear caches** periodically to free memory
5. **Set appropriate render quality** based on needs
6. **Handle errors gracefully** with fallback to bridge mode

## 📚 Additional Resources

- [README_JSI.md](./README_JSI.md) - Detailed JSI documentation
- [PDFJSIExample.js](./src/examples/PDFJSIExample.js) - Complete examples
- [Performance Benchmarks](./README_JSI.md#performance-characteristics) - Detailed performance data

---

**Ready to supercharge your PDF performance?** 🚀

Start with the basic examples above and gradually incorporate advanced features as needed. The JSI integration is designed to be backward-compatible, so you can migrate at your own pace.