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

Falaq — Wed, 01 Jul 2026 20:20:14 +0000

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

What I learned building offline AI for Android

Falaq — Mon, 29 Jun 2026 19:47:35 +0000

I built Orb because I wanted AI on my phone that still worked when the network disappeared.

Most AI apps are simple from the app side: send the prompt to a server, stream the response back, and keep the real complexity in the cloud. Orb is the opposite. It runs local models on Android after a one-time model download, so the app has to deal with the annoying mobile parts directly.

A few things stood out.

The model download is part of the product

If your app needs a 1-3 GB model before it becomes useful, the download flow is not plumbing. It is onboarding.

Users need to know:

why the file is large
whether they need Wi-Fi only for setup
if the download can resume
how much storage it will use
what works offline after that

This is also why I pulled part of the download work into a React Native native module. Large model files need progress, resume, and background-friendly behavior. A normal "just fetch it" flow is not enough.

Offline has to be obvious

A privacy app cannot just say "local-first" and hope people believe it.

The product has to make the boundary clear:

no account
no cloud chat backend
no subscription
no ads
works without Wi-Fi after setup

For Orb, the point is simple: once the model is downloaded, chat, image/document workflows, speech-to-text, text-to-speech, and local reasoning should not require an internet connection.

Mobile inference is not one performance target

Android hardware is all over the place.

Some devices can use GPU acceleration. Some Snapdragon devices may have experimental NPU/HTP paths. Many devices need CPU fallback. The same model can feel completely different across phones.

So the app cannot be marketed like every phone gets the same experience. The honest version is: use the best local path available, fall back safely, and keep model choices realistic.

Privacy is a workflow, not a slogan

The strongest use cases are not "replace ChatGPT." They are moments where sending data to a remote service feels wrong or impossible:

private notes
personal documents
travel with no signal
journaling
studying offline
screenshots/photos you do not want uploaded

Local AI is weaker than cloud AI in many ways, but it wins when the private/offline boundary matters.

Orb

Orb is my attempt at making this feel normal on Android: local models on-device, image and document upload, speech-to-text, text-to-speech, no account, no subscription, no ads, and no cloud chat backend.

It is Google Play only for now:
https://play.google.com/store/apps/details?id=com.falaq.orb

DEV Community: Falaq