FileSystem

File system handing with @nativescript/core provides easy-to-use APIs for working with files and folders in a device's file system like managing files, folders, paths, and separators, etc.

How to work with files and folders ​

Accessing the Documents folder ​

To get the root Documents folder, call the documents() method on knownFolders:

import { knownFolders } from '@nativescript/core'

const documents = knownFolders.documents()

Accessing the temporary(Caches) folder ​

import { knownFolders } from '@nativescript/core'

const cache = knownFolders.temp()

Accessing the root folder for the app ​

import { knownFolders } from '@nativescript/core'

const appRootFolder = knownFolders.currentApp()

Creating a folder ​

To create a folder, call the getFolder() method on an instance of Folder (any of the root folders above or one you create) and pass it the name of the folder.

folder.getFolder('folder-name')

You can also use the fromPath static method of the Folder class.

const folderPath = path.join(knownFolders.documents().path, 'music')
const folder: Folder = Folder.fromPath(folderPath)

Renaming a folder ​

To rename a folder, use the rename or renameSync method:

folder
  .rename(newName)
  .then((res) => {
    // Folder Successfully renamed.
  })
  .catch((err) => {
    //Folder couldn't be renamed
    console.error(err)
  })

Check if a folder exists ​

const folderExists: boolean = Folder.exists('folder-path')

Accessing a folder's content ​

To get a folder's files and folders, use the getEntitiesSync or getEntities method:

folder
  .getEntities()
  .then((entities: FileSystemEntity[]) => {
    // do something
  })
  .catch((err) => {
    console.log(err)
  })

Deleting the contents of a Folder ​

To delete all the content of a Folder, use the clear or clearSync method of a Folder instance:

folder
  .clear()
  .then((result) => {
    // successful delete
  })
  .catch((rerror) => {})

// OR

folder.clearSync((error) => {})

Deleting a folder ​

To delete a folder, use the remove or removeSync method:

folder
  .remove()
  .then((value: boolean) => {
    console.log(value)
  })
  .catch((error) => {
    console.error(error.message)
  })

Creating, writing to and reading from a text file ​

• To create a file, call the getFile() method on an instance of the Folder class and pass it the file name with the extension.

folder.getFile('my-text.txt')
//or
const filePath = path.join(folder.path, 'my-text.txt')
const file = File.fromPath(filePath)

• To save a text to a file, use the writeText or writeTextSync method:

file
  .writeText('Some text')
  .then((result) => {
    // Succeeded writing to the file.
  })
  .catch((error) => {
    console.log(error)
  })

• To extract data from a text file, you can use the readText or readTextSync method of the file instance. Here's an example of how to use it:

file
  .readText()
  .then((res) => {
    // Succeeded read from file.
  })
  .catch((error) => {})

Check if a file exists ​

To check if a file exists, you can use exists with the file path:

const exists = File.exists(filePath)

Renaming a file ​

To rename a file, use the rename or renameSync method:

file
  .rename('new-name.ext')
  .then((value) => {})
  .catch((err) => {})

Saving a binary data to a file ​

To save binary data to a file, use either the write or writeSync method:

file
  .write(binary data)
  .then(result => {
    // Succeeded writing to the file.

  })
  .catch(error => {
    console.log(error)
  })

Reading a binary data from a file ​

To read binary data, use the read or readSync method of the File instance. For example, you can save an image on the device and retrive it as follows:

async readAnImage() {

    const folder = knownFolders.documents()
    const filePath = path.join(folder.path, 'cat.png')
    const imageFile = File.fromPath(filePath)

    try {

      const imageSource = await ImageSource.fromFile('~/assets/images/download.jpeg')
      const saved: boolean = imageSource.saveToFile(filePath, "png")

      if (saved) {
        // READ BINARY DATA
        const imageBinary = await imageFile.read()
        const img = await ImageSource.fromData(imageBinary)
      }

    } catch (err) {

    }
}

Deleting a file ​

To remove a file, use the remove or removeSync method of the File instance:

file
  .remove()
  .then((res: boolean) => {
    // Success removing the file.
  })
  .catch((err) => {})

Normalizing a path ​

To normalize a path use the normalize or create the path with the join method from the path object:

const testPath = '///test.txt'
let documentsFolder = knownFolders.documents()
path.normalize(documentsFolder.path + testPath)

FileSystem API ​

documents() ​

const folder: Folder = knownFolders.documents()

Gets the Documents folder available for the current application. This Folder is private for the application and not accessible from Users/External apps.

externalDocuments() ​

const folder: Folder = knownFolders.externalDocuments()

Gets the Documents folder available for the current application from an external storage source. This folder has private access, with availability limited to the application, meaning it is not accessible to outside users, bots or external apps.

• On Android, for such read or write access, the flags READ_EXTERNAL_STORAGE/WRITE_EXTERNAL_STORAGE permissions need to be set to true. This can be done by adding the following XML code to the AndroidManifest.xml file:

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

• There is no external storage on iOS, it is the same as documents().

temp() ​

const folder: Folder = knownFolders.temp()

Gets the Temporary (Caches) folder available for the current application. This Folder is private for the application and not accessible from Users/External apps.

currentApp() ​

const folder: Folder = knownFolders.currentApp()

Gets the root folder for the current application.

iOS known folders ​

The following methods allow to access to iOS known folders.

library() ​

const folder: Folder = knownFolders.ios.library()

