Chilkat for React Native and Expo — the @chilkat/react-native package

Add to your project

npm install @chilkat/react-native react-native-nitro-modules

# bare React Native:
cd ios && pod install

# Expo (a development build or EAS Build; Expo Go cannot load native modules):
npx expo prebuild

Then build and run as usual (npx react-native run-ios / run-android, npx expo run:ios / run:android, or an EAS build). The package contains only TypeScript and C++ sources; the Chilkat native library is fetched by the native build. On iOS, pod install downloads chilkat-rn-ios.tar.gz; on Android, the Gradle build downloads chilkat-rn-android.tar.gz — both for the exact package version, from https://chilkatdownload.com/<version>/. Each archive's SHA-256 is checked against the table shipped in the package (chilkat-checksums.json) before it is unpacked under node_modules/@chilkat/react-native/native/. A verified copy is reused by later builds, so the download happens once per Chilkat version per platform.

Quick start

import { Chilkat, Http, JsonObject } from '@chilkat/react-native'

// Any string unlocks the fully functional 30-day trial. Call once per app start.
Chilkat.unlockBundle('Anything for 30-day trial')

async function stars(): Promise<number> {
  const http = new Http()
  http.connectTimeout = 30
  http.setRequestHeader('Accept', 'application/json')

  try {
    // The ...Async form runs on a native worker thread, so the UI keeps rendering.
    const body = await http.quickGetStrAsync('https://api.github.com/repos/facebook/react-native')
    const json = new JsonObject()
    json.load(body)
    return json.intOf('stargazers_count')
  } catch (e) {
    console.log((e as Error).message)   // Http.quickGetStrAsync: <reason>
    console.log(http.lastErrorText)     // the full Chilkat log of the failed call
    throw e
  }
}

A method that can fail throws a plain Error instead of returning a status (a ...Async method rejects its promise with the same error). The error's message names the class, the method and the reason; the object's lastErrorText holds the full Chilkat log of the failed call. Objects release their native resources when garbage collected; call dispose() to release them immediately (a large BinData, an open socket).

Supported targets

A prebuilt Chilkat library is published for each platform with every Chilkat release. The archive is what the native build downloads.

The archives are downloaded for the platform being built (iOS on a Mac running pod install; Android wherever Gradle runs, including Windows and Linux). React Native for macOS or Windows and react-native-web are not targets of this package; if you need one of them, contact Chilkat support.

Async, progress and cancellation

Every method has a synchronous form, which blocks the JavaScript thread until Chilkat returns. Quick operations (JSON, XML, hashing, encoding) are fine that way. Every method that can take a while (network, files, compression, key generation) also has an ...Async form returning a Promise: the same call on a native worker thread, settling on the JavaScript thread. Use those from UI code:

const body = await http.quickGetStrAsync(url)      // instead of http.quickGetStr(url)

While an async call is pending, every other call on that object throws (the object is busy); other objects are unaffected, so several downloads can run concurrently on several Http objects. Two things are allowed on a busy object: abort(), which cancels the pending call (its promise then rejects), and assigning the progress callbacks.

The event-capable classes (Http, Ftp2, SFtp, Zip, Imap, …) have onPercentDone and onProgressInfo callback properties. They are delivered on the JavaScript thread, so they can update React state directly — and for the same reason they are useful with the ...Async methods (during a synchronous call the JavaScript thread is busy inside Chilkat). There is no AbortCheck callback: to cancel, call abort(), which Chilkat notices at its next progress check, at least every heartbeatMs milliseconds on the classes that have that property.

const ftp = new Ftp2()
ftp.hostname = host; ftp.username = user; ftp.password = pw
ftp.heartbeatMs = 250                                  // let abort() take effect within a quarter second
ftp.onPercentDone = (pct) => setProgress(pct)          // 0..100, on the JS thread
cancelButton.onPress = () => ftp.abort()

await ftp.connectAsync()
await ftp.getFileAsync('remote.dat', localPath)

The Task and TaskChain classes of other Chilkat products are not part of this package; the ...Async methods use the same Async names but return a JavaScript Promise.

Offline builds, vendoring, and your own Chilkat library

Build machines without internet access, or that must not download during a build, point the fetch script at a local directory instead. Either set the environment variable CHILKAT_RN_LIB_DIR for the shell that runs pod install or Gradle (on EAS Build, an environment variable or build secret), or add the setting to the application's package.json:

{
  "chilkat": { "libDir": "./vendor/chilkat" }     // a relative path resolves against this package.json
}

The directory holds either the archives themselves (chilkat-rn-ios.tar.gz, chilkat-rn-android.tar.gz, verified against the package's checksum table) or their unpacked contents (ios/Chilkat.xcframework, ios/include, android/<abi>/libchilkat.a, android/include). With the setting present, nothing is downloaded. To populate that directory, download the archives once from a connected machine — the URLs are

https://chilkatdownload.com/<version>/chilkat-rn-ios.tar.gz
https://chilkatdownload.com/<version>/chilkat-rn-android.tar.gz

# for example, for @chilkat/react-native 11.6.1:
https://chilkatdownload.com/11.6.1/chilkat-rn-android.tar.gz

where <version> is the exact version of @chilkat/react-native you depend on (the package version equals the Chilkat version). Each archive contains the library and headers, license.pdf, a software bill of materials, and a VERSION file. The SHA-256 of both archives is listed in chilkat-checksums.json inside the package of the same version; a checksum mismatch fails the build rather than linking an unverified library.

The unpacked-directory form is also the way to build against your own build of the Chilkat C++ library: put its static library and headers in that layout and point libDir at it.

How the Chilkat API maps to TypeScript

The reference documentation shows the exact TypeScript signature of every member, and the same text is in the package's type declarations, so your editor shows it as you type.

Licensing

This is the full-version Chilkat product. Chilkat libraries are fully functional for a 30-day evaluation; passing any non-empty string to Chilkat.unlockBundle starts the trial, and a purchased unlock code removes the time limit. The license terms are in the LICENSE file of the package (and license.pdf in both native archives). For questions, see the reference documentation or contact Chilkat support.