Quick Start

This guide takes you from install to reading and writing your first cloud file. The default CloudStorage instance automatically uses iCloud on iOS and Google Drive everywhere else, so most of your code stays the same across platforms.

If you'd like to use the key-value store instead of storing files, see the key-value storage guide.

InstallCopy Anchor Link

npm install react-native-cloud-storage

Then complete the native setup for your platform:

• Expo managed project
• Bare React Native project
• Configure the Google Drive API — required whenever Google Drive is used (e.g. on Android)

Provide a Google Drive access tokenCopy Anchor Link

iCloud needs native configuration and a signed-in iCloud account on iOS, but no access token. Google Drive requires an access token that you obtain from the user with a library such as @react-native-google-signin/google-signin, then hand to the library:

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

if (CloudStorage.getProvider() === CloudStorageProvider.GoogleDrive) {
  CloudStorage.setProviderOptions({ accessToken: 'your_access_token' });
}

Read and write plain-text filesCopy Anchor Link

The core API mirrors Node's fs, so reading and writing is just writeFile / readFile:

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

// Write a file to the app-private scope.
await CloudStorage.writeFile('/user.json', JSON.stringify({ name: 'Ada' }), CloudStorageScope.AppData);

// Read it back.
if (await CloudStorage.exists('/user.json', CloudStorageScope.AppData)) {
  const json = await CloudStorage.readFile('/user.json', CloudStorageScope.AppData);
  const user = JSON.parse(json);
}

Read and write binary files and dataCopy Anchor Link

Binary data can be read and written using two different ways, based on the platform.

File-based binary supportCopy Anchor Link

On native platforms, you can directly download and upload files to and from the local filesystem:

await CloudStorage.downloadFile('/data.bin', '/local/data.bin', CloudStorageScope.AppData);

await CloudStorage.uploadFile(
  '/data.bin',
  '/local/data.bin',
  { mimeType: 'application/octet-stream' },
  CloudStorageScope.AppData
);

Lacking access to the user's local filesystem, this is not supported on Web and will throw when trying to use it on the Web.

Bytes-based binary supportCopy Anchor Link

On all supported platforms, you can alternatively supply and receive an Uint8Array to writeFile and from readFile:

await CloudStorage.writeFile('/data.bin', new Uint8Array([0, 128, 255]), {
  mimeType: 'application/octet-stream',
  scope: CloudStorageScope.AppData,
});

const bytes = await CloudStorage.readFile('/data.bin', {
  format: 'bytes',
  scope: CloudStorageScope.AppData,
});

This is also supported on the Web. The return type of readFile is determined by the format option (defaults to text). writeFile accepts both a string or a Uint8Array.

Use the React hookCopy Anchor Link

Inside components, useCloudFile reads a single file and gives you helpers to read, write, and remove it. It updates content after its own writes and removals. It does not subscribe to remote file changes or poll for them.

import { Button, Text, View } from 'react-native';
import { CloudStorageScope, useCloudFile } from 'react-native-cloud-storage';

function Profile() {
  const { content, write, remove } = useCloudFile('/user.json', CloudStorageScope.AppData);

  return (
    <View>
      <Text>{content ?? 'No profile saved yet'}</Text>
      <Button title="Save" onPress={() => write(JSON.stringify({ name: 'Ada' }))} />
      <Button title="Delete" onPress={remove} />
    </View>
  );
}

To react to whether the cloud is reachable at all (for example, iCloud right after launch or before the user signs in), use useIsCloudAvailable.

Next stepsCopy Anchor Link