Registry / web-framework / browser-fs-access

browser-fs-access

JSON →
library0.38.0jsnpmunverified

browser-fs-access is a JavaScript library that provides a simplified, progressive enhancement approach to using the File System Access API in web browsers. It acts as a ponyfill, meaning it offers a consistent API surface while transparently falling back to older, less capable methods like `<input type="file">` and `<a download>` on browsers that do not fully support the File System Access API. This ensures broad compatibility while leveraging modern capabilities where available. The library is currently at version 0.38.0 and maintains an active release cadence, frequently publishing updates and fixes, often on a monthly basis. Key differentiators include its robust fallback mechanism, its origin from GoogleChromeLabs, and its focus on developer ergonomics by abstracting away the complexities of feature detection and legacy API interactions. It ships with TypeScript types for improved developer experience.

npm install browser-fs-access
INSTALL
IMPORT
SIG · BROWSER-FS-ACCESS
B
browser-fs-access
web-frameworkjavascriptv0.38.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

fileOpen
import { fileOpen } from 'browser-fs-access';
const { fileOpen } = require('browser-fs-access');
The library is ESM-first and primarily consumed via `import` statements. While bundlers can often handle CommonJS, `require()` is not the idiomatic way to use this library in modern browser environments.
directoryOpen
import { directoryOpen } from 'browser-fs-access';
const directoryOpen = require('browser-fs-access').directoryOpen;
Named imports are the standard for this library. Direct CommonJS `require` might lead to issues with bundlers expecting ESM.
fileSave
import { fileSave } from 'browser-fs-access';
import fileSave from 'browser-fs-access'; // Incorrect default import
The library exports multiple named functions. A default import will not provide `fileSave`.
supported
import { supported } from 'browser-fs-access';
import * as fsAccess from 'browser-fs-access'; console.log(fsAccess.supported);
`supported` is a named export. While `import * as` works, direct named import is more concise for feature detection.
FileSystemAccessTypes
import type { FileSystemAccessTypes } from 'browser-fs-access';
TypeScript types are shipped with the package for all exported functions and relevant interfaces.

This quickstart demonstrates opening single and multiple files, recursively opening a directory, and saving a file, along with feature detection and error handling using the `browser-fs-access` library.

import { fileOpen, directoryOpen, fileSave, supported } from 'browser-fs-access'; async function performFileOperations() { if (supported) { console.log('Using the File System Access API.'); } else { console.log('Using the fallback implementation (e.g., <input type="file"> or <a download>).'); } try { // Open a single image file with specific options const imageBlob = await fileOpen({ mimeTypes: ['image/*'], extensions: ['.png', '.jpg', '.jpeg'], description: 'Select an image file', multiple: false, startIn: 'pictures' }); console.log(`Opened image: ${imageBlob.name} (type: ${imageBlob.type}, size: ${imageBlob.size} bytes)`); // Open multiple text files from a directory, recursively const filesInDir = await directoryOpen({ recursive: true, mode: 'read', mimeTypes: ['text/*', 'application/json'], extensions: ['.txt', '.md', '.json'] }); console.log(`Opened ${filesInDir.length} files in directory. First file: ${filesInDir[0]?.name || 'N/A'}`); // Save a new text file created from a Blob const textContent = 'This is a test file saved using browser-fs-access.\nHello, world!'; const textBlob = new Blob([textContent], { type: 'text/plain' }); await fileSave(textBlob, { fileName: 'my-document.txt', extensions: ['.txt'], description: 'My Text Document', startIn: 'documents' }); console.log('Successfully saved my-document.txt'); } catch (error) { if (error.name === 'AbortError') { console.log('User cancelled the file picker.'); } else { console.error('File operation failed:', error); } } } performFileOperations();
Debug
Known issues
breakingThe `directoryOpen()` function's return value for empty directories changed. When the File System Access API is supported and a directory is empty, the function now returns `[directoryHandle]` instead of an empty array `[]`. This is to provide access to the directory handle itself.
fix
Update your code to expect `[directoryHandle]` for empty directories when the File System Access API is active, and handle cases where `files.length` might be 1 but represent an empty directory, or check the `kind` property of the handle.
affects: >=0.32.1
gotcha`browser-fs-access` is a ponyfill, not a polyfill. This means its behavior, user experience (UI for file pickers), and capabilities will differ significantly between browsers fully supporting the File System Access API and those relying on legacy fallbacks. Always test your application across all target browsers to understand these UX variations.
fix
Design your application's UI and workflow to gracefully handle the different user interactions and capabilities offered by the native File System Access API versus the fallback `<input type="file">` and `<a download>` methods. Use the `supported` export for feature detection.
affects: >=0.1.0
gotchaPrior to versions 0.33.0 and 0.35.0, there were known issues with proper detection and use of the File System Access API within same-origin and cross-origin iframes, sometimes leading to erroneous fallback usage. While fixed, complex embedding scenarios might still require careful testing.
fix
Ensure you are using `browser-fs-access` version 0.35.0 or newer when working with iframes to benefit from the detection and functionality fixes. Thoroughly test file operations in your specific iframe contexts.
affects: <0.35.0
gotchaWhen using `fileSave` to overwrite an existing file, the File System Access API will prompt the user for permission. In legacy fallback mode, this functionality is not available, and typically triggers a new download instead of overwriting, leading to a different user experience.
fix
Inform users about the expected behavior for saving, especially regarding overwriting existing files, and differentiate between browsers with and without full File System Access API support.
affects: >=0.1.0
Errors
Common errors & fixes
SyntaxError: Unexpected token 'export' (when using with Jest or older bundlers)
The library is distributed as an ESM module, and older versions of Jest or some bundler configurations might not correctly transpile `export` syntax in `node_modules`.
fix
Configure Jest's `transformIgnorePatterns` to include `browser-fs-access` for transformation, e.g., `"transformIgnorePatterns": ["node_modules/(?!browser-fs-access)"]`. For other bundlers, ensure your configuration correctly handles ESM in `node_modules`.
Upgrade
Version history
0.38.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
5 hits · last 30 days
node
4
OpenAI (training)
1
Resources
browser-fs-access — npm install browser-fs-access · libregistry