I built a native React Native downloader because AI models are huge

I ran into this while building Orb, a private offline AI app for Android.

Orb runs local models on the phone. That is great for privacy, but it creates a very practical mobile problem: the app has to download model files that can be multiple gigabytes. If the network drops, the app backgrounds, or the user force-closes the app, restarting from zero is a terrible experience.

So I pulled the downloader out into a small open-source package:

GitHub: https://github.com/zraisan/react-native-client

NPM: https://www.npmjs.com/package/react-native-client

react-native-client is a native HTTP client for React Native apps that need direct-to-file downloads without moving bytes through the JavaScript bridge. The first stable API is focused on downloads, not general HTTP requests.

What it does

The package exposes a typed downloadFile API through Nitro Modules.

Under the hood:

• Android uses OkHttp
• iOS uses URLSession
• files are streamed directly to disk on the native side
• progress callbacks report bytes written and total length
• resumable downloads use HTTP Range requests
• partial-file resume validates Content-Range before appending
• Android background mode uses a foreground service
• iOS uses a background URLSession path

The main use case is large files: AI models, media packs, offline datasets, cache warmups, and anything else where a failed 2GB download should not mean starting over.

Basic usage

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

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

console.log(result.statusCode, result.bytesWritten)

With progress:

await downloadFile({
  fromUrl: 'https://example.com/large-file.bin',
  toFile: `${documentDirectoryPath}/large-file.bin`,
  begin: (statusCode, contentLength) => {
    console.log('started', statusCode, contentLength)
  },
  onProgress: (bytesWritten, contentLength) => {
    if (contentLength > 0) {
      console.log(`${Math.round((bytesWritten / contentLength) * 100)}%`)
    }
  },
})

Resumable background download:

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

To resume after app relaunch, call the same request again with the same toFile and resumable: true. If the partial file is still there, the native client requests only the missing range.

const modelPath = `${documentDirectoryPath}/model.gguf`

await downloadFile({
  fromUrl: modelUrl,
  toFile: modelPath,
  resumable: true,
  background: true,
})

Why not just fetch?

For small files, normal app-level download logic is fine.

For Orb, the files are not small. A local AI model download needs to survive boring real-world mobile behavior: bad Wi-Fi, app backgrounding, retries, foreground service expectations on Android, and users reopening the app later.

I wanted the heavy transfer to stay native:

• no file bytes crossing the JS bridge
• native networking behavior on each platform
• progress events for the UI
• partial-file recovery when the server supports Range
• safe restart when resume metadata is wrong or unsupported

The package is not trying to be a full download manager yet. It does not currently expose task IDs, cancellation, a persistent queue, checksums, uploads, or a general request/response client. The current goal is narrower: make large direct-to-file downloads reliable enough to build real product flows around them.

Install

npm install react-native-client react-native-nitro-modules

yarn add react-native-client react-native-nitro-modules

bun add react-native-client react-native-nitro-modules

For iOS:

cd ios
pod install

Android should work through normal React Native autolinking.

Current status

The package is early, but usable for the download flow it was built for.

Current version: 0.0.3

Requirements:

• React Native app
• react-native-nitro-modules >=0.35.0 <0.36.0
• Android and/or iOS native builds

The README has a demo showing Android resume behavior: start a native background download, send the app home, return to the transfer, force-stop the app, relaunch, and resume from the partial file.

Why I’m releasing it

Orb needed this because private offline AI has a surprisingly unglamorous bottleneck: getting the model onto the device cleanly. The AI part gets the attention, but the first user experience is often just a large download that must not fail in a stupid way.

If you are building a React Native app that downloads big files, I’d love feedback on the API before it grows too much.

The next useful pieces are probably:

• task IDs and cancellation
• persistent background task registry
• request headers and response metadata
• checksum verification
• upload support
• broader HTTP APIs beyond file download

GitHub: https://github.com/zraisan/react-native-client

NPM: https://www.npmjs.com/package/react-native-client

Orb on Google Play: https://play.google.com/store/apps/details?id=com.falaq.orb