Skip to main content

Filesystem

EOL Notice

Filesystem will reach its end-of-life on July 1, 2024, and will no longer receive updates or support. Please see Support Policy for additional information.

The Filesystem plugin presents a simple and intuitive interface for common file operations such as reading/writing and listing the contents of directories.

Installation

If you have not already setup Ionic Enterprise in your app, follow the one-time setup steps.

Next, install the plugin:

Available as a core Capacitor plugin.

Usage

The Filesystem plugin ships with a native Angular & es2015+/Typescript wrappers as well as being available on window.

// Angular
import { Filesystem } from '@ionic-enterprise/filesystem/ngx';
import { Directories } from '@ionic-enterprise/filesystem';

...

constructor(private filesystem: Filesystem) { }

async statApplicationDirectory() {
const info = await this.filesystem.stat({path: '/', directory: Directories.Application});
console.log('Stat Info: ', info);
}

...

// ES2015+/TypeScript
import { Directories, Filesystem } from '@ionic-enterprise/filesystem';

Filesystem.stat({path: '/', directory: Directories.Application})
.then((info) => console.log('Stat Info: ', info))
.catch((e) => console.log('Error occurred while doing stat: ', e));

...

// Vanilla JS
document.addEventListener('deviceready', () => {
IonicFilesystem.stat({path: '/', directory: IonicFilesystem.Directories.Application})
.then((info) => console.log('Stat Info: ', info))
.catch((e) => console.log('Error occurred while doing stat: ', e));
});

API Documentation

You can find the API and interface documentation for everything below. The main classes to pay attention to are:

  • Filesystem - This is the main API for interacting with the filesystem.
  • Directories - The available directory locations for the application.
  • Encodings - The available encodings when reading/writing a file.

Index

Enumerations

Classes

Interfaces


Enumerations

Directories

Directories:

The avaiable directories on the system

Application

Application: = "APPLICATION"

The Application directory


Cache

Cache: = "CACHE"

The Cache directory


Data

Data: = "DATA"

The Data directory


Documents

Documents: = "DOCUMENTS"

The Documents directory


External

External: = "EXTERNAL"

The external directory (Android only)


ExternalStorage

ExternalStorage: = "EXTERNAL_STORAGE"

The external storage directory (Android only)



Encodings

Encodings:

The possible encoding types

ASCII

ASCII: = "ascii"

ASCII encoding


UTF16

UTF16: = "utf16"

UTF16 encoding


UTF8

UTF8: = "utf8"

UTF8 encoding



Classes

Filesystem

usage:

// Angular
import { Filesystem } from '@ionic-enterprise/filesystem/ngx';
import { Directories } from '@ionic-enterprise/filesystem';

...

constructor(private filesystem: Filesystem) { }

async statApplicationDirectory() {
const info = await this.filesystem.stat({path: '/', directory: Directories.Application});
console.log('Stat Info: ', info);
}

...

// ES2015+/TypeScript
import { Directories, Filesystem } from '@ionic-enterprise/filesystem';

Filesystem.stat({path: '/', directory: Directories.Application})
.then((info) => console.log('Stat Info: ', info))
.catch((e) => console.log('Error occurred while doing stat: ', e));

...

// Vanilla JS
document.addEventListener('deviceready', () => {
IonicFilesystem.stat({path: '/', directory: IonicFilesystem.Directories.Application})
.then((info) => console.log('Stat Info: ', info))
.catch((e) => console.log('Error occurred while doing stat: ', e));
});

Directories

● Directories: Directories = Directories

The avaiable directories on the system


Encodings

● Encodings: Encodings = Encodings

The possible encoding types


appendFile

appendFile(options: FileWriteOptions): Promise<EmptyResult>

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

Parameters:

NameTypeDescription
optionsFileWriteOptionsoptions for the file append

Returns: Promise<EmptyResult> a promise that resolves with the file write result


copy

copy(options: CopyOptions): Promise<EmptyResult>

Copy a file or directory

Parameters:

NameTypeDescription
optionsCopyOptionsthe options for the copy operation

Returns: Promise<EmptyResult>


deleteFile

deleteFile(options: PathOptions): Promise<EmptyResult>

Delete a file from disk

Parameters:

NameTypeDescription
optionsPathOptionsoptions for the file delete

Returns: Promise<EmptyResult> a promise that resolves with the deleted file data result


getUri

getUri(options: PathOptions): Promise<GetUriResult>

Return full File URI for a path and directory

Parameters:

NameTypeDescription
optionsPathOptionsthe options for the stat operation

Returns: Promise<GetUriResult> a promise that resolves with the file stat result


mkdir

mkdir(options: MkdirOptions): Promise<EmptyResult>

