https://github.com/athexweb3/react-native-bg-upload
https://github.com/athexweb3/react-native-bg-upload
Last synced: 6 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/athexweb3/react-native-bg-upload
- Owner: athexweb3
- License: mit
- Created: 2025-11-27T04:38:00.000Z (8 months ago)
- Default Branch: develop
- Last Pushed: 2025-11-28T18:26:51.000Z (8 months ago)
- Last Synced: 2025-11-29T21:58:39.081Z (8 months ago)
- Language: TypeScript
- Size: 2.71 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
React Native Background Upload SDK
Production-grade SDK for reliable background file uploads on React Native. Survives app kills, network drops, and device reboots.
## Features
- **Resumable**: Survives app kills, low memory, and device reboots
- **Chunking**: Automatic chunking for large files with resume capability
- **Retry Logic**: Exponential backoff with jitter for transient failures
- **Network Aware**: Auto pause/resume on connectivity changes
- **Secure**: Credential refresh hooks, no long-term token storage
- **Native Notifications**: Foreground service with progress (Android)
- **Persistent Queue**: MMKV-based storage for instant recovery
- **React Hooks**: `useUpload()` for seamless integration
- **Observable**: Progress, completion, error events
- **Battle Tested**: Comprehensive test suite included
## Platform Support
| Feature | Android (API 21+) | iOS (11+) |
| :-------------------- | :---------------: | :-----------: |
| Background Uploads | WorkManager | URLSession |
| App Kill Survival | Yes | Yes |
| Device Reboot | Yes | Yes |
| Chunking & Resume | Yes | Yes |
| Retry & Backoff | Yes | Yes |
| Progress Notification | Yes | N/A |
| Network Monitoring | Yes | Yes |
## Installation
```bash
npm install react-native-bg-upload react-native-mmkv @react-native-community/netinfo
# or
yarn add react-native-bg-upload react-native-mmkv @react-native-community/netinfo
```
**iOS**: `cd ios && pod install`
## Quick Start
```typescript
import { BgUpload } from 'react-native-bg-upload';
// Start an upload
const taskId = await BgUpload.start({
id: 'video-upload-1',
url: 'https://api.example.com/upload',
path: 'file:///path/to/large-video.mp4',
headers: {
Authorization: 'Bearer YOUR_TOKEN',
},
chunking: {
enabled: true, // Auto-enabled for files > 5MB
chunkSize: 5 * 1024 * 1024, // 5MB chunks
},
retryPolicy: {
maxAttempts: 5,
baseDelay: 1000,
maxDelay: 30000,
},
// Android only
notification: {
enabled: true,
title: 'Uploading Video',
},
});
```
## Using Hooks
```typescript
import { useUpload } from 'react-native-bg-upload';
function UploadScreen({ taskId }) {
const task = useUpload(taskId);
if (!task) return null;
return (
State: {task.state}
Progress: {task.progress}%
{task.state === 'UPLOADING' && (
BgUpload.pause(taskId)} />
)}
{task.error && {task.error}}
);
}
```
## API Reference
### `BgUpload.start(options): Promise`
Start a background upload. Returns the task ID.
#### Options
| Option | Type | Required | Description |
| :-------------------- | :--------- | :------: | :------------------------------ |
| `id` | `string` | Yes | Unique task identifier |
| `url` | `string` | Yes | Upload destination URL |
| `path` | `string` | Yes | Absolute file path (file://) |
| `method` | `string` | | HTTP method (default: POST) |
| `headers` | `object` | | HTTP headers |
| `networkType` | `string` | | 'ANY', 'WIFI_ONLY', 'UNMETERED' |
| `chunking` | `object` | | Chunking configuration |
| `retryPolicy` | `object` | | Retry configuration |
| `onCredentialRefresh` | `function` | | Token refresh callback |
| `notification` | `object` | | Android notification config |
#### Chunking Options
```typescript
{
enabled?: boolean; // Enable chunking (default: true for > 5MB)
chunkSize?: number; // Chunk size in bytes (default: 5MB)
maxConcurrent?: number; // Max concurrent chunks (default: 3)
}
```
#### Retry Policy
```typescript
{
maxAttempts?: number; // Max retry attempts (default: 5)
baseDelay?: number; // Base delay in ms (default: 1000)
maxDelay?: number; // Max delay in ms (default: 30000)
jitter?: number; // Random jitter in ms (default: 500)
}
```
### Other Methods
- `BgUpload.cancel(taskId)`: Cancel upload
- `BgUpload.pause(taskId)`: Pause upload
- `BgUpload.resume(taskId)`: Resume upload
- `BgUpload.getPending()`: Get all pending uploads
- `BgUpload.addListener(event, callback)`: Add event listener
## Security
### Credential Refresh
```typescript
BgUpload.start({
id: 'secure-upload',
url: 'https://api.example.com/upload',
path: filePath,
onCredentialRefresh: async () => {
// Refresh your auth token
const newToken = await refreshAuthToken();
return {
Authorization: `Bearer ${newToken}`,
};
},
});
```
### Best Practices
- Use short-lived signed URLs (S3, Azure)
- Implement `onCredentialRefresh` for token rotation
- Don't store tokens in upload options (use refresh hook)
- Use HTTPS only
- Don't hardcode credentials
## Testing
### Running Tests
```bash
yarn test # Unit tests
yarn test:integration # Integration tests (requires mock server)
```
### Example Test Scenarios
- Large file (1GB+) with chunking
- App kill during upload → resume
- Network offline/online toggle
- Retry on server 500 errors
- Notification cancel action (Android)
See [IMPLEMENTATION_NOTES.md](./IMPLEMENTATION_NOTES.md) for server-side contract.
## Implementation Notes
### Android
- Uses `WorkManager` for reliable background execution
- Foreground Service with notification during active uploads
- Persists task state to survive process death
- Chunks stored with offset tracking for resume
### iOS
- Uses `URL Session` background configuration
- OS handles upload continuation when app is killed
- Delegate callbacks for progress/completion
- Task state synced via `UserDefaults`
### Storage
- **Queue**: MMKV for instant read/write
- **Tasks**: Serialized JSON with chunk metadata
- **Credentials**: Never persisted (use refresh hook)
## Contributing
See [CONTRIBUTING.md](./CONTRIBUTING.md)
## License
MIT © 2025
## Links
- [API Documentation](./docs)
- [Security Guide](./SECURITY.md)
- [Changelog](./CHANGELOG.md)