Nary a Package Missing

    @capacitor/filesystem
    TypeScript icon, indicating that this package has built-in type declarations

    4.0.1 • Public • Published

    @capacitor/filesystem

    The Filesystem API provides a NodeJS-like API for working with files on the device.

    Install

    npm install @capacitor/filesystem
    npx cap sync

    Android

    If using Directory.Documents or Directory.ExternalStorage, this API requires the following permissions be added to your AndroidManifest.xml:

    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

    Read about Setting Permissions in the Android Guide for more information on setting Android permissions.

    Note that Directory.Documents and Directory.ExternalStorage are only available on Android 9 or older.

    Understanding Directories and Files

    iOS and Android have additional layers of separation between files, such as special directories that are backed up to the Cloud, or ones for storing Documents. The Filesystem API offers a simple way to scope each operation to a specific special directory on the device.

    Additionally, the Filesystem API supports using full file:// paths, or reading content:// files on Android. Simply leave out the directory param to use a full file path.

    Example

    import { Filesystem, Directory, Encoding } from '@capacitor/filesystem';
    
    const writeSecretFile = async () => {
      await Filesystem.writeFile({
        path: 'secrets/text.txt',
        data: "This is a test",
        directory: Directory.Documents,
        encoding: Encoding.UTF8,
      });
    };
    
    const readSecretFile = async () => {
      const contents = await Filesystem.readFile({
        path: 'secrets/text.txt',
        directory: Directory.Documents,
        encoding: Encoding.UTF8,
      });
    
      console.log('secrets:', contents);
    };
    
    const deleteSecretFile = async () => {
      await Filesystem.deleteFile({
        path: 'secrets/text.txt',
        directory: Directory.Documents,
      });
    };
    
    const readFilePath = async () => {
      // Here's an example of reading a file with a full file path. Use this to
      // read binary data (base64 encoded) from plugins that return File URIs, such as
      // the Camera.
      const contents = await Filesystem.readFile({
        path: 'file:///var/mobile/Containers/Data/Application/22A433FD-D82D-4989-8BE6-9FC49DEA20BB/Documents/text.txt'
      });
    
      console.log('data:', contents);
    };

    API

    readFile(...)

    readFile(options: ReadFileOptions) => Promise<ReadFileResult>

    Read a file from disk

    Param Type
    options ReadFileOptions

    Returns: Promise<ReadFileResult>

    Since: 1.0.0


    writeFile(...)

    writeFile(options: WriteFileOptions) => Promise<WriteFileResult>

    Write a file to disk in the specified location on device

    Param Type
    options WriteFileOptions

    Returns: Promise<WriteFileResult>

    Since: 1.0.0


    appendFile(...)

    appendFile(options: AppendFileOptions) => Promise<void>

    Append to a file on disk in the specified location on device

    Param Type
    options AppendFileOptions

    Since: 1.0.0


    deleteFile(...)

    deleteFile(options: DeleteFileOptions) => Promise<void>

    Delete a file from disk

    Param Type
    options DeleteFileOptions

    Since: 1.0.0


    mkdir(...)

    mkdir(options: MkdirOptions) => Promise<void>

    Create a directory.

    Param Type
    options MkdirOptions

    Since: 1.0.0


    rmdir(...)

    rmdir(options: RmdirOptions) => Promise<void>

    Remove a directory

    Param Type
    options RmdirOptions

    Since: 1.0.0


    readdir(...)

    readdir(options: ReaddirOptions) => Promise<ReaddirResult>

    Return a list of files from the directory (not recursive)

    Param Type
    options ReaddirOptions

    Returns: Promise<ReaddirResult>

    Since: 1.0.0


    getUri(...)

    getUri(options: GetUriOptions) => Promise<GetUriResult>

    Return full File URI for a path and directory

    Param Type
    options GetUriOptions

    Returns: Promise<GetUriResult>

    Since: 1.0.0


    stat(...)

    stat(options: StatOptions) => Promise<StatResult>

    Return data about a file

    Param Type
    options StatOptions

    Returns: Promise<StatResult>

    Since: 1.0.0


    rename(...)

    rename(options: RenameOptions) => Promise<void>

    Rename a file or directory

    Param Type
    options CopyOptions

    Since: 1.0.0


    copy(...)

    copy(options: CopyOptions) => Promise<CopyResult>

    Copy a file or directory

    Param Type
    options CopyOptions

    Returns: Promise<CopyResult>

    Since: 1.0.0


    checkPermissions()

    checkPermissions() => Promise<PermissionStatus>

    Check read/write permissions. Required on Android, only when using Directory.Documents or Directory.ExternalStorage.

    Returns: Promise<PermissionStatus>

    Since: 1.0.0


    requestPermissions()

    requestPermissions() => Promise<PermissionStatus>

    Request read/write permissions. Required on Android, only when using Directory.Documents or Directory.ExternalStorage.

    Returns: Promise<PermissionStatus>

    Since: 1.0.0


    Interfaces

    ReadFileResult

    Prop Type Description Since
    data string The string representation of the data contained in the file 1.0.0

    ReadFileOptions

    Prop Type Description Since
    path string The path of the file to read 1.0.0
    directory Directory The Directory to read the file from 1.0.0
    encoding Encoding The encoding to read the file in, if not provided, data is read as binary and returned as base64 encoded. Pass Encoding.UTF8 to read data as string 1.0.0

    WriteFileResult

    Prop Type Description Since
    uri string The uri where the file was written into 1.0.0

    WriteFileOptions

    Prop Type Description Default Since
    path string The path of the file to write 1.0.0
    data string The data to write 1.0.0
    directory Directory The Directory to store the file in 1.0.0
    encoding Encoding The encoding to write the file in. If not provided, data is written as base64 encoded. Pass Encoding.UTF8 to write data as string 1.0.0
    recursive boolean Whether to create any missing parent directories. false 1.0.0

    AppendFileOptions

    Prop Type Description Since
    path string The path of the file to append 1.0.0
    data string The data to write 1.0.0
    directory Directory The Directory to store the file in 1.0.0
    encoding Encoding The encoding to write the file in. If not provided, data is written as base64 encoded. Pass Encoding.UTF8 to write data as string 1.0.0

    DeleteFileOptions

    Prop Type Description Since
    path string The path of the file to delete 1.0.0
    directory Directory The Directory to delete the file from 1.0.0

    MkdirOptions

    Prop Type Description Default Since
    path string The path of the new directory 1.0.0
    directory Directory The Directory to make the new directory in 1.0.0
    recursive boolean Whether to create any missing parent directories as well. false 1.0.0

    RmdirOptions

    Prop Type Description Default Since
    path string The path of the directory to remove 1.0.0
    directory Directory The Directory to remove the directory from 1.0.0
    recursive boolean Whether to recursively remove the contents of the directory false 1.0.0

    ReaddirResult

    Prop Type Description Since
    files FileInfo[] List of files and directories inside the directory 1.0.0

    FileInfo

    Prop Type Description Since
    name string Name of the file or directory.
    type 'directory' | 'file' Type of the file. 4.0.0
    size number Size of the file in bytes. 4.0.0
    ctime number Time of creation in milliseconds. It's not available on Android 7 and older devices. 4.0.0
    mtime number Time of last modification in milliseconds. 4.0.0
    uri string The uri of the file. 4.0.0

    ReaddirOptions

    Prop Type Description Since
    path string The path of the directory to read 1.0.0
    directory Directory The Directory to list files from 1.0.0

    GetUriResult

    Prop Type Description Since
    uri string The uri of the file 1.0.0

    GetUriOptions

    Prop Type Description Since
    path string The path of the file to get the URI for 1.0.0
    directory Directory The Directory to get the file under 1.0.0

    StatResult

    Prop Type Description Since
    type 'directory' | 'file' Type of the file. 1.0.0
    size number Size of the file in bytes. 1.0.0
    ctime number Time of creation in milliseconds. It's not available on Android 7 and older devices. 1.0.0
    mtime number Time of last modification in milliseconds. 1.0.0
    uri string The uri of the file 1.0.0

    StatOptions

    Prop Type Description Since
    path string The path of the file to get data about 1.0.0
    directory Directory The Directory to get the file under 1.0.0

    CopyOptions

    Prop Type Description Since
    from string The existing file or directory 1.0.0
    to string The destination file or directory 1.0.0
    directory Directory The Directory containing the existing file or directory 1.0.0
    toDirectory Directory The Directory containing the destination file or directory. If not supplied will use the 'directory' parameter as the destination 1.0.0

    CopyResult

    Prop Type Description Since
    uri string The uri where the file was copied into 4.0.0

    PermissionStatus

    Prop Type
    publicStorage PermissionState

    Type Aliases

    RenameOptions

    CopyOptions

    PermissionState

    'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'

    Enums

    Directory

    Members Value Description Since
    Documents 'DOCUMENTS' The Documents directory On iOS it's the app's documents directory. Use this directory to store user-generated content. On Android it's the Public Documents folder, so it's accessible from other apps. It's not accesible on Android 10 unless the app enables legacy External Storage by adding android:requestLegacyExternalStorage="true" in the application tag in the AndroidManifest.xml. It's not accesible on Android 11 or newer. 1.0.0
    Data 'DATA' The Data directory On iOS it will use the Documents directory. On Android it's the directory holding application files. Files will be deleted when the application is uninstalled. 1.0.0
    Library 'LIBRARY' The Library directory On iOS it will use the Library directory. On Android it's the directory holding application files. Files will be deleted when the application is uninstalled. 1.1.0
    Cache 'CACHE' The Cache directory Can be deleted in cases of low memory, so use this directory to write app-specific files that your app can re-create easily. 1.0.0
    External 'EXTERNAL' The external directory On iOS it will use the Documents directory On Android it's the directory on the primary shared/external storage device where the application can place persistent files it owns. These files are internal to the applications, and not typically visible to the user as media. Files will be deleted when the application is uninstalled. 1.0.0
    ExternalStorage 'EXTERNAL_STORAGE' The external storage directory On iOS it will use the Documents directory On Android it's the primary shared/external storage directory. It's not accesible on Android 10 unless the app enables legacy External Storage by adding android:requestLegacyExternalStorage="true" in the application tag in the AndroidManifest.xml. It's not accesible on Android 11 or newer. 1.0.0

    Encoding

    Members Value Description Since
    UTF8 'utf8' Eight-bit UCS Transformation Format 1.0.0
    ASCII 'ascii' Seven-bit ASCII, a.k.a. ISO646-US, a.k.a. the Basic Latin block of the Unicode character set This encoding is only supported on Android. 1.0.0
    UTF16 'utf16' Sixteen-bit UCS Transformation Format, byte order identified by an optional byte-order mark This encoding is only supported on Android. 1.0.0

    Install

    npm i @capacitor/filesystem

    DownloadsWeekly Downloads

    50,972

    Version

    4.0.1

    License

    MIT

    Unpacked Size

    361 kB

    Total Files

    31

    Last publish

    Collaborators

    • itschaced
    • it_mike_s
    • larsmikkelsen
    • giralte-ionic
    • steven0351-ionic
    • jpender
    • ionicjs
    • maxlynch
    • mhartington
    • jcesarmobile
    • cmapoole
    • nhyatt