Create a directory.

Parameters:

NameTypeDescription
optionsMkdirOptionsoptions for the mkdir

Returns: Promise<EmptyResult> a promise that resolves with the mkdir result


readFile

readFile(options: FileReadOptions): Promise<FileReadResult>

Read a file from disk

Parameters:

NameTypeDescription
optionsFileReadOptionsoptions for the file read

Returns: Promise<FileReadResult> a promise that resolves with the read file data result


readdir

readdir(options: PathOptions): Promise<ReaddirResult>

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

Parameters:

NameTypeDescription
optionsPathOptionsthe options for the readdir operation

Returns: Promise<ReaddirResult> a promise that resolves with the readdir directory listing result


rename

rename(options: RenameOptions): Promise<EmptyResult>

Rename a file or directory

Parameters:

NameTypeDescription
optionsRenameOptionsthe options for the rename operation

Returns: Promise<EmptyResult>


rmdir

rmdir(options: RmdirOptions): Promise<EmptyResult>

Remove a directory

Parameters:

NameTypeDescription
optionsRmdirOptionsthe options for the directory remove

Returns: Promise<EmptyResult>


stat

stat(options: PathOptions): Promise<StatResult>

Return data about a file

Parameters:

NameTypeDescription
optionsPathOptionsthe options for the stat operation

Returns: Promise<StatResult> a promise that resolves with the file stat result


writeFile

writeFile(options: FileWriteOptions): Promise<EmptyResult>

Write a file to disk in the specified location on device

Parameters:

NameTypeDescription
optionsFileWriteOptionsoptions for the file write

Returns: Promise<EmptyResult> a promise that resolves with the file write result



Interfaces

CopyOptions

CopyOptions:

<Optional> directory

● directory: Directories

The system directory containing the existing file or directory


from

● from: string

The existing file or directory


to

● to: string

The destination file or directory


<Optional> toDirectory

● toDirectory: Directories

The system directory containing the destination file or directory. If not supplied will use the 'directory' parameter as the destination



EmptyResult

EmptyResult:


FileReadOptions

FileReadOptions:

<Optional> directory

● directory: Directories

The directory to start in


<Optional> encoding

● encoding: Encodings

The encoding to read/write the file in, if not provided, data is read as binary and returned as base64 encoded data.

Pass Encodings.UTF8 to read data as string


path

● path: string

The path to the file or directory with one of the Directories



FileReadResult

FileReadResult:

data

● data: string

The data in the file



FileWriteOptions

FileWriteOptions:

data

● data: string

The data to write


<Optional> directory

● directory: Directories

The directory to start in


<Optional> encoding

● encoding: Encodings

The encoding to write the file in


path

● path: string

The path to the file or directory with one of the Directories



GetUriResult

GetUriResult:

uri

● uri: string



MkdirOptions

MkdirOptions:

createIntermediateDirectories

● createIntermediateDirectories: boolean

Whether to create any missing parent directories as well


<Optional> directory

● directory: Directories

The directory to start in


path

● path: string

The path to the file or directory with one of the Directories



PathOptions

PathOptions:

<Optional> directory

● directory: Directories

The directory to start in


path

● path: string

The path to the file or directory with one of the Directories



ReaddirResult

ReaddirResult:

files

● files: string[]

the list of files in the directory



RenameOptions

RenameOptions:

<Optional> directory

● directory: Directories

The system directory containing the existing file or directory


from

● from: string

The existing file or directory


to

● to: string

The destination file or directory


<Optional> toDirectory

● toDirectory: Directories

The system directory containing the destination file or directory. If not supplied will use the 'directory' parameter as the destination



RmdirOptions

RmdirOptions:

<Optional> directory

● directory: Directories

The directory to start in


path

● path: string

The path to the file or directory with one of the Directories


recursive

● recursive: boolean

Whether to recursively remove the contents of the directory (defaults to false)



StatResult

StatResult:

<Optional> ctime

● ctime: undefined | number

The created time if available


mtime

● mtime: number

The last modified time


size

● size: number

The size of the item


type

● type: "file" | "directory"

Whether the item is a file or a directory


uri

● uri: string

The size of the item



Change Log

[1.1.0] (2019-09-03)

Bug Fixes

  • Free saved call after permission result
  • android: remove incorrect trailing newline in readFile when using encoding
  • ios: make readdir return only file names
  • iOS: Update iOS deleteFile method bug where deleteFile would actually make a directory.
  • iOS: use proper getUri method

Features

  • Add recursive option for rmdir
  • add rename and copy implementations

[1.0.2] (2019-08-02)

Bug Fixes

  • iOS: Update iOS deleteFile method bug where deleteFile would actually make a directory.