Browser-FS-Access

This module allows you to easily use the
File System Access API on supporting browsers,
with a transparent fallback to the and legacy methods.
This library is a ponyfill.

Read more on the background of this module in my post
Progressive Enhancement In the Age of Fugu APIs.

Live Demo

Try the library in your browser: https://googlechromelabs.github.io/browser-fs-access/demo/.

Installation

You can install the module with npm.

``bash
npm install --save browser-fs-access
`

Usage Examples

The module feature-detects support for the File System Access API and
only loads the actually relevant code.

$3

Import only the features that you need. In the code sample below, all
features are loaded. The imported methods will use the File System
Access API or a fallback implementation.

`js
import {
fileOpen,
directoryOpen,
fileSave,
supported,
} from 'https://unpkg.com/browser-fs-access';
`

$3

You can check supported to see if the File System Access API is
supported.

`js
if (supported) {
console.log('Using the File System Access API.');
} else {
console.log('Using the fallback implementation.');
}
`

$3

`js
const blob = await fileOpen({
mimeTypes: ['image/*'],
});
`

$3

`js
const blobs = await fileOpen({
mimeTypes: ['image/*'],
multiple: true,
});
`

$3

`js
const blobs = await fileOpen([
{
description: 'Image files',
mimeTypes: ['image/jpg', 'image/png', 'image/gif', 'image/webp'],
extensions: ['.jpg', '.jpeg', '.png', '.gif', '.webp'],
multiple: true,
},
{
description: 'Text files',
mimeTypes: ['text/*'],
extensions: ['.txt'],
},
]);
`

$3

Optionally, you can recursively include subdirectories.

`js
const blobsInDirectory = await directoryOpen({
recursive: true,
});
`

$3

`js
await fileSave(blob, {
fileName: 'Untitled.png',
extensions: ['.png'],
});
`

$3

`js
const response = await fetch('foo.png');
await fileSave(response, {
fileName: 'foo.png',
extensions: ['.png'],
});
`

$3

No need to await the Blob to be created.

`js
const blob = createBlobAsyncWhichMightTakeLonger(someData);
await fileSave(blob, {
fileName: 'Untitled.png',
extensions: ['.png'],
});
`

API Documentation

$3

`js
// Options are optional. You can pass an array of options, too.
const options = {
// List of allowed MIME types, defaults to /.
mimeTypes: ['image/*'],
// List of allowed file extensions (with leading '.'), defaults to ''.
extensions: ['.png', '.jpg', '.jpeg', '.webp'],
// Set to true for allowing multiple files, defaults to false.
multiple: true,
// Textual description for file dialog , defaults to ''.
description: 'Image files',
// Suggested directory in which the file picker opens. A well-known directory, or a file or directory handle.
startIn: 'downloads',
// By specifying an ID, the user agent can remember different directories for different IDs.
id: 'projects',
// Include an option to not apply any filter in the file picker, defaults to false.
excludeAcceptAllOption: true,
};

const blobs = await fileOpen(options);
`

$3

`js
// Options are optional.
const options = {
// Set to true to recursively open files in all subdirectories, defaults to false.
recursive: true,
// Open the directory with "read" or "readwrite" permission, defaults to "read".
mode:
// Suggested directory in which the file picker opens. A well-known directory, or a file or directory handle.
startIn: 'downloads',
// By specifying an ID, the user agent can remember different directories for different IDs.
id: 'projects',
// Callback to determine whether a directory should be entered, return true to skip.
skipDirectory: (entry) => entry.name[0] === '.',
};

const blobs = await directoryOpen(options);
`

The module also polyfills a webkitRelativePath property on returned files in a consistent way, regardless of the underlying implementation.

$3

`js
// Options are optional. You can pass an array of options, too.
const options = {
// Suggested file name to use, defaults to ''.
fileName: 'Untitled.txt',
// Suggested file extensions (with leading '.'), defaults to ''.
extensions: ['.txt'],
// Suggested directory in which the file picker opens. A well-known directory, or a file or directory handle.
startIn: 'downloads',
// By specifying an ID, the user agent can remember different directories for different IDs.
id: 'projects',
// Include an option to not apply any filter in the file picker, defaults to false.
excludeAcceptAllOption: true,
};

// Optional file handle to save back to an existing file.
// This will only work with the File System Access API.
// Get a FileHandle from the handle property of the Blob
// you receive from fileOpen() (this is non-standard).
const existingHandle = previouslyOpenedBlob.handle;

// Optional flag to determine whether to throw (rather than open a new file
// save dialog) when existingHandle is no longer good, for example, because
// the underlying file was deleted. Defaults to false.
const throwIfExistingHandleNotGood = true;

// blobOrPromiseBlobOrResponse is a Blob, a Promise, or a Response.
await fileSave(
blobOrResponseOrPromiseBlob,
options,
existingHandle,
throwIfExistingHandleNotGood
);
`

$3

The File System Access API supports exceptions, so apps can throw when problems occur (permissions
not granted, out of disk space,…), or when the user cancels the dialog. The legacy save method,
unfortunately, doesn't support exceptions. If your app depends on exceptions, see the file
index.d.ts for the
documentation of the legacySetup parameter.

Browser-FS-Access in Action

You can see the module in action in the Excalidraw drawing app.

!excalidraw

It also powers the SVGcode app that converts raster images to SVGs.

!svgcode

Alternatives

A similar, but more extensive library called
native-file-system-adapter
is provided by @jimmywarting.

Ecosystem

If you are looking for a similar solution for dragging and dropping of files,
check out @placemarkio/flat-drop-files.

Acknowledgements

Thanks to @developit
for improving the dynamic module loading
and @dwelle for the helpful feedback,
issue reports, and the Windows build fix.
Directory operations were made consistent regarding webkitRelativePath`
and parallelized and sped up significantly by
@RReverser.
The TypeScript type annotations were initially provided by
@nanaian.
Dealing correctly with cross-origin iframes was contributed by
@nikhilbghodke and
@kbariotis.
The exception handling of the legacy methods was contributed by
@jmrog.
The streams and blob saving was improved by @tmcw.

License and Note

Apache 2.0.

This is not an official Google product.