📄 Improve clerk_auth example and README – DefaultPersistor fails silently on mobile due to Directory.current.

[Turskyi]

Steps to reproduce

1. Clone the clerk-sdk-flutter repo
2. Open the packages/clerk_auth/example/ directory
3. Replace with a valid key in main.dart
4. Run the example on an iOS simulator or device (not on desktop)
5. Observe the crash when DefaultPersistor.create(storageDirectory: Directory.current) is called

Expected results

•	The example should run without throwing any unhandled exceptions
•	If Directory.current is not suitable for the platform, a helpful error should be shown
•	The README should warn developers that Directory.current does not work on iOS and suggest alternatives like path_provider

Actual results

•	The app is running, but throws:

FileSystemException: Cannot open file, path = '//clerk_sdk.json' (OS Error: Read-only file system, errno = 30)

•	No prior indication in the README that this code is not mobile-safe
•	The example misleads developers into thinking the setup works cross-platform

Code sample

From clerk_auth/example/main.dart:

Code sample

final auth = Auth(
  config: const AuthConfig(
    publishableKey: '<YOUR-PUBLISHABLE-KEY>',
  ),
  persistor: await DefaultPersistor.create(
    storageDirectory: Directory.current, // ← problematic on iOS
  ),
);

Screenshots or Video

No response

Logs

Logs

[ERROR:flutter/runtime/dart_vm_initializer.cc(40)] Unhandled Exception: FileSystemException: Cannot open file, path = '//clerk_sdk.json' (OS Error: Read-only file system, errno = 30)

Flutter Doctor output

Doctor output

[✓] Flutter (Channel stable, 3.29.2, on macOS 15.4.1 24E263 darwin-arm64, locale en-CA) [1,546ms]
    • Flutter version 3.29.2 on channel stable at /Users/dmytro/flutter
    • Upstream repository https://github.com/flutter/flutter.git
    • Framework revision c236373904 (7 weeks ago), 2025-03-13 16:17:06 -0400
    • Engine revision 18b71d647a
    • Dart version 3.7.2
    • DevTools version 2.42.3

[✓] Android toolchain - develop for Android devices (Android SDK version 35.0.0) [2.5s]
    • Android SDK at /Users/dmytro/Library/Android/sdk
    • Platform android-35, build-tools 35.0.0
    • ANDROID_SDK_ROOT = /Users/dmytro/Library/Android/sdk
    • Java binary at: /Applications/Android Studio.app/Contents/jbr/Contents/Home/bin/java
      This is the JDK bundled with the latest Android Studio installation on this machine.
      To manually set the JDK path, use: `flutter config --jdk-dir="path/to/jdk"`.
    • Java version OpenJDK Runtime Environment (build 21.0.6+-13355223-b631.42)
    • All Android licenses accepted.

[✓] Xcode - develop for iOS and macOS (Xcode 16.3) [1,348ms]
    • Xcode at /Applications/Xcode.app/Contents/Developer
    • Build 16E140
    • CocoaPods version 1.16.2

[✓] Chrome - develop for the web [92ms]
    • Chrome at /Applications/Google Chrome.app/Contents/MacOS/Google Chrome

[✓] Android Studio (version 2024.3) [92ms]
    • Android Studio at /Applications/Android Studio.app/Contents
    • Flutter plugin can be installed from:
      🔨 https://plugins.jetbrains.com/plugin/9212-flutter
    • Dart plugin can be installed from:
      🔨 https://plugins.jetbrains.com/plugin/6351-dart
    • Java version OpenJDK Runtime Environment (build 21.0.6+-13355223-b631.42)

[✓] IntelliJ IDEA Community Edition (version 2025.1) [91ms]
    • IntelliJ at /Applications/IntelliJ IDEA CE.app
    • Flutter plugin version 85.2.4
    • Dart plugin version 251.25267.1

[✓] VS Code (version 1.99.3) [9ms]
    • VS Code at /Applications/Visual Studio Code.app/Contents
    • Flutter extension version 3.108.0

[✓] Connected device (5 available) [6.4s]
    • iPad (wireless) (mobile) • 00008020-001E6D690168402E            • ios            • iOS 18.3.2 22D82
    • iPhone 16 Pro Max (mobile)                     • DB8962E0-74F5-4EF5-88B8-991A0E9AB40E • ios            •
      com.apple.CoreSimulator.SimRuntime.iOS-18-4 (simulator)
    • macOS (desktop)                                • macos                                • darwin-arm64   • macOS 15.4.1 24E263
      darwin-arm64
    • Mac Designed for iPad (desktop)                • mac-designed-for-ipad                • darwin         • macOS 15.4.1 24E263
      darwin-arm64
    • Chrome (web)                                   • chrome                               • web-javascript • Google Chrome
      135.0.7049.115

[✓] Network resources [370ms]
    • All expected network resources are available.

• No issues found!

[slightfoot]

This is correct in our expectation at this time. The example is an example of use.

We cannot provide an example for mobile for the non-mobile sdk. This would make clerk_auth depend on Flutter which is not the case. In the example as you have noticed you could replace the Directory with any directory of your choice. In Flutter you would use path_provider to get the mobile directory.

You can always replace it with Persistor.none. Perhaps we can show that as an alternative, but the idea of the example is to show how you can save and persist your local SDK state.