@sync-vault-js/react-native

React Native integration for SyncVault - Provides AsyncStorage adapter and React Native-specific utilities for offline-first sync.

Installation

``bash
npm install @sync-vault-js/react-native @sync-vault-js/core @react-native-async-storage/async-storage @react-native-community/netinfo


or

yarn add @sync-vault-js/react-native @sync-vault-js/core @react-native-async-storage/async-storage @react-native-community/netinfo

or

pnpm add @sync-vault-js/react-native @sync-vault-js/core @react-native-async-storage/async-storage @react-native-community/netinfo
`

$3

- @sync-vault-js/core - Core SyncVault package (required)
- @react-native-async-storage/async-storage - Storage adapter (required)
- @react-native-community/netinfo - Network detection (optional, but recommended)

Quick Start

$3

The easiest way to get started is using createReactNativeSyncVault():

`typescript
import AsyncStorage from '@react-native-async-storage/async-storage';
import NetInfo from '@react-native-community/netinfo';
import { createReactNativeSyncVault } from '@sync-vault-js/react-native';

// Create a SyncVault instance configured for React Native
const vault = createReactNativeSyncVault({
asyncStorage: AsyncStorage,
netInfo: NetInfo,
debug: true,
retry: {
maxRetries: 3,
initialDelay: 1000,
},
});

// Make requests - automatically queued when offline
const response = await vault.post('/api/users', {
name: 'John Doe',
email: 'john@example.com',
});

// Check if request was queued
if (response.fromQueue) {
console.log('Request queued for later sync');
}
`

$3

For more control, you can configure storage and network separately:

`typescript
import AsyncStorage from '@react-native-async-storage/async-storage';
import NetInfo from '@react-native-community/netinfo';
import { createSyncVault } from '@sync-vault-js/core';
import {
createAsyncStorageAdapter,
createReactNativeNetworkChecker,
} from '@sync-vault-js/react-native';

// Create storage adapter
const storage = createAsyncStorageAdapter(AsyncStorage);

// Create network checker
const networkChecker = createReactNativeNetworkChecker(NetInfo);

// Create SyncVault instance
const vault = createSyncVault({
storage,
networkChecker,
debug: true,
});
`

Usage with React

You can use the React hooks from @sync-vault-js/core/react with the React Native package:

`tsx
import AsyncStorage from '@react-native-async-storage/async-storage';
import NetInfo from '@react-native-community/netinfo';
import { useSyncVault } from '@sync-vault-js/core/react';
import { createAsyncStorageAdapter, createReactNativeNetworkChecker } from '@sync-vault-js/react-native';
import { createSyncVault } from '@sync-vault-js/core';

// Create instance with React Native adapters
const vault = createSyncVault({
storage: createAsyncStorageAdapter(AsyncStorage),
networkChecker: createReactNativeNetworkChecker(NetInfo),
});

function MyComponent() {
const { isOnline, isProcessing, queueLength, post } = useSyncVault();

const handleSubmit = async (data) => {
const response = await post('/api/data', data);

if (response.fromQueue) {
Alert.alert('Saved offline', 'Will sync when online');
}
};

return (

Status: {isOnline ? 'Online' : 'Offline'}
Queue: {queueLength} pending
handleSubmit({ name: 'Test' })} title="Submit" />

);
}
`

API Reference

$3

Convenience function that creates a fully configured SyncVault instance for React Native.

Parameters:
- options.asyncStorage - AsyncStorage instance from @react-native-async-storage/async-storage
- options.netInfo - NetInfo instance from @react-native-community/netinfo
- options.* - All other SyncVaultConfig options (see core documentation)

Returns: SyncVault instance

$3

Creates an AsyncStorage-based storage adapter.

Parameters:
- asyncStorage - AsyncStorage instance from @react-native-async-storage/async-storage

Returns: AsyncStorageAdapter instance

$3

Creates a network checker using React Native NetInfo.

Parameters:
- netInfo - NetInfo instance from @react-native-community/netinfo

Returns: NetworkChecker instance

$3

Storage adapter implementation that uses AsyncStorage for persistence.

Methods:
- init() - Initialize the storage
- add(job) - Add a job to the queue
- getAll() - Get all pending jobs
- get(id) - Get a specific job
- update(id, updates) - Update a job
- remove(id) - Remove a job
- count() - Get count of pending jobs
- clear() - Clear all jobs
- moveToDLQ(job) - Move a job to Dead Letter Queue
- getDLQ() - Get all jobs in Dead Letter Queue
- clearDLQ() - Clear Dead Letter Queue
- close() - Close the storage

Storage Details

The AsyncStorage adapter stores data using the following keys:
- @syncvault:queue - Main queue storage
- @syncvault:dlq - Dead Letter Queue storage

Jobs are stored as JSON arrays and automatically sorted by timestamp to maintain FIFO ordering.

Examples

$3

`typescript
import AsyncStorage from '@react-native-async-storage/async-storage';
import NetInfo from '@react-native-community/netinfo';
import { createReactNativeSyncVault } from '@sync-vault-js/react-native';

