react-native-cloud-storage

React Native Cloud Storage provides a developer-friendly API for using iCloud (iOS only) and Google Drive as file and data storage in React Native applications. The API is modeled after Node's fs and AsyncStorage to minimize the learning curve.

Core Capabilities

• File Storage: Use an fs-like API including readFile, writeFile, appendFile, readdir, mkdir, stat, and unlink.
• Key-Value Storage: Save preferences and small app states using native iCloud key-value storage or an emulated Google Drive store.
• Unified API: Use the same methods regardless of the provider (iCloud or Google Drive).
• Scopes: Choose between AppData (hidden, app-private container) or Documents (user-visible folder).
• React Hooks: Access reactive values for files, key-value state, and provider availability using useCloudFile, useCloudKV, and useIsCloudAvailable.
• Modern Architecture: Built as a Turbo Module and fully typed with TypeScript.

You can listen for changes made to the cloud store from other devices using subscribeToExternalChanges.

• iCloud: Uses native push events.
• Google Drive: Does not support push. Instead, you must enable polling by setting kvPollInterval in setProviderOptions. Polling starts when the first listener subscribes and stops when the last one unsubscribes.

If changedKeys is empty, it indicates a general change (like an iCloud account change) and you should refresh all relevant values.

import { CloudKVStorage } from 'react-native-cloud-storage';

// Enable polling for Google Drive
CloudKVStorage.setProviderOptions({ kvPollInterval: 15_000 });

const handleChange = async (event: { changedKeys: string[] }) => {
  if (event.changedKeys.length === 0 || event.changedKeys.includes('theme')) {
    console.log('New theme:', await CloudKVStorage.getItem('theme'));
  }
};

CloudKVStorage.subscribeToExternalChanges(handleChange);

// To stop listening:
// CloudKVStorage.unsubscribeFromExternalChanges(handleChange);

This example demonstrates how to check for cloud availability using the useIsCloudAvailable hook, configure Google Drive with an access token, and perform basic file operations using the CloudStorage imperative API.

Note: For Google Drive, you must obtain an access token using a library like @react-native-google-signin/google-signin before calling CloudStorage.setProviderOptions.

import React from 'react';
import { Platform, View, Text, Button } from 'react-native';
import { CloudStorage, CloudStorageProvider, useIsCloudAvailable } from 'react-native-cloud-storage';

const App = () => {
  const cloudAvailable = useIsCloudAvailable();

  React.useEffect(() => {
    if (CloudStorage.getProvider() === CloudStorageProvider.GoogleDrive) {
      // get access token via @react-native-google-signin/google-signin or similar
      CloudStorage.setProviderOptions({ accessToken: 'some-access-token' });
    }
  }, []);

  const writeToCloud = async () => {
    await CloudStorage.writeFile('/file.txt', 'Hello, world!');
    console.log('Successfully wrote file to cloud');
  };

  const readFromCloud = async () => {
    const value = await CloudStorage.readFile('/file.txt');
    console.log('Successfully read file from cloud:', value);
  };

  return (
    <View>
      {cloudAvailable ? (
        <>
          <Button onPress={writeToCloud} title="Write to Cloud" />
          <Button onPress={readFromCloud} title="Read from Cloud" />
        </>
      ) : (
        <Text>The cloud storage is not available. Are you logged in?</Text>
      )}
    </View>
  );
};

To use multiple providers (e.g., backing up to both iCloud and Google Drive at the same time), do not rely on the static default instance. Instead, instantiate new CloudStorage objects by passing the desired CloudStorageProvider to the constructor.

Note: When instantiating a provider that is not native to the current platform (e.g., using CloudStorageProvider.ICloud on Android), the operation will throw an error.

import { CloudStorageProvider, CloudStorage } from 'react-native-cloud-storage';

// Create specific instances for different providers
const iCloudStorage = new CloudStorage(CloudStorageProvider.ICloud);
const googleDriveStorage = new CloudStorage(CloudStorageProvider.GoogleDrive, { accessToken: 'some_access_token' });

// Use the instances independently
await iCloudStorage.writeFile('/test.txt', 'Hello, iCloud!');
await googleDriveStorage.writeFile('/test.txt', 'Hello, Google Drive!');

To use react-native-cloud-storage in an Expo Managed project, follow these steps:

1. Install the package using your preferred package manager:

   npm install react-native-cloud-storage
   # or
   yarn add react-native-cloud-storage

2. Configure the Expo Config Plugin: Since the library contains native code, you must add it to the plugins array in your app.json to automate native project modifications.

3. Use a Development Client: This library is not compatible with Expo Go. You must create and use a development build to run the application.

4. Architecture Requirement: Newer versions of this library require the React Native New Architecture. If you are using the Legacy Architecture, you must either migrate to the New Architecture or install version 2 of the library using npm install react-native-cloud-storage@^2.

After installing the library and pods, you must configure the iCloud capability in Xcode to allow document access:

1. Open your Xcode workspace.
2. Select your main project target and navigate to the Signing & Capabilities tab.
3. Click the + Capability button and add iCloud.
4. In the iCloud section, under Services, enable iCloud Documents.
5. Create a new container named iCloud.{bundle_identifier}, replacing {bundle_identifier} with your project's actual bundle identifier.

If you are using CloudKVStorage, you must also enable Key-value storage in the iCloud capability section. Ensure your target includes the following entitlement:

com.apple.developer.ubiquity-kvstore-identifier

Warning: Your Apple App ID and provisioning profile must support iCloud key-value storage. If the entitlement is missing, local operations might work, but data will not synchronize across devices.