Browser FS Access API Ponyfill

Common errors

• SyntaxError: Unexpected token 'export' (when using with Jest or older bundlers)

  cause 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`.

Warnings

• breaking The `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.
• 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.
• gotcha Prior 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.
• gotcha When 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.

Install

• npm install browser-fs-access npm
• yarn add browser-fs-access yarn
• pnpm add browser-fs-access pnpm

Imports

• fileOpen
  wrong:

  const { fileOpen } = require('browser-fs-access');

  correct:

  import { fileOpen } from '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
  wrong:

  const directoryOpen = require('browser-fs-access').directoryOpen;

  correct:

  import { directoryOpen } from 'browser-fs-access';

  Named imports are the standard for this library. Direct CommonJS `require` might lead to issues with bundlers expecting ESM.
• fileSave
  wrong:

  import fileSave from 'browser-fs-access'; // Incorrect default import

  correct:

  import { fileSave } from 'browser-fs-access';

  The library exports multiple named functions. A default import will not provide `fileSave`.
• supported
  wrong:

  import * as fsAccess from 'browser-fs-access'; console.log(fsAccess.supported);

  correct:

  import { supported } from 'browser-fs-access';

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

Quickstart

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