react-native-cloud-settings

Persist small key-value data securely and reliably across app installs and devices for React Native apps.

Supports:

• iOS: Uses iCloud Key-Value Store (syncs across devices, persists after uninstall)
• Android: Uses SharedPreferences (optionally supports backup/restore)

Installation

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

iOS Setup

1. Enable iCloud Key-Value Store:
   • In Xcode, open your app target → Signing & Capabilities.
   • Add the "iCloud" capability.
   • Check "Key-Value storage".
2. Rebuild your app.

Android Setup (File-based Backup)

To persist your data across uninstall/reinstall (if device backup is enabled), add the following to your app's AndroidManifest.xml inside the <application> tag:

<application
   android:allowBackup="true"
   android:backupAgent="com.cloudsettings.CloudSettingsBackupAgent"
   android:fullBackupOnly="false"
   android:fullBackupContent="@xml/backup_rules_lte_api_30"
   android:dataExtractionRules="@xml/backup_rules_gte_api_31"
/>

Then, add these files to your project:

android/app/src/main/res/xml/backup_rules_lte_api_30.xml (for API 30 and below):

<?xml version="1.0" encoding="utf-8"?>
<full-backup-content>
   <include domain="file" path="cloudsettings.json"/>
</full-backup-content>

android/app/src/main/res/xml/backup_rules_gte_api_31.xml (for API 31+):

<?xml version="1.0" encoding="utf-8"?>
<data-extraction-rules>
   <cloud-backup>
      <include domain="file" path="cloudsettings.json"/>
   </cloud-backup>
</data-extraction-rules>

Usage

import CloudSettings, {
  setItem,
  getItem,
  removeItem,
  clear,
} from 'react-native-cloud-settings';

// Set a value
await setItem('language', 'en');

// Get a value
const lang = await getItem('language');

// Remove a value
await removeItem('language');

// Clear all values
await clear();

API

All methods are asynchronous and return a Promise.

| Method | Description | | --------------------- | ------------------------------ | | setItem(key, value) | Store a string value for a key | | getItem(key) | Retrieve a string value by key | | removeItem(key) | Remove a value by key | | clear() | Remove all stored values |

Platform Details

iOS

• Uses iCloud Key-Value Store. Data syncs across devices signed into the same iCloud account and persists after uninstall/reinstall.
• Requires iCloud Key-Value Store entitlement (see setup above).

Android

• Uses a file (cloudsettings.json) for local storage, which is included in Android's backup system using a custom backup agent.
• To enable backup/restore, follow the Android setup above.

Contributing

• Development workflow
• Sending a pull request
• Code of conduct

License

MIT