File System Access API
Read, Write and File management capabilities
The File System Access API is formally known as Native File System API and prior to that, it was called Writeable Files API. It allows web apps to read or save changes directly to files and folders on the user’s device. This means you can build a web app that interacts with files on the user’s local device.
You can see an example text editor demo.
The File System Access API is currently supported on most Chromium browsers on Windows, macOS, Chrome OS, and Linux. Checkout browser compatibility here.
After a user grants a web app access, it allows users to read or save changes directly to files and folders on the user’s device. Beyond reading and writing files, the File System Access API provides the ability to open a directory and identify its contents. You can read more about that here.
In this article, we will look at how we use the file system access API in React to do the following:
- Opening and Reading Contents of files from disk
- Saving(writing) changes to files.
NB: I will be using typescript together with react for type safety.
Opening and Reading Contents of files from disk
The Code below allows the user to open and read the contents of files using the window.showOpenFilePicker() as an entry point. it opens a file picker dialog box and prompts the user to select a file.
NB: We will first declare a fileHandle variable at the top level to help us keep a reference to the fileHandle around so that it can be used later.
let fileHandle: FileSystemFileHandle | undefined
After they select a file, the API returns an array of handles that contains the properties and methods needed to interact with the file. E.g. getFile().
Additional parameters can be passed to the showOpenFilePicker() to specify the options for the kind of file you want to open. In this case, JSON files only.
We will read the file content by calling
fileHandle.getFile() as seen on line 13 which returns a
File object, which contains a blob, and then calls the method text() as seen on line 14.
NB: am also returning the file object so that I will be able to read the name of the file from it. This is not required.
Saving(writing) changes to files.
There are usually two ways to save a file: Save, and Save As. Save simply writes the changes back to the original file using the file handle retrieved earlier. But Save As creates a new file, and thus requires a new file handle.
Creating a new File (Save As)
To save a new file, we call showSaveFilePicker(), which opens the file picker in Save mode, allowing the user to enter a new file name for saving.
We save the file as JSON as specified in the saveFileOptions object.
Saving changes back to the original file (Save)
Writing data to disk uses a FileSystemWritableFileStream object. We create a Writable Stream by calling createWritable() on the file handle object. The browser first checks if the user has granted write permission to the file. If not, the browser will prompt the user for permission.
The write() method takes a string, which is the content to be written to the file.
You Can Suggest a file name and start directory for saving and opening files like below.
The list of the well-known system directories include:
desktop: The user's desktop directory, if such a thing exists.
documents: Directory in which documents created by the user would typically be stored.
downloads: Directory where downloaded files would typically be stored.
music: Directory where audio files would typically be stored.
pictures: Directory where photos and other still images would typically be stored.
videos: Directory where videos/movies would typically be stored.