@codetoy-io/files.web

A TypeScript library for browser file operations using the Origin Private File System (OPFS) API.

Heavy operations (upload, save, move, delete) run in a dedicated Web Worker to avoid blocking the main thread.

Requirements

• A browser that supports the File System Access API (navigator.storage.getDirectory)
• A Vite-based project (the worker is loaded via new URL('./worker.js', import.meta.url))

Installation

pnpm add @codetoy-io/files.web

Usage

import {
    uploadFile,
    saveTextFile,
    moveFile,
    moveFolder,
    deleteFile,
    deleteFolder,
    fileExists,
    listEntriesDetailed,
} from '@codetoy-io/files.web';
import type { Entry } from '@codetoy-io/files.web';

// List all files in the root OPFS directory
const root = await navigator.storage.getDirectory();
const entries: Record<string, Entry> = await listEntriesDetailed(root);

// Write a text file
await saveTextFile('console.log("hello")', '/src/main.ts');

// Upload a File object
await uploadFile(file, '/assets/image.png');

// Move or rename
await moveFile('/src/old.ts', '/src/new.ts');
await moveFolder('/old-dir', '/new-dir');

// Delete
await deleteFile('/src/main.ts');
await deleteFolder('/old-dir');

// Check existence
const exists = await fileExists('/src/main.ts');

Entry type

listEntriesDetailed returns a tree of Entry objects — pure data, no UI state:

interface Entry {
    name: string;
    kind: 'file' | 'directory';
    relativePath: string;
    handle: FileSystemFileHandle | FileSystemDirectoryHandle;
    entries?: Record<string, Entry>; // only present for directories
    size?: number;
    type?: string;
    lastModified?: number;
}

Building

pnpm build