react-native-better-qiniu

A React Native Turbo Module for Qiniu Cloud Kodo object storage, using the latest native SDKs for high-performance uploads.

This library provides a modern, promise-based API for uploading files from your React Native application to Qiniu's object storage, with support for progress tracking, cancellation, and resumable uploads.

---

Installation

npm install react-native-better-qiniu
# --- or ---
yarn add react-native-better-qiniu
# --- or ---
pnpm add react-native-better-qiniu

After installing the package, you need to install the native dependencies for iOS:

cd ios && pod install

Usage

Here is a basic example of how to initialize the client and upload a file with the task API.

import { Qiniu, QiniuUploadError } from 'react-native-better-qiniu';

const qiniu = Qiniu.shared({
  zone: 'auto', // Automatically select the best upload zone
  useConcurrentResumeUpload: true,
  putThreshold: 4 * 1024 * 1024, // Use resumable upload for files larger than 4MB
  tokenProvider: async ({ key }) => {
    // Fetch an upload token from your server. Never generate tokens in the app.
    const response = await fetch(`/upload-token?key=${encodeURIComponent(key)}`);
    const { token } = await response.json();
    return token;
  },
});

let activeTask = null;

const handleUpload = async () => {
  const task = qiniu.createUploadTask({
    filePath: '/path/to/your/local/file.jpg', // A direct, URI-decoded file path
    key: `uploads/image-${Date.now()}.jpg`,
  });
  activeTask = task;

  const subscription = task.onProgress((event) => {
    const percent = Math.round(event.percent * 100);
    console.log(`Upload Progress: ${percent}%`);
  });

  try {
    const result = await task.start();
    console.log('Upload successful!', result.hash, result.raw);
  } catch (error) {
    if (error instanceof QiniuUploadError && error.isCancelled) {
      console.log('Upload cancelled');
    } else {
      console.error('Upload failed.', error);
    }
  } finally {
    subscription.remove();
    activeTask = null;
  }
};

const handleCancel = () => {
  activeTask?.cancel();
};

Example

NPM package does not include the example app. If you need it, please clone the GitHub repository and run the example app from there.

Under the example directory, you can find a complete React Native application that demonstrates how to use this library. It includes:

• A simple UI for selecting a file and uploading it to Qiniu.
• Progress tracking and cancellation functionality.

To run the example app, please follow the instructions in example/README.md.

---

API Reference

Qiniu.shared(config: QiniuConfig)

Creates a JS client and reuses a cached native upload manager for identical native configuration.

Qiniu.create(config: QiniuConfig)

Creates a JS client with a new native upload manager, even when the native configuration matches an existing shared instance.

new Qiniu(config: QiniuConfig)

Deprecated compatibility constructor. Prefer Qiniu.shared(config) or Qiniu.create(config) so lifecycle intent is explicit.

QiniuConfig (Interface)

Property	Type	Description
zone	'auto' | ZoneRegionId | ZoneCustomDomains | ZoneCustomUcServers	The upload zone configuration.
putThreshold	number	The file size threshold in bytes for triggering resumable (chunked) upload.
useConcurrentResumeUpload	boolean	Enables concurrent uploading of multiple chunks for faster resumable uploads.
resumeUploadVersion	'v1' | 'v2'	Specifies the version of the resumable upload protocol.
useHttps	boolean	Whether to use HTTPS for uploads.
tokenProvider	(input) => string | Promise<string>	Returns an upload token for a task when the task options do not include token.
advanced	QiniuAdvancedConfig	Less common SDK-builder options.

Legacy top-level advanced fields such as chunkSize, retryMax, and timeoutInterval are still accepted but deprecated. When both are present, advanced wins.

QiniuAdvancedConfig (Interface)

Property	Type	Description
accelerateUploading	boolean	Enables global acceleration. Requires server-side and bucket configuration.
chunkSize	number	The size of each chunk in bytes for resumable uploads.
retryMax	number	The maximum number of times to retry a failed chunk.
retryInterval	number	Retry interval in seconds.
timeoutInterval	number	Network timeout in seconds for each request.
allowBackupHost	boolean	Allows backup upload hosts.
concurrentTaskCount	number	Concurrent task count for multipart upload.

