react-native-client

A high-performance native HTTP client for React Native, built with Nitro Modules.

Features

• File download
  • Native performance — Uses URLSession on iOS and OkHttp on Android
  • Resumable downloads — Pause and resume downloads with HTTP Range requests
  • Background downloads — Continue downloading while the app is in the background
  • Progress tracking — Real-time onProgress and begin callbacks
  • Configurable timeouts — Set connection and read timeouts independently

Installation

npm install react-native-client react-native-nitro-modules
# or
yarn add react-native-client react-native-nitro-modules
# or
bun add react-native-client react-native-nitro-modules

iOS

cd ios && pod install

Android

No additional steps required — Gradle handles everything automatically.

Usage

Basic download

import { downloadFile, documentDirectoryPath } from 'react-native-client'

const result = await downloadFile({
  fromUrl: 'https://example.com/file.zip',
  toFile: `${documentDirectoryPath}/file.zip`,
})

console.log(`Status: ${result.statusCode}, Bytes: ${result.bytesWritten}`)

Download with progress

import { downloadFile, documentDirectoryPath } from 'react-native-client'

const result = await downloadFile({
  fromUrl: 'https://example.com/large-file.zip',
  toFile: `${documentDirectoryPath}/large-file.zip`,
  begin: (statusCode, contentLength) => {
    console.log(`Download started — ${contentLength} bytes`)
  },
  onProgress: (bytesWritten, contentLength) => {
    const percent = ((bytesWritten / contentLength) * 100).toFixed(1)
    console.log(`${percent}%`)
  },
})

Resumable background download

import { downloadFile, documentDirectoryPath } from 'react-native-client'

const result = await downloadFile({
  fromUrl: 'https://example.com/large-file.zip',
  toFile: `${documentDirectoryPath}/large-file.zip`,
  resumable: true,
  background: true,
  connectionTimeout: 30000,
  readTimeout: 30000,
  onProgress: (bytesWritten, contentLength) => {
    console.log(`${bytesWritten} / ${contentLength}`)
  },
})

API

downloadFile(config: DownloadConfig): Promise<DownloadResult>

Downloads a file from a remote URL to a local path.

documentDirectoryPath: string

The app's document directory path, useful as a base path for toFile.

DownloadConfig

| Property | Type | Required | Description | |---|---|---|---| | fromUrl | string | Yes | URL to download from | | toFile | string | Yes | Local file path to save to | | resumable | boolean | No | Enable resumable downloads via HTTP Range | | background | boolean | No | Continue download in the background | | discretionary | boolean | No | iOS only — marks the transfer as discretionary | | progressDivider | number | No | Controls progress callback frequency | | connectionTimeout | number | No | Connection timeout in milliseconds | | readTimeout | number | No | Read timeout in milliseconds | | onProgress | (bytesWritten, contentLength) => void | No | Called periodically with download progress | | begin | (statusCode, contentLength) => void | No | Called when the download begins |

DownloadResult

| Property | Type | Description | |---|---|---| | statusCode | number | HTTP status code (200, 206, etc.) | | bytesWritten | number | Total bytes written to disk |

Contributing

Contributions are welcome! This library is actively growing and we appreciate help from the community.

Getting Started

1. Fork the repository
2. Clone your fork:

   git clone https://github.com/<your-username>/react-native-client.git

3. Install dependencies:

   bun install

4. Create a branch for your changes:

   git checkout -b feat/my-feature

Development

# Type check
bun run typecheck

# Lint
bun run lint

# Regenerate Nitro specs after changing .nitro.ts files
bun run specs

# Regenerate nitrogen bindings after changing Client.nitro.ts
bunx nitrogen

License

This project is licensed under the MIT License - see the LICENSE file for details.