const vault = createReactNativeSyncVault({
asyncStorage: AsyncStorage,
netInfo: NetInfo,
});

// Make requests
await vault.post('/api/users', { name: 'John' });
await vault.get('/api/users');
`

$3

`typescript
const vault = createReactNativeSyncVault({
asyncStorage: AsyncStorage,
netInfo: NetInfo,
retry: {
maxRetries: 5,
initialDelay: 2000,
maxDelay: 60000,
},
queue: {
concurrency: 2,
processingDelay: 500,
},
debug: true,
});
`

$3

`typescript
vault.on('network_offline', () => {
console.log('Device went offline');
});

vault.on('network_online', () => {
console.log('Device came online - processing queue');
});

vault.on('job_success', (event) => {
console.log('Job completed:', event.data.job.id);
});

vault.on('job_failed', (event) => {
if (!event.data.willRetry) {
console.error('Job failed permanently:', event.data.error);
}
});
`

Migration from Core Package

If you were previously using the core package with manual setup:

Before:
`typescript
import { createSyncVault, createReactNativeNetworkChecker } from '@sync-vault-js/core';
// Had to use MemoryAdapter (no persistence)
`

After:
`typescript
import { createReactNativeSyncVault } from '@sync-vault-js/react-native';
// Now has persistent storage with AsyncStorage
`

Troubleshooting

$3

Make sure you've installed @react-native-async-storage/async-storage:

`bash
npm install @react-native-async-storage/async-storage
`

For iOS, you may need to run:
`bash
cd ios && pod install
`

$3

Ensure @react-native-community/netinfo is installed and properly linked:

`bash
npm install @react-native-community/netinfo
cd ios && pod install # For iOS
`

$3

AsyncStorage may have size limitations. If you're storing large amounts of data, consider:
- Clearing old jobs periodically
- Implementing custom storage with a different backend
- Using the DLQ to manage failed jobs

Related Packages

- @sync-vault-js/core - Core SyncVault package
- @sync-vault-js/core/react - React hooks integration

Contributing

Contributions are welcome! We appreciate your help in making this project better.

$3

1. Fork the repository and clone it locally
2. Create a branch for your feature or bug fix:
`bash
git checkout -b feature/your-feature-name
`
3. Make your changes and ensure they follow the project's code style
4. Add tests if applicable
5. Run the build and type checking:
`bash
npm run build
npm run typecheck
`
6. Commit your changes with a clear message
7. Push to your fork and create a Pull Request

$3

`bash


Install dependencies

npm install

Run in development mode (watch mode)

npm run dev

Build the package

npm run build

Run type checking

npm run typecheck
``

$3

If you find a bug or have a feature request, please open an issue on GitHub with:
- A clear description of the problem or feature
- Steps to reproduce (for bugs)
- Expected vs actual behavior
- Environment details (React Native version, Node version, etc.)

$3

- Follow TypeScript best practices
- Use meaningful variable and function names
- Add comments for complex logic
- Ensure all code is properly typed

License

MIT © SyncVault

Authors

Nabhodipta Garai

- GitHub: @brownboycodes
- LinkedIn: Nabhodipta Garai
-