Welcome to the universal-fs docs!

Please note: This is the new home for the universal-fs documentation. These docs are still in beta so there may be issues. If you come across one and think you can fix it click Edit this page. Or if you don't now how to fix the problem open an issue (opens in a new tab) and we will handle it.

If there is ever a contradiction between the beta docs and the stable docs use the jsdoc annotations for the most accurate documentation.

What is universal-fs?

Have you ever needed to do a simple file operation on the client side? Maybe you have a blog with an assets file containing markdown files. You may need to add an edit page function like what wikipedia has so you try something simple.

import fs from "fs";
import {useState} from "react";
 
export default function EditPage(path) {
  const [text, setText] = useState("");
  return (
    <form onSubmit={() => fs.writeFileSync(path, text)}>
      <RichTextEditor
        value={text}
        onChange={(e) => setTextRange(e.target.value)}
      />
      <button>Submit</button>
    </form>
  );
}

You will then find that this does not work. Node fs does not exist in the client. You are now forced add a backend just to use the fs module.

universal-fs aims to solve this in an easy to setup, lightweight, and type safe package.

Why universal-fs?

Comparison	universal-fs	Node fs	vite-plugin-fs
Works outside of Node	✅	❌	✅
Works outside of Vite	✅	✅	❌
Works in prod	✅	✅	❌
Password protected	✅	❌	❌
Multi-language support	✅ ₁	❌	❌
Full Node fs backwards compatibility	✅ ₂	✅	❌
Edge support	✅	❌	❌
Access to other codebases file system	✅	❌	❌
Additional functionality outside of standard Node fs	✅	❌	❌
Custom API generation	✅	❌	❌
Supports all Node fs methods	❌	✅	❌

Gotcha

Server.init() must be called in a Node environment, everything else can be called anywhere.

Additional features

All operations can be aborted by passing an AbortSignal

How can I contribute to universal-fs?

Please see CONTRIBUTING (opens in a new tab) for how to contribute.

I found a security vulnerability in universal-fs! What should I do?

The most important thing to remember is DO NOT REPORT IT PUBLICLY!

Please see SECURITY (opens in a new tab) for how to handle this.

How should I spell universal-fs?

You should always spell it as universal-fs regardless of where it sits in a sentence. When using the name in markdown file do not place it in back ticks.

✅ universal-fs is a integral part of our tech stack.

❌ Universal fs is a integral part of our tech stack.

Note on canary features

Certain features may not be available in stable versions of universal-fs ie: 1.3.4 and instead only exist in canary versions ie canary-1. These features will be marked with a label canary.

Multi-language support is only possible via the relay file server api. Additionally your project still needs to obtain an access token and the server's url.
The whole library is not backwards compatible however, each method works in the exact same way as the Node fs method.

Getting started