iOS: CloudStorageScope.Documents writes to local storage instead of iCloud Documents

[ColeMurray]

Description

When using CloudStorageScope.Documents on iOS, files are written to the app's local sandbox Documents folder instead of the iCloud Documents folder. This means files don't sync to iCloud and aren't visible in the Files app.

Expected Behavior

According to the documentation, CloudStorageScope.Documents should store data in "the user-visible root directory of the cloud storage" - which for iCloud should be the iCloud Documents folder visible in the Files app.

Actual Behavior

Files are written to /var/mobile/Containers/Data/Application/{UUID}/Documents/ (local sandbox) instead of the iCloud ubiquity container's Documents folder.

Root Cause

In ios/Utils/CloudKitUtils.swift, the documentsDirectory property uses the local Documents folder:

static var documentsDirectory: URL? {
    fileManager.urls(for: .documentDirectory, in: .userDomainMask).first
}

This should instead use the iCloud Documents folder:

static var documentsDirectory: URL? {
    fileManager.url(forUbiquityContainerIdentifier: nil)?.appendingPathComponent("Documents")
}

Note that appDataDirectory correctly uses the ubiquity container:

static var appDataDirectory: URL? {
    fileManager.url(forUbiquityContainerIdentifier: nil)
}

Environment

• Library version: 2.3.0
• iOS version: 17.x
• React Native: 0.81.5
• Expo: 54

Workaround

Apply a patch to CloudKitUtils.swift to fix the documentsDirectory property.

[l1shu]

met the same problem, could you review and approve this PR? @mfkrause appreciate!