title	description
FileSystem	Work with the device file system

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.

Parameter	Type	Description
`onError?`	`(error: any) => any`	An optional 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).

Parameter	Type	Description
`content`	`string`	The content to write.
`encoding?`	`string`	An optional encoding value. If you do not pass any encoding, `UTF-8` is used.

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).

Parameter	Type	Description
`content`	`string`	The content to write.
`onError?`	`(error: any) => any`	An optional function to be called if some IO-error occurs.
`encoding?`	`string`	An optional encoding value. If you do not pass any encoding, `UTF-8` is used.

write()

await file.write(content)

Writes the provided binary content to the file asynchronously.

Parameter	Type	Description
`content`	`any`	The content to write.

writeSync()

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

Writes the provided binary content to the file synchronously.

Parameter	Type	Description
`content`	`any`	The content to write.
`onError?`	`(error: any) => any`	An optional function to be called if some IO-error occurs.

contains()

const containsEntity: boolean = folder.contains(name)

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

Parameter	Type	Description
`name`	`string`	The name of the entity to check for.

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.

Parameter	Type	Description
`onError?`	`(error: any) => any`	An optional function to be called if some IO-error occurs.

path operations

normalize

const normalizedPath: string = path.normalize(path)

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

Parameter	Type	Description
`path`	`string`	The path to normalize.

join()

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

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

Parameter	Type	Description
`paths`	`string[]`	The components of the path to join.

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

Files

file-system.md

Latest commit

History