# cross_file 0.4.0 An abstraction to allow working with files across multiple platforms. ## Installing ``` export PUB_HOSTED_URL=https://pub.mirror.p-hatan.com flutter pub add 'cross_file:0.4.0' ``` Published: 2026-09-24T15:21:42.778278Z Expected archive SHA-256: 3bde17bce71488fc4dc99216da1d990642a726472874dcce4db700eb103d3fa4 Available in cache; verification: upstream_checksum ## Direct dependencies - cross_file_android: ^1.0.0 - cross_file_darwin: ^1.0.0 - cross_file_io: ^1.0.0 - cross_file_platform_interface: ^1.0.0 - cross_file_web: ^1.0.0 - flutter: map[sdk:flutter] ## Package README (untrusted upstream documentation) # cross_file An abstraction to allow working with files across multiple platforms. [![pub package](https://img.shields.io/pub/v/cross_file.svg)](https://pub.dartlang.org/packages/cross_file) | | Android | iOS | Linux | macOS | Web | Windows | |-------------|---------|---------|-------|--------|-----|-------------| | **Support** | SDK 24+ | iOS 13+ | Any | 10.15+ | Any | Windows 10+ | ## Overview This package provides a unified API for interacting with resources across platforms through two primary implementation types: ### FileSystem The `FileSystem` implementation represents resources on a traditional file system. It is used when resources are identified by standard file paths or `file://` URIs. * **Classes**: `FileSystemXFile`, `FileSystemXDirectory`. * **Use Cases**: Desktop applications, app-private storage on mobile, or any environment where direct file system access is available. ### ScopedStorage The `ScopedStorage` implementation represents resources that are managed or restricted by the platform. These resources are typically identified by platform-specific URIs rather than direct paths. * **Classes**: `ScopedStorageXFile`, `ScopedStorageXDirectory`. * **Use Cases**: Android Content URIs, iOS Security-Scoped bookmarks, Web Object URLs, or Photo Library assets. * **Key Characteristic**: Access to these resources may be ephemeral or requires explicit lifecycle management (e.g., using `dispose()` or specific platform extensions). ## Usage Instantiate a `XFile` using a uri or path and use its methods and properties to access the file and its metadata. Example: ```dart final file = XFile.fileSystem(path: 'assets/hello.txt'); debugPrint('File information:'); debugPrint('- URI: ${file.uri}'); debugPrint('- Name: ${await file.name()}'); if (await file.exists()) { final String fileContent = await file.readAsString(); debugPrint('Content of the file: $fileContent'); } ``` You can find links to the API docs on the [pub page](https://pub.dev/documentation/cross_file/latest/). ### Implementation-Specific Features Classes in this package contain an underlying platform implementation that provides features that are specific to an implementation. To access implementation-specific features, start by adding the platform implementation packages to your app or package: * **dart:io** [cross_file_io](https://pub.dev/packages/cross_file_io/install) * **Android Scoped Storage**: [cross_file_android](https://pub.dev/packages/cross_file_android/install) * **iOS/macOS App Sandbox**: [cross_file_darwin](https://pub.dev/packages/cross_file_darwin/install) * **Web**: [cross_file_web](https://pub.dev/packages/cross_file_web/install) Next, add the imports of the implementation packages to your app or package: ```dart // Import for Darwin App Sandbox features. import 'package:cross_file_darwin/cross_file_darwin.dart'; // Import for Web features. import 'package:cross_file_web/cross_file_web.dart'; ``` Now, additional features can be accessed through the platform implementations. Classes `FileSystemXFile`, `FileSystemXDirectory`, `ScopedStorageXFile`, and `ScopedStorageXDirectory` pass their functionality to a class provided by the current platform. Below are a couple of ways to access additional functionality provided by the platform and is followed by an example. 1. Pass a creation params class provided by a platform implementation to a `fromCreationParams` constructor (e.g. `FileSystemXFile.fromCreationParams`, `ScopedStorageXFile.fromCreationParams`, etc.). 2. Call methods on an implementation of a class by using `getExtension` method (e.g. `XFile.getExtension`, `XDirectory.getExtension`, etc.). Below is an example of using additional iOS/macOS and Web features for a `XFile`. ```dart late final XFile file; switch (CrossFile.implementation) { case CrossFileWeb(): final params = WebScopedStorageXFileCreationParams.fromObjectUrl( objectUrl: 'blob:https://some/url:for/file', ); file = ScopedStorageXFile.fromCreationParams(params); case CrossFileDarwin(): file = ScopedStorageXFile.fromUri(Uri.file('/my/file.txt')); default: file = XFile.fileSystem(path: '/my/file.txt'); } await file .getExtension() ?.startAccessingSecurityScopedResource(); debugPrint(await file.readAsString()); if (file is ScopedStorageXFile) { await file.dispose(); } ``` See https://pub.dev/documentation/cross_file_darwin/latest/cross_file_darwin/cross_file_darwin-library.html for more details on iOS/macOS App Sandbox features. See https://pub.dev/documentation/cross_file_android/latest/cross_file_android/cross_file_android-library.html for more details on Android Scoped Storage features. See https://pub.dev/documentation/cross_file_io/latest/cross_file_io/cross_file_io-library.html for more details on `dart:io` features. See https://pub.dev/documentation/cross_file_web/latest/cross_file_web/cross_file_web-library.html for more details on Web features. ## Changelog ## 0.4.0 * Updates `cross_file` to a package-separated federated plugin. * Adds `XDirectory` to access resource containers. * Adds implementation for file systems. See `FileSystemXFile` and `FileSystemXDirectory`. * Adds implementation for scoped storage APIs that use ephemeral URLS. See `ScopedStorageXFile` and `ScopedStorageXDirectory`. * **BREAKING CHANGES**: * Replaces `XFile(String path)` with `XFile.fileSystem({required String path})` or `FileSystemXFile(String path)`. * Removes `XFile.fromData`. `XFile`s can no longer be instantiated with a `Uint8List`. The web implementation can use `WebScopedStorageXFileCreationParams.fromBlob` to instantiate one with a `Blob`/`File`. See README to see how to access platform-specific features. * Removes `XFile.saveTo()`. `FileSystemXFile.writeAsBytes` has been added and the web implementation can use `WebScopedStorageXFileExtension.download`. See README to see how to access platform-specific features. * Removes `XFile.mimeType`. * Removes `XFile.path`. This has been replaced by `XFile.uri` or `FileSystemXFile.path`. * Changes `XFile.name` to a method that returns `Future` rather than a field that returns `String`. * Adds Flutter as a dependency. * Updates minimum supported SDK version to Flutter 3.41/Dart 3.11. ## 0.3.5+5 * Fixes native `readAsString` returning mojibake for `XFile.fromData`, which decoded the bytes as UTF-16 code units instead of using the `encoding` argument. ## 0.3.5+4 * Adds a runnable `main` entry point and an additional `XFile.fromData` demonstration to the example. ## 0.3.5+3 * Clarifies native XFile.mimeType documentation. * Updates minimum supported SDK version to Flutter 3.38/Dart 3.10. ## 0.3.5+2 * Separates "Save As" implementation details from XFile web class. ## 0.3.5+1 * Replaces README mentions of `dart:html` with `package:web`. * Updates minimum supported SDK version to Flutter 3.32/Dart 3.8. ## 0.3.5 * Fixes a bug where the bytes of an XFile, that is created using the `XFile.fromData` constructor, are ignored on web. * Updates minimum supported SDK version to Flutter 3.29/Dart 3.7. ## 0.3.4+2 * Adds support for `web: ^1.0.0`. ## 0.3.4+1 * Removes a few deprecated API usages. ## 0.3.4 * Updates to web code to package `web: ^0.5.0`. * Updates SDK version to Dart `^3.3.0`. ## 0.3.3+8 * Now supports `dart2wasm` compilation. * Updates minimum supported SDK version to Flutter 3.16/Dart 3.2. ## 0.3.3+7 * Updates README to improve example of instantiating an XFile. * Updates minimum supported SDK version to Flutter 3.10/Dart 3.0. ## 0.3.3+6 * Improves documentation about ignored parameters in IO implementation. ## 0.3.3+5 * Adds pub topics to package metadata. * Updates minimum supported SDK version to Flutter 3.7/Dart 2.19. ## 0.3.3+4 * Reverts an accidental change in a constructor argument's nullability. ## 0.3.3+3 * **RETRACTED** * Updates code to fix strict-cast violations. * Updates minimum SDK version to Flutter 3.0. ## 0.3.3+2 * Fixes lint warnings in tests. * Dartdoc correction for `readAsBytes` and `readAsString`. ## 0.3.3+1 * Fixes `lastModified` unimplemented error description. ## 0.3.3 * Removes unused Flutter dependencies. ## 0.3.2 * Improve web implementation so it can stream larger files. ## 0.3.1+5 * Unify XFile interface for web and mobile platforms ## 0.3.1+4 * The `dart:io` implementation of `saveTo` now does a file copy for path-based `XFile` instances, rather than reading the contents into memory. ## 0.3.1+3 * Fix example in README ## 0.3.1+2 * Fix package import in README * Remove 'Get Started' boilerplate in README ## 0.3.1+1 * Rehomed to `flutter/packages` repository. ## 0.3.1 * Fix nullability of `XFileBase`'s `path` and `name` to match the implementations to avoid potential analyzer issues. ## 0.3.0 * Migrated package to null-safety. * **breaking change** According to our unit tests, the API should be backwards-compatible. Some relevant changes were made, however: * Web: `lastModified` returns the epoch time as a default value, to maintain the `Future` return type (and not `null`) ## 0.2.1 * Prepare for breaking `package:http` change. ## 0.2.0 * **breaking change** Make sure the `saveTo` method returns a `Future` so it can be awaited and users are sure the file has been written to disk. ## 0.1.0+2 * Fix outdated links across a number of markdown files ([#3276](https://github.com/flutter/plugins/pull/3276)) ## 0.1.0+1 * Update Flutter SDK constraint. ## 0.1.0 * Initial open-source release.