Gathering detailed insights and metrics for browser-fs-access
Gathering detailed insights and metrics for browser-fs-access
Gathering detailed insights and metrics for browser-fs-access
Gathering detailed insights and metrics for browser-fs-access
File System Access API with legacy fallback in the browser
npm install browser-fs-access
Typescript
Module System
Node Version
NPM Version
99.6
Supply Chain
99.5
Quality
76.2
Maintenance
100
Vulnerability
100
License
Updated on 29 Nov 2024
Minified
Minified + Gzipped
JavaScript (100%)
Cumulative downloads
Total Downloads
Last day
6.8%
Compared to previous day
Last week
-9%
Compared to previous week
Last month
-12.4%
Compared to previous month
Last year
52.2%
Compared to previous year
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.
Try the library in your browser: https://googlechromelabs.github.io/browser-fs-access/demo/.
You can install the module with npm.
1npm install --save browser-fs-access
The module feature-detects support for the File System Access API and only loads the actually relevant code.
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.
1import { 2 fileOpen, 3 directoryOpen, 4 fileSave, 5 supported, 6} from 'https://unpkg.com/browser-fs-access';
You can check supported
to see if the File System Access API is
supported.
1if (supported) { 2 console.log('Using the File System Access API.'); 3} else { 4 console.log('Using the fallback implementation.'); 5}
1const blob = await fileOpen({ 2 mimeTypes: ['image/*'], 3});
1const blobs = await fileOpen({
2 mimeTypes: ['image/*'],
3 multiple: true,
4});
1const blobs = await fileOpen([ 2 { 3 description: 'Image files', 4 mimeTypes: ['image/jpg', 'image/png', 'image/gif', 'image/webp'], 5 extensions: ['.jpg', '.jpeg', '.png', '.gif', '.webp'], 6 multiple: true, 7 }, 8 { 9 description: 'Text files', 10 mimeTypes: ['text/*'], 11 extensions: ['.txt'], 12 }, 13]);
Optionally, you can recursively include subdirectories.
1const blobsInDirectory = await directoryOpen({ 2 recursive: true, 3});
1await fileSave(blob, {
2 fileName: 'Untitled.png',
3 extensions: ['.png'],
4});
Response
that will be streamed1const response = await fetch('foo.png'); 2await fileSave(response, { 3 fileName: 'foo.png', 4 extensions: ['.png'], 5});
Promise<Blob>
that will be streamed.No need to await
the Blob
to be created.
1const blob = createBlobAsyncWhichMightTakeLonger(someData);
2await fileSave(blob, {
3 fileName: 'Untitled.png',
4 extensions: ['.png'],
5});
1// Options are optional. You can pass an array of options, too. 2const options = { 3 // List of allowed MIME types, defaults to `*/*`. 4 mimeTypes: ['image/*'], 5 // List of allowed file extensions (with leading '.'), defaults to `''`. 6 extensions: ['.png', '.jpg', '.jpeg', '.webp'], 7 // Set to `true` for allowing multiple files, defaults to `false`. 8 multiple: true, 9 // Textual description for file dialog , defaults to `''`. 10 description: 'Image files', 11 // Suggested directory in which the file picker opens. A well-known directory, or a file or directory handle. 12 startIn: 'downloads', 13 // By specifying an ID, the user agent can remember different directories for different IDs. 14 id: 'projects', 15 // Include an option to not apply any filter in the file picker, defaults to `false`. 16 excludeAcceptAllOption: true, 17}; 18 19const blobs = await fileOpen(options);
1// Options are optional. 2const options = { 3 // Set to `true` to recursively open files in all subdirectories, defaults to `false`. 4 recursive: true, 5 // Open the directory with `"read"` or `"readwrite"` permission, defaults to `"read"`. 6 mode: 7 // Suggested directory in which the file picker opens. A well-known directory, or a file or directory handle. 8 startIn: 'downloads', 9 // By specifying an ID, the user agent can remember different directories for different IDs. 10 id: 'projects', 11 // Callback to determine whether a directory should be entered, return `true` to skip. 12 skipDirectory: (entry) => entry.name[0] === '.', 13}; 14 15const blobs = await directoryOpen(options);
The module also polyfills a webkitRelativePath
property on returned files in a consistent way, regardless of the underlying implementation.
1// Options are optional. You can pass an array of options, too. 2const options = { 3 // Suggested file name to use, defaults to `''`. 4 fileName: 'Untitled.txt', 5 // Suggested file extensions (with leading '.'), defaults to `''`. 6 extensions: ['.txt'], 7 // Suggested directory in which the file picker opens. A well-known directory, or a file or directory handle. 8 startIn: 'downloads', 9 // By specifying an ID, the user agent can remember different directories for different IDs. 10 id: 'projects', 11 // Include an option to not apply any filter in the file picker, defaults to `false`. 12 excludeAcceptAllOption: true, 13}; 14 15// Optional file handle to save back to an existing file. 16// This will only work with the File System Access API. 17// Get a `FileHandle` from the `handle` property of the `Blob` 18// you receive from `fileOpen()` (this is non-standard). 19const existingHandle = previouslyOpenedBlob.handle; 20 21// Optional flag to determine whether to throw (rather than open a new file 22// save dialog) when `existingHandle` is no longer good, for example, because 23// the underlying file was deleted. Defaults to `false`. 24const throwIfExistingHandleNotGood = true; 25 26// `blobOrPromiseBlobOrResponse` is a `Blob`, a `Promise<Blob>`, or a `Response`. 27await fileSave( 28 blobOrResponseOrPromiseBlob, 29 options, 30 existingHandle, 31 throwIfExistingHandleNotGood 32);
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.
You can see the module in action in the Excalidraw drawing app.
It also powers the SVGcode app that converts raster images to SVGs.
A similar, but more extensive library called native-file-system-adapter is provided by @jimmywarting.
If you are looking for a similar solution for dragging and dropping of files, check out @placemarkio/flat-drop-files.
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.
Apache 2.0.
This is not an official Google product.
No vulnerabilities found.
Reason
no dangerous workflow patterns detected
Reason
no binaries found in the repo
Reason
license file detected
Details
Reason
8 existing vulnerabilities detected
Details
Reason
Found 4/25 approved changesets -- score normalized to 1
Reason
SAST tool is not run on all commits -- score normalized to 1
Details
Reason
0 commit(s) and 1 issue activity found in the last 90 days -- score normalized to 0
Reason
detected GitHub workflow tokens with excessive permissions
Details
Reason
dependency not pinned by hash detected -- score normalized to 0
Details
Reason
no effort to earn an OpenSSF best practices badge detected
Reason
project is not fuzzed
Details
Reason
security policy file not detected
Details
Reason
branch protection not enabled on development/release branches
Details
Score
Last Scanned on 2024-12-02
The Open Source Security Foundation is a cross-industry collaboration to improve the security of open source software (OSS). The Scorecard provides security health metrics for open source projects.
Learn More