• Stars
    star
    1,316
  • Rank 34,265 (Top 0.7 %)
  • Language
    JavaScript
  • License
    Apache License 2.0
  • Created about 4 years ago
  • Updated about 1 month ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

File System Access API with legacy fallback in the browser

Browser-FS-Access

This module allows you to easily use the File System Access API on supporting browsers, with a transparent fallback to the <input type="file"> and <a download> 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.

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.

Importing what you need

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.

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

Feature detection

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

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

Opening a file

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

Opening multiple files

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

Opening files of different MIME types

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'],
  },
]);

Opening all files in a directory

Optionally, you can recursively include subdirectories.

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

Saving a file

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

Saving a Response that will be streamed

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

Saving a Promise<Blob> that will be streamed.

No need to await the Blob to be created.

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

API Documentation

Opening files:

// 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);

Opening directories:

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

Saving files:

// 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<Blob>`, or a `Response`.
await fileSave(
  blobOrResponseOrPromiseBlob,
  options,
  existingHandle,
  throwIfExistingHandleNotGood
);

File operations and exceptions

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 methods, unfortunately, do not support exceptions (albeit there is an HTML issue open for this request). 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.

More Repositories

1

squoosh

Make images smaller using best-in-class codecs, right in the browser.
TypeScript
20,633
star
2

quicklink

⚡️Faster subsequent page-loads by prefetching in-viewport links during idle time
JavaScript
10,937
star
3

ndb

ndb is an improved debugging experience for Node.js, enabled by Chrome DevTools
JavaScript
10,914
star
4

comlink

Comlink makes WebWorkers enjoyable.
TypeScript
10,702
star
5

carlo

Web rendering surface for Node applications
JavaScript
9,326
star
6

ProjectVisBug

FireBug for designers › Edit any webpage, in any state https://a.nerdy.dev/gimme-visbug
JavaScript
5,348
star
7

sw-precache

[Deprecated] A node module to generate service worker code that will precache specific resources so they work offline.
JavaScript
5,236
star
8

react-adaptive-hooks

Deliver experiences best suited to a user's device and network constraints
JavaScript
5,070
star
9

ui-element-samples

A collection of prototyped UI elements
JavaScript
4,101
star
10

sw-toolbox

[Deprecated] A collection of service worker tools for offlining runtime requests
JavaScript
3,621
star
11

webpack-libs-optimizations

Using a library in your webpack project? Here’s how to optimize it
3,358
star
12

critters

🦔 A Webpack plugin to inline your critical CSS and lazy-load the rest.
JavaScript
3,330
star
13

psi

PageSpeed Insights Reporting for Node
JavaScript
3,103
star
14

lighthousebot

Run Lighthouse in CI, as a web service, using Docker. Pass/Fail GH pull requests.
JavaScript
2,236
star
15

bubblewrap

Bubblewrap is a Command Line Interface (CLI) that helps developers to create a Project for an Android application that launches an existing Progressive Web App (PWAs) using a Trusted Web Activity.
TypeScript
2,201
star
16

preload-webpack-plugin

Please use https://github.com/vuejs/preload-webpack-plugin instead.
JavaScript
2,162
star
17

worker-plugin

👩‍🏭 Adds native Web Worker bundling support to Webpack.
JavaScript
1,914
star
18

prerender-loader

📰 Painless universal pre-rendering for Webpack.
JavaScript
1,912
star
19

simplehttp2server

A simple HTTP/2 server for development
Go
1,735
star
20

jsvu

JavaScript (engine) Version Updater
JavaScript
1,698
star
21

size-plugin

Track compressed Webpack asset sizes over time.
JavaScript
1,675
star
22

clooney

Clooney is an actor library for the web. Use workers without thinking about workers.
JavaScript
1,419
star
23

proxx

A game of proximity
TypeScript
1,296
star
24

application-shell

Service Worker Application Shell Architecture
JavaScript
1,169
star
25

dark-mode-toggle

A custom element that allows you to easily put a Dark Mode 🌒 toggle or switch on your site:
JavaScript
1,140
star
26

pwacompat

PWACompat to bring Web App Manifest to older browsers
JavaScript
1,130
star
27

container-query-polyfill

A polyfill for CSS Container Queries
TypeScript
1,106
star
28

idlize

Helper classes and methods for implementing the idle-until-urgent pattern
JavaScript
1,048
star
29

houdini-samples

Demos for different Houdini APIs
JavaScript
967
star
30

css-triggers

A reference for the render impact of mutating CSS properties.
JavaScript
893
star
31

jsbi

JSBI is a pure-JavaScript implementation of the official ECMAScript BigInt proposal.
JavaScript
886
star
32

howto-components

Literate code examples for common UI patterns.
JavaScript
851
star
33

tooling.report

tooling.report a quick way to determine the best build tool for your next web project, or if tooling migration is worth it, or how to adopt a tool's best practice into your existing configuration and code base.
JavaScript
844
star
34

page-lifecycle

PageLifecycle.js is a tiny JavaScript library that allows developers to easily observe Page Lifecycle API state changes cross browser
JavaScript
795
star
35

css-paint-polyfill

CSS Custom Paint / Paint Worklet polyfill with special browser optimizations.
JavaScript
709
star
36

estimator.dev

🧮 Calculate the size and performance impact of switching to modern JavaScript syntax.
JavaScript
667
star
37

web-audio-samples

Web Audio API samples by Chrome Web Audio Team
JavaScript
666
star
38

picture-in-picture-chrome-extension

JavaScript
655
star
39

comlink-loader

Webpack loader to offload modules to Worker threads seamlessly using Comlink.
JavaScript
616
star
40

pwa-wp

WordPress feature plugin to bring Progressive Web Apps (PWA) to Core
PHP
603
star
41

