Fs Browser Side

Overview

Fs Browser Side is a TypeScript library that brings Node.js FileSystem (fs) capabilities into the client-side environment, built on top of the File System Access API. It provides a clean, promise-based interface for managing files and directories within the browser.

Features

• Promise-first API — All methods return Promise by default, with optional error-first callbacks.
• Stateless path resolution — No mutable internal state; concurrent operations are safe.
• Robust path handling — Proper normalization with ., .., and // support.
• Idiomatic errors — FsError extends Error with typed error codes.
• AsyncGenerator for recursive reads — readdirRecursive yields entries lazily via for await...of.
• Two access modes — User-picked directory (showDirectoryPicker) or OPFS (navigator.storage).

Installation

pnpm add fs-browser-side

Quick Start

import { FsBrowserSide } from 'fs-browser-side';

const fs = new FsBrowserSide();

// Request access to a user-selected directory
if (await fs.getAccess()) {
    // Create nested directories
    await fs.mkdir('/project/src', { recursive: true });

    // Write a text file
    await fs.writeFileText('/project/src/index.ts', 'console.log("hello");');

    // Read it back
    const content = await fs.readFileText('/project/src/index.ts');
    console.log(content); // 'console.log("hello");'

    // List directory contents
    const entries = await fs.readdir('/project/src');
    console.log(entries);
    // [{ name: 'index.ts', type: 'file', path: '/project/src/index.ts' }]
}

OPFS Mode (Origin Private File System)

const fs = new FsBrowserSide({ navigatorMode: true });
await fs.getAccess(); // No user prompt needed

API Reference

new FsBrowserSide(options?)

| Option | Type | Default | Description | |---|---|---|---| | navigatorMode | boolean | false | Use OPFS instead of showDirectoryPicker |

getAccess(): Promise<boolean>

Request file system access. Returns true on success.

readFile(path): Promise<ArrayBuffer>

Read a file as an ArrayBuffer.

readFileText(path): Promise<string>

Read a file as a UTF-8 string.

writeFile(path, data, options?): Promise<void>

Write binary data to a file. Creates the file and parent directories if needed.

| Option | Type | Default | Description | |---|---|---|---| | append | boolean | false | Append to existing content |

writeFileText(path, data, options?): Promise<void>

Write a string to a file. Same options as writeFile.

exists(path): Promise<boolean>

Check if a file or directory exists at the given path.

mkdir(path, options?): Promise<void>

Create a directory.

| Option | Type | Default | Description | |---|---|---|---| | recursive | boolean | false | Create parent directories as needed |

rmdir(path, options?): Promise<void>

Remove a directory. Fails if non-empty unless recursive is true.

| Option | Type | Default | Description | |---|---|---|---| | recursive | boolean | false | Remove contents recursively |

rm(path, options?): Promise<void>

Remove a file or directory entry.

| Option | Type | Default | Description | |---|---|---|---| | recursive | boolean | false | Remove directory contents recursively |

copyFile(src, dest): Promise<void>

Copy a file from src to dest.

rename(src, dest): Promise<void>

Move/rename a file (copy + remove).

readdir(path): Promise<DirEntry[]>

List entries in a directory. Each DirEntry has name, type ('file' | 'directory'), and path.

readdirRecursive(path): AsyncGenerator<DirEntry>

Recursively yield all entries under a directory:

for await (const entry of fs.readdirRecursive('/')) {
    console.log(entry.type, entry.path);
}

Callback Style

Every method also accepts an error-first callback as last argument:

fs.readFileText('/file.txt', (err, content) => {
    if (err) {
        console.error(err.code, err.path);
        return;
    }
    console.log(content);
});

Error Handling

All errors are instances of FsError with a typed code:

import { FsError } from 'fs-browser-side';

try {
    await fs.readFile('/missing.txt');
} catch (err) {
    if (err instanceof FsError) {
        console.log(err.code); // 'NOT_FOUND'
        console.log(err.path); // '/missing.txt'
    }
}

| Code | Description | |---|---| | NO_ACCESS | File system access not granted | | NOT_FOUND | Path does not exist | | ALREADY_EXISTS | Path already exists | | PERMISSION_DENIED | Insufficient permissions | | INVALID_PATH | Invalid path (e.g. resolves above root) | | NOT_A_DIRECTORY | Expected a directory | | NOT_A_FILE | Expected a file | | UNKNOWN | Unexpected error |

Path Utilities

import { PathUtils } from 'fs-browser-side';

PathUtils.normalize('//a/./b/../c');  // '/a/c'
PathUtils.dirname('/a/b/c');          // '/a/b'
PathUtils.basename('/a/b/c');         // 'c'
PathUtils.join('/a', 'b', '../c');    // '/a/c'
PathUtils.segments('/a/b/c');         // ['a', 'b', 'c']

Compatibility

The library requires browser support for the File System Access API. OPFS mode (navigatorMode: true) has broader compatibility than showDirectoryPicker.

Use Cases

• Browser-Based IDE — Read and write project files directly. Demo Github
• Custom CMS — Manage content files without a server.
• Offline-first apps — Persistent storage via OPFS.
• Client-side scraping — Save processed data to local files.
• Photo/file organizer — Manage user files in the browser.

Contributing

You are completely free to contribute to this project! It would be my pleasure to review and accept your Pull Requests or Issues to improve this package.

License

This project is licensed under the MIT License.