@serebano/capacitor-plugin-icloud-kv

Capacitor 7 plugin for syncing simple key‑value preferences across iCloud on iOS.

Install

npm install @serebano/capacitor-plugin-icloud-kv
npx cap sync

⚙️ iOS Setup

Enable iCloud + Key-Value Storage in Xcode:

1. Open ios/App.xcworkspace.
2. Select your app target → Signing & Capabilities.
3. Add iCloud capability and check Key‑Value Storage.

📦 Usage

import { ICloudKV } from '@serebano/capacitor-plugin-icloud-kv';

ICloudKV.addListener('icloudKVDidChange', data => {
  console.log('Synced keys:', data.keys, 'reason:', data.reason);
});

await ICloudKV.set({ key: 'theme', value: 'dark' });
const result = await ICloudKV.get({ key: 'theme' });
console.log('Theme:', result.value);

API

• echo(...)
• set(...)
• get(...)
• remove(...)
• addListener('icloudKVDidChange', ...)
• Interfaces
• Type Aliases
• Enums

echo(...)

echo(options: { value: string; }) => Promise<{ value: string; }>

| Param | Type | | ------------- | ------------------------------- | | options | { value: string; } |

Returns: Promise<{ value: string; }>

set(...)

set(options: { key: string; value: ICloudKVValue; }) => Promise<void>

| Param | Type | | ------------- | -------------------------------------------------------------------------------- | | options | { key: string; value: ICloudKVValue; } |

get(...)

get(options: { key: string; }) => Promise<{ value?: ICloudKVValue; }>

| Param | Type | | ------------- | ----------------------------- | | options | { key: string; } |

Returns: Promise<{ value?: ICloudKVValue; }>

remove(...)

remove(options: { key: string; }) => Promise<void>

| Param | Type | | ------------- | ----------------------------- | | options | { key: string; } |

addListener('icloudKVDidChange', ...)

addListener(eventName: 'icloudKVDidChange', listenerFunc: (data: { reason: ICloudKVSyncReason; keys: string[]; }) => void) => Promise<PluginListenerHandle>

| Param | Type | | ------------------ | ----------------------------------------------------------------------------------------------------------------- | | eventName | 'icloudKVDidChange' | | listenerFunc | (data: { reason: ICloudKVSyncReason; keys: string[]; }) => void |

Returns: Promise<PluginListenerHandle>

Interfaces

Date

Enables basic storage and retrieval of dates and times.

| Method | Signature | Description | | ---------------------- | ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- | | toString | () => string | Returns a string representation of a date. The format of the string depends on the locale. | | toDateString | () => string | Returns a date as a string value. | | toTimeString | () => string | Returns a time as a string value. | | toLocaleString | () => string | Returns a value as a string value appropriate to the host environment's current locale. | | toLocaleDateString | () => string | Returns a date as a string value appropriate to the host environment's current locale. | | toLocaleTimeString | () => string | Returns a time as a string value appropriate to the host environment's current locale. | | valueOf | () => number | Returns the stored time value in milliseconds since midnight, January 1, 1970 UTC. | | getTime | () => number | Gets the time value in milliseconds. | | getFullYear | () => number | Gets the year, using local time. | | getUTCFullYear | () => number | Gets the year using Universal Coordinated Time (UTC). | | getMonth | () => number | Gets the month, using local time. | | getUTCMonth | () => number | Gets the month of a Date object using Universal Coordinated Time (UTC). | | getDate | () => number | Gets the day-of-the-month, using local time. | | getUTCDate | () => number | Gets the day-of-the-month, using Universal Coordinated Time (UTC). | | getDay | () => number | Gets the day of the week, using local time. | | getUTCDay | () => number | Gets the day of the week using Universal Coordinated Time (UTC). | | getHours | () => number | Gets the hours in a date, using local time. | | getUTCHours | () => number | Gets the hours value in a Date object using Universal Coordinated Time (UTC). | | getMinutes | () => number | Gets the minutes of a Date object, using local time. | | getUTCMinutes | () => number | Gets the minutes of a Date object using Universal Coordinated Time (UTC). | | getSeconds | () => number | Gets the seconds of a Date object, using local time. | | getUTCSeconds | () => number | Gets the seconds of a Date object using Universal Coordinated Time (UTC). | | getMilliseconds | () => number | Gets the milliseconds of a Date, using local time. | | getUTCMilliseconds | () => number | Gets the milliseconds of a Date object using Universal Coordinated Time (UTC). | | getTimezoneOffset | () => number | Gets the difference in minutes between the time on the local computer and Universal Coordinated Time (UTC). | | setTime | (time: number) => number | Sets the date and time value in the Date object. | | setMilliseconds | (ms: number) => number | Sets the milliseconds value in the Date object using local time. | | setUTCMilliseconds | (ms: number) => number | Sets the milliseconds value in the Date object using Universal Coordinated Time (UTC). | | setSeconds | (sec: number, ms?: number | undefined) => number | Sets the seconds value in the Date object using local time. | | setUTCSeconds | (sec: number, ms?: number | undefined) => number | Sets the seconds value in the Date object using Universal Coordinated Time (UTC). | | setMinutes | (min: number, sec?: number | undefined, ms?: number | undefined) => number | Sets the minutes value in the Date object using local time. | | setUTCMinutes | (min: number, sec?: number | undefined, ms?: number | undefined) => number | Sets the minutes value in the Date object using Universal Coordinated Time (UTC). | | setHours | (hours: number, min?: number | undefined, sec?: number | undefined, ms?: number | undefined) => number | Sets the hour value in the Date object using local time. | | setUTCHours | (hours: number, min?: number | undefined, sec?: number | undefined, ms?: number | undefined) => number | Sets the hours value in the Date object using Universal Coordinated Time (UTC). | | setDate | (date: number) => number | Sets the numeric day-of-the-month value of the Date object using local time. | | setUTCDate | (date: number) => number | Sets the numeric day of the month in the Date object using Universal Coordinated Time (UTC). | | setMonth | (month: number, date?: number | undefined) => number | Sets the month value in the Date object using local time. | | setUTCMonth | (month: number, date?: number | undefined) => number | Sets the month value in the Date object using Universal Coordinated Time (UTC). | | setFullYear | (year: number, month?: number | undefined, date?: number | undefined) => number | Sets the year of the Date object using local time. | | setUTCFullYear | (year: number, month?: number | undefined, date?: number | undefined) => number | Sets the year value in the Date object using Universal Coordinated Time (UTC). | | toUTCString | () => string | Returns a date converted to a string using Universal Coordinated Time (UTC). | | toISOString | () => string | Returns a date as a string value in ISO format. | | toJSON | (key?: any) => string | Used by the JSON.stringify method to enable the transformation of an object's data for JavaScript Object Notation (JSON) serialization. |

PluginListenerHandle

| Prop | Type | | ------------ | ----------------------------------------- | | remove | () => Promise<void> |

Type Aliases

ICloudKVValue

Supported data types for iCloud Key-Value storage These correspond to the types supported by NSUbiquitousKeyValueStore

string | number | boolean | Date | ICloudKVValue[] | { [key: string]: ICloudKVValue }

Enums

ICloudKVSyncReason

| Members | Value | Description | | ---------------------------- | -------------- | -------------------------------------- | | SERVER_CHANGE | 0 | Change came from iCloud | | INITIAL_SYNC_CHANGE | 1 | Initial sync occurred | | QUOTA_VIOLATION_CHANGE | 2 | Change removed due to quota violations | | ACCOUNT_CHANGE | 3 | iCloud account changed |