What is the File System Access API?The File System Access API (formerly known as Native File System API and prior to that it was called Writeable Files API) enables developers to build powerful web apps that interact with files on the user's local device, such as IDEs, photo and video editors, text editors, and more. After a user grants a web app access, this API allows them 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 enumerate its contents. Show
The File System Access API—despite the similar name—is distinct from the It is likewise distinct from the deprecated File API: Directories and System specification, which defines an API to navigate file system hierarchies and a means by which browsers may expose sandboxed sections of a user's local filesystem to web applications. If you've worked with reading and writing files before, much of what I'm about to share will be familiar to you. I encourage you to read it anyway, because not all systems are alike. We've put a lot of thought into the design and implementation of the File System Access API to ensure that people can easily manage their files. See the security and permissions section for more information. The File System Access API is currently supported on most Chromium browsers on Windows, macOS, ChromeOS, and Linux. A notable exception is Brave where it is currently only available behind a flag. Android support is coming for the origin private file system part (https://crbug.com/1354273). There are no plans currently for picker methods, but you can track potential progress by starring crbug.com/1011535. Using the File System Access APITo show off the power and usefulness of the File System Access API, I wrote a single file text editor. It lets you open a text file, edit it, save the changes back to disk, or start a new file and save the changes to disk. It's nothing fancy, but provides enough to help you understand the concepts. Try itSee the File System Access API in action in the text editor demo. Read a file from the local file systemThe first use case I want to tackle is to ask the user to choose a file, then open and read that file from disk. Ask the user to pick a file to readThe entry point to the File System Access API is Like many other powerful APIs, calling
Once the user selects a file, It's helpful to keep a reference to the file handle so that it can be used later. It'll be needed to save changes to the file, or to perform any other file operations. Read a file from the file systemNow that you have a handle to a file, you can get the file's properties, or access the file itself. For now, I'll simply read its contents. Calling
For the majority of use cases, you can read files in sequential order with the The Putting it all togetherWhen users click the Open button, the browser shows a file picker. Once they've selected a file, the app reads the contents and puts them into a
Write the file to the local file systemIn the text editor, there are 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. Create a new fileTo save a file, call
Sometimes processing the to-be-saved data takes some time after the user clicks the Save button in your app. A common gotcha is to do this work before the Save changes to diskYou can find all the code for saving changes to a file in my text editor demo on GitHub. The core file system interactions are in
Writing data to disk uses a The
You can also Changes are not written to disk until the stream is closed, either by calling Specifying a suggested file name and start directoryIn many cases you may want your app to suggest a default file name or location. For example, a text editor might want to suggest a default file name of
The same goes for
the default start directory. If you're building a text editor, you may want to start the file save or file open dialog in the default
The list of the well-known system directories is:
Apart from well-known system directories, you can also pass an existing file or
directory handle as a value for
Specifying the purpose of different file pickersSometimes applications have different pickers for different purposes. For example, a rich text editor may allow the user to open text files, but also to import images. By default, each file picker would open at the last-remembered location. You can circumvent this by
storing
Storing file handles or directory handles in IndexedDBFile handles and directory handles are serializable, which means that you can save a file or directory handle to IndexedDB, or call Saving file or directory handles to IndexedDB means that you can store state, or remember which files or directories a user was working on. This makes it possible to keep a list of recently opened or edited files, offer to re-open the last file when the app is opened, restore the previous working directory, and more. In the text editor, I store a list of the five most recent files the user has opened, making it easy to access those files again. The code example below shows storing and retrieving a file handle and a directory handle. You can see this in action over on Glitch. (I use the idb-keyval library for brevity.)
Stored file or directory handles and permissionsSince permissions currently are not persisted between
sessions, you should verify whether the user has granted permission to the file or directory using In the text editor, I created a
By requesting write permission with the read request, I reduced the number of permission prompts; the user sees one prompt when opening the file, and grants permission to both read and write to it. While Opening a directory and enumerating its contentsTo enumerate all files in a directory, call
If you additionally need to access each file via
Creating or accessing files and folders in a directoryFrom a directory, you can create or access files and folders using the
Resolving the path of an item in a directoryWhen working with files or folders in a
directory, it can be useful to resolve the path of the item in question. This can be done with the aptly named
Deleting files and folders in a directoryIf you have obtained access to a directory, you can delete
the contained files and folders with the
Deleting a file or folder directlyIf you have access to a file or directory handle, call
The Renaming and moving files and foldersFiles and folders can be renamed or moved to a new location by calling
The Drag and drop integrationThe
HTML Drag and Drop interfaces enable web applications to accept dragged and dropped files on a web page. During a drag and drop operation, dragged file and directory items are associated with file entries and directory entries respectively. The
Accessing the origin private file systemThe origin private file system is a storage endpoint that, as the name suggests, is private to the origin of the page. While browsers typically implement this by persisting the contents of this origin private file
system to disk somewhere, it is not intended that the contents be easily user accessible. Similarly, there is no expectation that files or directories with names matching the names of children of the origin private file system exist. While the browser might make it seem that there are files, internally—since this is an origin private file system—the browser might store these "files" in a database or any other data structure. Essentially, if you use this API, do not
expect to find the created files matched one-to-one somewhere on the hard disk. You can operate as usual on the origin private file system once you have access to the root
Accessing files optimized for performance from the origin private file systemThe origin private file system provides optional access to a special kind of file that is highly optimized for
performance, for example, by offering in-place and exclusive write access to a file's content. In Chromium 102 and later, there is an additional method on the origin private file system for simplifying file access:
People interested in the PolyfillingIt is not possible to completely polyfill the File System Access API methods.
We have developed a library called browser-fs-access that uses the File System Access API wherever possible and that falls back to these next best options in all other cases. Security and permissionsThe Chrome team has designed and implemented the File System Access API using the core principles defined in Controlling Access to Powerful Web Platform Features, including user control and transparency, and user ergonomics. Opening a file or saving a new fileA file picker used to open an existing file for reading.When opening a file, the user provides permission to read a file or directory via the file picker. The open file picker can only be shown via a user gesture when served from a secure context. If users change their minds, they can cancel the
selection in the file picker and the site does not get access to anything. This is the same behavior as that of the Similarly, when a web app wants to save a new file, the browser shows the save file picker, allowing the user to specify the name and location of the new file. Since they are saving a new file to the device (versus overwriting an existing file), the file picker grants the app permission to write to the file. Restricted foldersTo help protect users and their data, the browser may limit the user's ability to save to certain folders, for example, core operating system folders like Windows, the macOS Library folders, etc. When this happens, the browser shows a modal prompt and ask the user to choose a different folder. Modifying an existing file or directoryA web app cannot modify a file on disk without getting explicit permission from the user. Permission promptIf a person wants to save changes to a file that they previously granted read access to, the browser shows a modal permission prompt, requesting permission for the site to write changes to disk. The permission request can only be triggered by a user gesture, for example, by clicking a Save button. Prompt shown to users before the browser is granted write permission on an existing file.Alternatively, a web app that edits multiple files, such as an IDE, can also ask for permission to save changes at the time of opening. If the user chooses Cancel, and does not grant write access, the web app cannot save changes to the local file. It should provide an alternative method for the user to save their data, for example by providing a way to "download" the file, saving data to the cloud, etc. TransparencyOmnibox icon indicating the user has granted the website permission to save to a local file.Once a user has granted permission to a web app to save a local file, the browser shows an icon in the URL bar. Clicking on the icon opens a pop-over showing the list of files the user has given access to. The user can easily revoke that access if they choose. Permission persistenceThe web app can continue to save changes to the file without prompting until all tabs for its origin are closed. Once a tab is closed, the site loses all access. The next time the user uses the web app, they will be re-prompted for access to the files. FeedbackWe want to hear about your experiences with the File System Access API. Tell us about the API designIs there something about the API that doesn't work like you expected? Or are there missing methods or properties that you need to implement your idea? Have a question or comment on the security model?
Problem with the implementation?Did you find a bug with Chrome's implementation? Or is the implementation different from the spec?
Planning to use the API?Planning to use the File System Access API on your site? Your public support helps us to prioritize features, and shows other browser vendors how critical it is to support them.
Helpful links
AcknowledgementsThe File System Access API spec was written by Marijn Kruisselbrink. What are the 3 types of permissions?Permission Types
Files and directories can have three types of permissions: read, write, and execute: Someone with read permission may read the contents of a file, or list the contents of a directory.
What is the meaning of chmod 777?The command chmod -R 777 / makes every single file on the system under / (root) have rwxrwxrwx permissions. This is equivalent to allowing ALL users read/write/execute permissions. If other directories such as home, media, etc are under root then those will be affected as well.
What does chmod 644 mean?Permissions of 644 mean that the owner of the file has read and write access, while the group members and other users on the system only have read access.
What permission allows a user to enter the directory and work with directory contents?Permissions for directories
Read permission means that the user may see the contents of a directory (e.g. use ls for this directory.) Write permission means that a user may create files in the directory. Execute permission means that the user may enter the directory (i.e. make it his current directory.)
|