ProgressiveWordPress

A Sample WordPress-based Progressive Web App
JavaScript
570
star
42

gulliver

A PWA directory, focusing on collecting PWA best practices and examples.
JavaScript
549
star
43

web-push-codelab

JavaScript
549
star
44

text-app

A text editor for ChromeOS and Chrome
JavaScript
547
star
45

progressive-tooling

A list of community-built, third-party tools that can be used to improve page performance
JavaScript
545
star
46

wasm-feature-detect

A small library to detect which features of WebAssembly are supported.
JavaScript
518
star
47

svgomg-twa

A sample that project Trusted Web Activities technology to wrap SVGOMG in an Android Application
Shell
512
star
48

web-vitals-report

Measure and report on your Web Vitals data in Google Analytics
JavaScript
495
star
49

text-editor

A text editor build on the Native File System APIs
JavaScript
487
star
50

chrome-for-testing

JavaScript
463
star
51

pptraas.com

Puppeteer as a service
JavaScript
455
star
52

progressive-rendering-frameworks-samples

Samples and demos from the Progressive Rendering I/O talk
JavaScript
407
star
53

wasm-bindgen-rayon

An adapter for enabling Rayon-based concurrency on the Web with WebAssembly.
JavaScript
404
star
54

MiniMobileDeviceLab

A mini mobile web device lab
Objective-C
396
star
55

webm-wasm

webm-wasm lets you create webm videos in JavaScript via WebAssembly.
C++
386
star
56

cronet-sample

A sample for the Cronet library
Java
381
star
57

link-to-text-fragment

Browser extension that allows for linking to arbitrary text fragments.
JavaScript
371
star
58

webpack-training-project

A training project for learning Webpack optimizations
JavaScript
368
star
59

pinch-zoom

TypeScript
366
star
60

samesite-examples

Examples of using the SameSite cookie attribute in a variety of language, libraries, and frameworks.
HTML
365
star
61

airhorn

Air horn
JavaScript
361
star
62

buffer-backed-object

Buffer-backed objects in JavaScript.
JavaScript
349
star
63

first-input-delay

A JavaScript library for measuring First Input Delay (FID) in the browser.
JavaScript
347
star
64

AutoWebPerf

AutoWebPerf provides a flexible and scalable framework for running web performance audits with arbitrary audit tools including PageSpeedInsights, WebPageTest and more.
JavaScript
345
star
65

tti-polyfill

Time-to-interactive polyfill
JavaScript
333
star
66

react-shrine

"Shrine" Progressive Web App sample built with React
JavaScript
331
star
67

dynamic-import-polyfill

A fast, tiny polyfill for dynamic import() that works in all module-supporting browsers
JavaScript
320
star
68

wasi-fs-access

This is a demo shell powered by WebAssembly, WASI, Asyncify and File System Access API.
TypeScript
293
star
69

native-url

Node's url module implemented using the built-in URL API.
JavaScript
284
star
70

two-up

TypeScript
270
star
71

adaptive-loading

Demos for Adaptive Loading - differentially deliver fast, lighter experiences for users on slow networks & devices
JavaScript
266
star
72

so-pwa

A progressive web app to read Stack Overflow content.
JavaScript
255
star
73

import-from-worker

It’s like import(), but runs the module in a worker.
JavaScript
246
star
74

sample-pie-shop

Example e-commerce site to explore PWA (Progressive Web App) use cases.
JavaScript
236
star
75

file-drop

A simple file drag and drop custom-element
TypeScript
226
star
76

form-troubleshooter

TypeScript
213
star
77

postcss-jit-props

A CSS custom property helper based on PostCSS. Supply a pool of variables and this plugin will add them to the stylesheet as they are used.
JavaScript
203
star
78

serial-terminal

Demo application for the Web Serial API.
TypeScript
191
star
79

audioworklet-polyfill

🔊 Polyfill AudioWorklet using the legacy ScriptProcessor API.
JavaScript
190
star
80

http2-push-manifest

Generate a list of static resources for http2 push.
JavaScript
187
star
81

pointer-tracker

Track mouse/touch/pointer events for a given element.
TypeScript
183
star
82

pr-bot

🤖 Compare your base branch to a pull request and run plugins over it to view differences
JavaScript
179
star
83

discovery

Discoveries on Sustainable Loading research
177
star
84

imagecapture-polyfill

MediaStream ImageCapture polyfill. Take photos from the browser as easy as .takePhoto().then(processPhoto)
JavaScript
176
star
85

tasklets

JavaScript
176
star
86

credential-management-sample

Credential Management Sample
HTML
157
star
87

houdini.how

A community-driven gathering place for CSS Houdini worklets and resources.
JavaScript
150
star
88

wasm-av1

Port of the AV1 Video codec to WebAssembly
C
150
star
89

perf-track

Tracking framework performance and usage at scale
Svelte
148
star
90

kv-storage-polyfill

A polyfill for the kv-storage built-in module.
JavaScript
145
star
91

wadb

A TypeScript implementation of the Android Debug Bridge(ADB) protocol over WebUSB
TypeScript
143
star
92

telnet-client

TypeScript
142
star
93

pwa-workshop-codelab

JavaScript
142
star
94

http2push-gae

Drop-in HTTP2 push on App Engine
HTML
140
star
95

chromeos_smart_card_connector

Smart Card Connector App for Chrome OS
C++
133
star
96

snapshot

TypeScript
133
star
97

devwebfeed

Firehose of team++ resources
JavaScript
130
star
98

sample-currency-converter

A sample currency conversion Progressive Web App
JavaScript
129
star
99

extension-manifest-converter

Python
119
star
100

json-parse-benchmark

Benchmark comparing JSON.parse vs. equivalent JavaScript literals across JavaScript engines.
JavaScript
119
star