Skip to content
Native File System API with legacy fallback in the browser
JavaScript Shell
Branch: master
Clone or download
Latest commit b972e9a Feb 17, 2020
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github/workflows Add compressed action Jan 30, 2020
demo Remove superfluous code line Feb 17, 2020
src Add folder listing Feb 17, 2020
.gitignore Initial commit Jan 21, 2020
CONTRIBUTING.md Create CONTRIBUTING.md Feb 10, 2020
LICENSE Initial commit Jan 21, 2020
README.md Add demo link Feb 17, 2020
build.sh Update build.sh Feb 10, 2020
package-lock.json Fix path Feb 12, 2020
package.json Remove superfluous code line Feb 17, 2020

README.md

Browser-NativeFS

This module allows you to easily use the Native File System API on supporting browsers, with a transparent fallback to the <input type="file"> and <a download> legacy methods.

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

Live Demo

See the library in action: https://browser-nativefs.glitch.me/.

Usage Example

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

// The imported methods will use the Native
// File System API or a fallback implementation.
import {
  fileOpen,
  directoryOpen,
  fileSave,
} from 'https://unpkg.com/browser-nativefs';

(async () => {
  // Open a file.
  const blob = await fileOpen({
    mimeTypes: ['image/*'],
  });

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

  // Open all files in a directory,
  // recursively including subdirectories.
  const blobsInDirectory = await directoryOpen({
    recursive: true
  });

  // Save a file.
  await fileSave(blob, {
    fileName: 'Untitled.png',
  });
})();

API Documentation

Opening files:

// Options are optional.
const options = {
  // List of allowed MIME types, defaults to `*/*`.
  mimeTypes: ['image/*'],
  // List of allowed file extensions, 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',
};

const blobs = await fileOpen(options);

Opening directories:

Note that there are some differences between the Native File System API and the fallback approach <input type="file" webkitdirectory multiple>. Namely, the Native File System API currently doesn't provide useful relative path info as webkitRelativePath did, so you need to keep track of paths yourself.

// Options are optional.
const options = {
  // Set to `true` for allowing multiple directories, defaults to `false`.
  multiple: true,
  // Set to `true` to recursively open files in all subdirectories,
  // defaults to `false`.
  recursive: true,
};

const blobs = await directoryOpen(options);

Saving files:

// Options are optional.
const options = {
   // Suggested file name to use, defaults to `''`.
  fileName: 'Untitled.txt',
};

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

await fileSave(someBlob, options, handle);

Browser-NativeFS in Action

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

excalidraw

Acknowledgements

Thanks to @developit for improving the dynamic module loading and @dwelle for the helpful feedback and issue reports.

License and Note

Apache 2.0.

This is not an official Google product.

You can’t perform that action at this time.