Gets the NSLibraryDirectory.

developer() ​

const folder: Folder = knownFolders.ios.developer()

Gets the NSDeveloperDirectory.

desktop() ​

const folder: Folder = knownFolders.ios.desktop()

Gets the NSDesktopDirectory.

downloads() ​

const folder: Folder = knownFolders.ios.downloads()

Gets the NSDownloadsDirectory.

movies() ​

const folder: Folder = knownFolders.ios.movies()

Gets the NSMoviesDirectory.

music() ​

const folder: Folder = knownFolders.ios.music()

Gets the NSMusicDirectory.

pictures() ​

const folder: Folder = knownFolders.ios.pictures()

Gets the NSPicturesDirectory.

sharedPublic() ​

const folder: Folder = knownFolders.ios.sharedPublic()

Gets the NSSharedPublicDirectory.

fromPath() ​

const file: File = File.fromPath(path)

or

const folder: Folder = Folder.fromPath(path)

Gets or creates a Folder or File entity at the specified path.

getFolder ​

const folder: Folder = folder.getFolder(name)

Gets or creates a Folder entity with the specified name within a Folder.

exists ​

const folderExists: boolean = Folder.exists(path)

or

const file: boolean = File.exists(path)

Checks whether a Folder or File with the specified path already exists.

isKnown ​

const isItAKnownFolder: boolean = folder.isKnown

Determines whether this instance is a known folder (accessed through the knownFolders object).

Both the File and Folder classes extend the FileSystemEntity which has the following API:

lastModified ​

const lastModified: Date = entity.lastModified

Gets the Date object specifying the last time this entity was modified.

name ​

const name: string = entity.name

Gets the name of the entity.

path ​

const path: string = entity.path

Gets the fully-qualified path (including the extension for a File) of the entity.

parent ​

const parent: Folder = entity.parent

Gets the Folder object representing the parent of this entity. Will be null for a root folder like Documents or Temporary. This property is readonly.

remove() ​

const result = await entity.remove()

Asynchronously removes (deletes) the current Entity from the file system.

removeSync() ​

entity.removeSync(onError?: (error: any) => any): void

Removes (deletes) the current Entity from the file system.

rename() ​

entity.rename(newName: string): Promise<any>

Asynchronously renames the current entity using the specified name.

renameSync() ​

entity.renameSync(newName: string, onError?: (error: any) => any)

Renames the current entity synchronously, using the specified name.

getEntities() ​

folder.getEntities(): Promise<Array<FileSystemEntity>>

Asynchronously gets all the top-level entities residing within a folder.

getEntitiesSync() ​

folder.getEntitiesSync(onError?: (error: any) => any): Array<FileSystemEntity>

Gets all the top-level entities residing within this folder synchronously. onError is a optional function to be called if some error occurs.

eachEntity() ​

folder.eachEntity(onEntity: (entity: FileSystemEntity) => boolean)

Enumerates all the top-level FileSystem entities within a folder. onEntity is a callback that receives the current entity.

getFile() ​

folder.getFile(name: string): File

Gets or creates a File entity with the specified name within this Folder

extension ​

const fileExt: string = file.extension

Gets the extension of the file.

size ​

const fileSize: number = file.size

Gets the extension of the file.

isLocked ​

const isFileLocked: boolean = file.isLocked

Gets a boolean value indicating whether the file is currently locked, meaning a background operation associated with this file is running.

readText() ​

const text = await file.readText(encoding)

Asynchronously reads the content of the file as a string using an optional encoding value. If you do not pass any encoding, UTF-8 is used.

readTextSync() ​

file.readTextSync(onError?: (error: any) => any, encoding?: string): string

Reads the content of the file as a string synchronously, using the specified encoding (defaults to UTF-8). onError is a function to be called if some IO-error occurs.

read ​

const fileContent = await file.read()

Reads the binary content of the file asynchronously.

readSync() ​

const fileContent = file.readSync(onError)

Reads the binary content of the file synchronously. onError is a function to be called if some IO-error occurs.

writeText() ​

const result = await file.writeText(content, encoding)

Asynchronously writes the content of the file as a string using the specified encoding (defaults to UTF-8).

writeTextSync() ​

file.writeTextSync(content, onError, encoding): void

Synchronously writes the content of the file as a string using the specified encoding (defaults to UTF-8).

write() ​

await file.write(content)

Writes the provided binary content to the file asynchronously.

writeSync() ​

file.writeSync(content: any, onError?: (error: any) => any): void

Writes the provided binary content to the file synchronously.

contains() ​

const containsEntity: boolean = folder.contains(name)

Checks whether this Folder contains an Entity with the specified name.

clear() ​

const result = await folder.clear()

Asynchronously deletes all the files and folders (recursively), contained within the Folder.

clearSync() ​

folder.clearSync(onError)

Synchronously deletes all the files and folders (recursively), contained within the Folder.

path operations ​

normalize ​

const normalizedPath: string = path.normalize(path)

Normalizes a path, taking care of occurrences like .. and //.

join() ​

const joinedPath: string = path.join(...paths)

Joins all the provided string components, forming a valid and normalized path.

separator ​

pathSeparator: string = path.separator

Gets the string used to separate file paths.

API References ​

• File class
• Folder class
• FileSystemEntity class
• knownFolders module
• path module

Native Component ​

• Android: java.io.File

• iOS: NSFileManager