Repository files navigation

ZenFS is a cross-platform library that emulates theNode.js filesystem API.It works using a system of backends, which are used by ZenFS to store and retrieve data.ZenFS can also integrate with other tools.

ZenFS is modular and easily extended. The core includes some built-in backends:

• InMemory: Stores files in-memory. This is cleared when the runtime ends (e.g. a user navigating away from a web page or a Node process exiting)
• CopyOnWrite: Use readable and writable file systems withcopy-on-write.
• Fetch: Downloads files over HTTP with thefetch API
• Port: Interacts with a remote over aMessagePort-like interface (e.g. a worker)
• Passthrough: Use an existingnode:fs interface with ZenFS
• SingleBuffer: A backend contained within a single buffer. Can be used for synchronous multi-threaded operations usingSharedArrayBuffer

ZenFS supports a number of other backends.Many are provided as separate packages under@zenfs.More backends can be defined by separate libraries by extending theFileSystem class and providing aBackend object.

You can find all of the packages available over onNPM. Below is a list of the backends included with some of them:

• @zenfs/archives:Zip,Iso
• @zenfs/cloud:Dropbox,GoogleDrive,S3Bucket
• @zenfs/dom:WebAccess (WebFile System Access API/OPFS),IndexedDB,WebStorage (localStorage/sessionStorage),XML (DOM elements)
• @zenfs/emscripten:Emscripten and a plugin for Emscripten's file system API

As an added bonus, all ZenFS backends support synchronous operations.Additionally, all of the backends included with the core are cross-platform.

For more information, see thedocs.

npm install @zenfs/core

If you're using ZenFS, especially for big projects, please consider supporting the project.Thousands of hours have been dedicated to its development.Your financial support would go a long way toward improving ZenFS and its community.

import{fs}from'@zenfs/core';// You can also use the default exportfs.writeFileSync('/test.txt','You can do this anywhere, including browsers!');constcontents=fs.readFileSync('/test.txt','utf-8');console.log(contents);

A singleInMemory backend is created by default, mounted on/.

You can configure ZenFS to use a different backend and mount multiple backends. It is strongly recommended to do so using theconfigure function.

You can use multiple backends by passing an object toconfigure which maps paths to file systems.

The following example mounts a zip file to/zip, in-memory storage to/tmp, and IndexedDB to/home. Note that/ has the default in-memory backend.

import{configure,InMemory}from'@zenfs/core';import{IndexedDB}from'@zenfs/dom';import{Zip}from'@zenfs/archives';constres=awaitfetch('mydata.zip');awaitconfigure({mounts:{'/mnt/zip':{backend:Zip,data:awaitres.arrayBuffer()},'/tmp':InMemory,'/home':IndexedDB,},});

Note that while you aren't required to use absolute paths for the keys ofmounts, it is a good practice to do so.

Here is an example that mounts theWebStorage backend from@zenfs/dom on/:

import{configureSingle,fs}from'@zenfs/core';import{WebStorage}from'@zenfs/dom';awaitconfigureSingle({backend:WebStorage});if(!fs.existsSync('/test.txt')){fs.writeFileSync('/test.txt','This will persist across reloads!');}constcontents=fs.readFileSync('/test.txt','utf-8');console.log(contents);

The FS promises API is exposed aspromises.

import{configureSingle}from'@zenfs/core';import{exists,writeFile}from'@zenfs/core/promises';import{IndexedDB}from'@zenfs/dom';awaitconfigureSingle({backend:IndexedDB});constexists=awaitexists('/myfile.txt');if(!exists){awaitwriteFile('/myfile.txt','Lots of persistent data');}

If you would like to create backends without configure (e.g. to do something dynamic at runtime), you may do so by importing the backend and callingresolveMountConfig with it.

You can then mount and unmount the backend instance by usingmount andumount.

import{configure,resolveMountConfig,InMemory}from'@zenfs/core';import{IndexedDB}from'@zenfs/dom';import{Zip}from'@zenfs/archives';awaitconfigure({mounts:{'/tmp':InMemory,'/home':IndexedDB,},});fs.mkdirSync('/mnt/zip',{recursive:true});constres=awaitfetch('mydata.zip');constzipfs=awaitresolveMountConfig({backend:Zip,data:awaitres.arrayBuffer()});fs.mount('/mnt/zip',zipfs);// do stuff with the mounted zipfs.umount('/mnt/zip');// finished using the zip

ZenFS includes support for device files. These are designed to follow Linux's device file behavior, for consistency and ease of use. Check out theDevices and Device Drivers documentation for more information.

ZenFS exports a drop-in for Node'sfs module, so you can use it for your bundler of preference using the default export.

A huge thank you todeco.cx for sponsoring ZenFS and helping to make this possible.

You can reach outon Discord or by emailingjp@zenfs.dev