qiniu.createUploadTask(options: UploadOptions)

Creates an upload task without starting it.

UploadTask

Member	Type	Description
uploadId	string	Local task identifier. Generated automatically when omitted.
key	string	The Qiniu object key.
status	'idle' | 'uploading' | 'success' | 'error' | 'cancelled'	Current task status.
onProgress(listener)	() => { remove(): void }	Subscribes to progress for this task.
start()	() => Promise<UploadResult>	Starts the upload. Calling it more than once returns the same promise.
cancel()	() => void	Cancels this task.

qiniu.upload(options: UploadOptions)

Deprecated compatibility wrapper. It creates a task internally and resolves with UploadResult.raw so existing callers continue receiving the raw JSON string.

UploadOptions (Interface)

Property	Type	Required	Description
uploadId	string	No	A local identifier for this upload task. Generated automatically when omitted.
filePath	string	Yes	The absolute local file path. Note: Must be a raw path, not a file:// URI. Decode URI-encoded paths before passing.
key	string	Yes	The destination key (filename) for the file in your Qiniu bucket.
token	string	No	A valid upload token. Overrides QiniuConfig.tokenProvider when present.
onProgress	(event: UploadProgressEvent) => void	No	Compatibility progress callback. Prefer task.onProgress().

qiniu.cancel(uploadId: string)

Deprecated compatibility wrapper. Prefer UploadTask.cancel().

qiniu.destroy()

Decrements the reference count for the native instance. When all JS instances sharing the same configuration are destroyed, the underlying native instance is removed to free up resources.

UploadResult (Interface)

Property	Type	Description
uploadId	string	Local task identifier.
key	string	The Qiniu object key.
statusCode	number	Native SDK status code.
requestId	string	Qiniu request ID when available.
host	string	Upload host when available.
hash	string	Parsed hash from the Qiniu response when available.
fsize	number	Parsed fsize from the Qiniu response when available.
bucket	string	Parsed bucket from the Qiniu response when available.
response	object	Parsed response body.
raw	string	Raw JSON response string.

QiniuUploadError

Property	Type	Description
code	string	TOKEN_MISSING, UPLOAD_ERROR, UPLOAD_CANCELLED, or a native error code.
message	string	Human-readable error message.
statusCode	number	Native SDK status code when available.
requestId	string	Qiniu request ID when available.
isCancelled	boolean	Whether the upload was cancelled.
raw	unknown	Raw native error metadata when available.

ZoneRegionId (Enum)

An enum of predefined zone IDs for different Qiniu regions.

ZoneCustomDomains & ZoneCustomUcServers (Classes)

Classes used to provide custom domains for fixed zones or custom UC servers for auto zones.

import { ZoneCustomDomains, ZoneCustomUcServers, Qiniu } from 'react-native-better-qiniu';

// Example for custom domains
const domainZone = new ZoneCustomDomains(['upload1.your-domain.com','upload2.your-domain.com']);
const qiniu1 = new Qiniu({ zone: domainZone });

// Example for custom UC servers
const ucZone = new ZoneCustomUcServers(['uc1.your-domain.com', 'uc2.your-domain.com']);
const qiniu2 = new Qiniu({ zone: ucZone });

UploadProgressEvent (Interface)

Property	Type	Description
uploadId	string	The local identifier of the upload task.
key	string	The key of the file being uploaded.
percent	number	The upload progress percentage (0 to 1).

Platform Capability Notes

The common config fields are intended to behave consistently on Android and iOS. advanced fields are passed through to the official native SDK builders; support depends on each SDK version. Global acceleration requires Qiniu server-side and bucket configuration on both platforms.

---

License

This project is licensed under the MIT License.

Acknowledgments

This library was built upon the work of Qiniu's official native SDKs and inspired by previous community libraries.

• Qiniu Android SDK
• Qiniu Objective-C SDK
• @react-native-hero/qiniu

---

Made with ❤️ by Zerlight using create-react-native-library