{"id":17235355,"url":"https://github.com/alpha0010/react-native-file-access","last_synced_at":"2025-05-16T05:07:20.022Z","repository":{"id":38477293,"uuid":"322177845","full_name":"alpha0010/react-native-file-access","owner":"alpha0010","description":"Filesystem access for React Native","archived":false,"fork":false,"pushed_at":"2024-09-24T13:51:58.000Z","size":1138,"stargazers_count":324,"open_issues_count":20,"forks_count":27,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-05-07T04:49:00.060Z","etag":null,"topics":["filesystem","react-native"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alpha0010.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-12-17T04:14:40.000Z","updated_at":"2025-04-11T14:52:45.000Z","dependencies_parsed_at":"2025-01-03T07:13:39.157Z","dependency_job_id":"5a665325-cd21-40e1-b74e-1eb7885ea78d","html_url":"https://github.com/alpha0010/react-native-file-access","commit_stats":{"total_commits":145,"total_committers":12,"mean_commits":"12.083333333333334","dds":0.1103448275862069,"last_synced_commit":"4b30d89ee720ee488a8db727bae04c29f8dc93a0"},"previous_names":[],"tags_count":46,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alpha0010%2Freact-native-file-access","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alpha0010%2Freact-native-file-access/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alpha0010%2Freact-native-file-access/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alpha0010%2Freact-native-file-access/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alpha0010","download_url":"https://codeload.github.com/alpha0010/react-native-file-access/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254471060,"owners_count":22076585,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["filesystem","react-native"],"created_at":"2024-10-15T05:33:08.416Z","updated_at":"2025-05-16T05:07:15.002Z","avatar_url":"https://github.com/alpha0010.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# react-native-file-access\n\n[![npm](https://img.shields.io/npm/v/react-native-file-access)](https://www.npmjs.com/package/react-native-file-access)\n\nFilesystem access for React Native. Supports saving network requests directly\nto the filesystem. Supports Android scoped storage, a requirement when targeting\nAPI 30 or higher.\n\n## Installation\n\n```sh\nnpm install react-native-file-access\ncd ios \u0026\u0026 pod install\n```\n\nApple restricts usage of certain privacy sensitive API calls. If you do not\nuse disk space measurements or file timestamps, define the following variable\nin your Podfile to exclude restricted API calls.\n[More details.](https://github.com/alpha0010/react-native-file-access/issues/73)\n\n```ruby\n$RNFANoPrivacyAPI = true\n```\n\nIf the app does not use autolinking, continue to the [manual install instructions](https://github.com/alpha0010/react-native-file-access/wiki/Manual-Installation) in the wiki.\n\n### Compatibility\n\n| React Native    | react-native-file-access |\n| --------------- | ------------------------ |\n| \u003c= 0.64         | 1.x.x                    |\n| 0.65+, old arch | 2.x.x, 3.x.x             |\n| 0.71+, new arch | 3.x.x                    |\n\n## Usage\n\n```js\nimport { Dirs, FileSystem } from 'react-native-file-access';\n\n// ...\n\nconst text = await FileSystem.readFile(Dirs.CacheDir + '/test.txt');\n```\n\n#### Directory constants.\n\n- `Dirs.CacheDir`\n- `Dirs.DatabaseDir` (Android only)\n- `Dirs.DocumentDir`\n- `Dirs.LibraryDir` (iOS \u0026 MacOS only)\n- `Dirs.MainBundleDir`\n- `Dirs.SDCardDir` (Android only)\n  - Prefer `FileSystem.cpExternal()` when possible.\n\n#### Functions.\n\n`FileSystem.appendFile(path: string, data: string, encoding?: 'utf8' | 'base64'): Promise\u003cvoid\u003e`\n\n- Append content to a file.\n  - Default encoding of `data` is assumed utf8.\n\n`FileSystem.concatFiles(source: string, target: string): Promise\u003cnumber\u003e`\n\n- Append a file to another file. Returns number of bytes written.\n\n`FileSystem.cp(source: string, target: string, onProgress?: (bytesCopied: number, contentLength: number, done: boolean) =\u003e void): Promise\u003cvoid\u003e`\n\n- Copy a file.\n\n`FileSystem.cpAsset(asset: string, target: string, type?: 'asset' | 'resource'): Promise\u003cvoid\u003e`\n\n- Copy a bundled asset file.\n  - Default `type` is `asset`. Prefer this when possible.\n  - `resource` uses the Android `res/` folder, and inherits the associated\n    naming restrictions.\n\n`FileSystem.cpExternal(source: string, targetName: string, dir: 'audio' | 'downloads' | 'images' | 'video'): Promise\u003cvoid\u003e`\n\n- Copy a file to an externally controlled location.\n  - On Android API level \u003c 29, may require permission WRITE_EXTERNAL_STORAGE.\n  - On iOS, consider using `Dirs.DocumentDir` with `UIFileSharingEnabled`\n    and `LSSupportsOpeningDocumentsInPlace` enabled.\n\n`FileSystem.df(): Promise\u003c{ internal_free: number, internal_total: number, external_free?: number, external_total?: number }\u003e`\n\n- Check device available space.\n\n`FileSystem.exists(path: string): Promise\u003cboolean\u003e`\n\n- Check if a path exists.\n\n```\nFilesSystem.fetch(\n  resource: string,\n  init: { body?: string, headers?: { [key: string]: string }, method?: string, network?: 'any' | 'unmetered', path?: string },\n  onProgress?: (bytesRead: number, contentLength: number, done: boolean) =\u003e void\n): Promise\u003cFetchResult\u003e\n\ntype FetchResult = {\n  headers: { [key: string]: string };\n  ok: boolean;\n  redirected: boolean;\n  status: number;\n  statusText: string;\n  url: string;\n}\n```\n\n- Save a network request to a file.\n  - `resource` - URL to fetch.\n  - `init.path` - Optional filesystem location to save the response.\n  - `init.network` - Optional restriction on network type. Specifying\n    `unmetered` will reject the request if unmetered connections (most likely\n    WiFi) are unavailable.\n  - `onProgress` - Optional callback to listen to download progress. Events\n    are rate limited, so do not rely on `done` becoming `true`.\n    `contentLength` is only accurate if the server sends the correct headers.\n\n```\nFilesSystem.fetchManaged(\n  resource: string,\n  init: { body?: string, headers?: { [key: string]: string }, method?: string, network?: 'any' | 'unmetered', path?: string },\n  onProgress?: (bytesRead: number, contentLength: number, done: boolean) =\u003e void\n): ManagedFetchResult\n\ntype ManagedFetchResult = {\n  cancel: () =\u003e Promise\u003cvoid\u003e;\n  result: Promise\u003cFetchResult\u003e;\n}\n```\n\n- Save a network request to a file.\n  - Similar to `fetch()`, with the option to cancel before completion.\n\n`FilesSystem.getAppGroupDir(groupName: string): Promise\u003cstring\u003e`\n\n- Get the directory for your app group (iOS \u0026 MacOS only).\n  - App groups are used on iOS/MacOS for storing content, which is shared between apps.\n  - This is e.g. useful for sharing data between your iOS/MacOS app and a widget or a watch app.\n\n`FilesSystem.hash(path: string, algorithm: 'MD5' | 'SHA-1' | 'SHA-224' | 'SHA-256' | 'SHA-384' | 'SHA-512'): Promise\u003cstring\u003e`\n\n- Hash the file content.\n\n`FilesSystem.isDir(path: string): Promise\u003cboolean\u003e`\n\n- Check if a path is a directory.\n\n`FileSystem.ls(path: string): Promise\u003cstring[]\u003e`\n\n- List files in a directory.\n\n`FileSystem.mkdir(path: string): Promise\u003cstring\u003e`\n\n- Make a new directory.\n  - Returns path of created directory.\n\n`FileSystem.mv(source: string, target: string): Promise\u003cvoid\u003e`\n\n- Move a file.\n\n`FileSystem.readFile(path: string, encoding?: 'utf8' | 'base64'): Promise\u003cstring\u003e`\n\n- Read the content of a file.\n  - Default encoding of returned string is utf8.\n\n`FileSystem.readFileChunk(path: string, offset: number, length: number, encoding?: 'utf8' | 'base64'): Promise\u003cstring\u003e`\n\n- Read a chunk of the content of a file, starting from byte at `offset`, reading for `length` bytes.\n  - Default encoding of returned string is utf8.\n\n```\nFileSystem.stat(path: string): Promise\u003cFileStat\u003e\n\ntype FileStat = {\n  filename: string;\n  lastModified: number;\n  path: string;\n  size: number;\n  type: 'directory' | 'file';\n}\n```\n\n- Read file metadata.\n\n`FileSystem.statDir(path: string): Promise\u003cFileStat[]\u003e`\n\n- Read metadata of all files in a directory.\n\n`FileSystem.unlink(path: string): Promise\u003cvoid\u003e`\n\n- Delete a file.\n\n`FileSystem.unzip(source: string, target: string): Promise\u003cvoid\u003e`\n\n- Extract a zip archive.\n\n`FileSystem.writeFile(path: string, data: string, encoding?: 'utf8' | 'base64'): Promise\u003cvoid\u003e`\n\n- Write content to a file.\n  - Default encoding of `data` is assumed utf8.\n\n#### Utility functions.\n\n`Util.basename(path: string, separator?: string): string`\n\n- Get the file/folder name from the end of the path.\n  - Default path `separator` is `/`.\n\n`Util.dirname(path: string, separator?: string): string`\n\n- Get the path containing the file/folder.\n  - Default path `separator` is `/`.\n\n`Util.extname(path: string, separator?: string): string`\n\n- Get the file extension.\n  - Default path `separator` is `/`.\n\n#### Scoped storage.\n\nFor simple usage, use `FileSystem.cpExternal()` to submit files to general\nscoped storage categories.\n\nMost functions in this library work with `content://` Android resource uris.\nTo gain access to a resource uri, currently use a library such as\n[react-native-document-picker](https://github.com/rnmods/react-native-document-picker) or\n[react-native-scoped-storage](https://github.com/ammarahm-ed/react-native-scoped-storage).\nEventually this library will incorporate file/folder selector functionality\n(pull requests welcome).\n\nNote:\n- When generating a scoped storage resource uri, use the helper\n  `AndroidScoped.appendPath(dir, 'data.txt')`, not `dir + '/data.txt'`.\n- Android may change the name of created files/folders.\n\n`AndroidScoped.appendPath(basePath: string, segment: string): string`\n\n- Append a path segment to an Android scoped storage content uri.\n\n## Testing\n\nFor ease of testing, this library contains a mock implementation:\n[jest/react-native-file-access.ts](https://github.com/alpha0010/react-native-file-access/blob/master/jest/react-native-file-access.ts).\nTo use, copy it into the [`__mocks__`](https://jestjs.io/docs/en/manual-mocks#mocking-node-modules)\nfolder, modifying if needed.\n\n## Alternatives\n\nThis library aims to be a modern implementation of filesystem api, using Kotlin/Swift\nand latest best practices. For a more established library, consider:\n\n- [expo-file-system](https://docs.expo.io/versions/latest/sdk/filesystem/)\n  - Well supported, a good option if already using Expo.\n- [react-native-blob-util](https://github.com/RonRadtke/react-native-blob-util)\n  - Often a dependency of other libraries.\n  - Forked from, and compatible with, the popular but deprecated [rn-fetch-blob](https://github.com/joltup/rn-fetch-blob).\n- [react-native-fs](https://github.com/itinance/react-native-fs)\n  - Large feature set.\n  - Low maintenance, aging codebase.\n\nFor more greater control over network requests, consider\n[react-native-blob-courier](https://github.com/edeckers/react-native-blob-courier).\n\n## Contributing\n\nSee the [contributing guide](CONTRIBUTING.md) to learn how to contribute to the repository and the development workflow.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falpha0010%2Freact-native-file-access","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falpha0010%2Freact-native-file-access","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falpha0010%2Freact-native-file-access/lists"}