Question about OPFS support

[kachurun]

Hi @james-pre!

I’ve been working on a project that needs persistent file storage in the browser, so I chose OPFS. I couldn’t find a backend for zen-fs, so I built a workaround — but quickly ran into Safari issues like createWritable missing, structuredClone problems with FileHandle, and others. That’s basically the blocker: every library that tries to use OPFS runs into the same Safari issues, making it impossible to use in production.

That led me to create opfs-worker - OPFS adapter based on web workers. It runs createSyncHandle inside a dedicated worker (bundled as a data URI so no static files are needed) and exposes low-level FS ops (open, read, write, close, fstat, mkdir, etc.) to the main thread.

I’m also planning to use it to fix the same issues in browser-only Theia IDE. Since that PR isn’t merged yet, I still have flexibility to adjust or even rewrite the adapter’s internals.

Now I’m wondering if it would make sense to contribute this as a zen-fs backend that wraps opfs-worker. That way, zen-fs would gain proper OPFS support (including Safari), and I could simplify my library by dropping the extra facade layer I currently maintain.

What do you think about it?

[james-pre]

Hey @kachurun, thanks for suggesting the idea. ZenFS actually does have a backend for OPFS: WebAccess from @zenfs/dom. I recommend you take a look at it. Please let me know what you think, you could really contribute to it.

[kachurun]

Not in safari 😉

[james-pre]

Access API is similar but not exactly the same as OPFS

The File System Access API is actually a superset of the File System API, the latter of which is used by the origin private file system^(source). This means any APIs using the File System API (including OPFS) are compatibile with the File System Access API, and therefore with the WebAccess backend.

Not in safari

I took a look at the browser compatibility table for the File System API (which is implemented/used by OPFS). It appears that Safari doesn't support FileSystemFileHandle.createWritable or FileSystemWritableFileStream yet, which are required for writing to files (though this is coming in Safari 26). There isn't any way to work around this.

[kachurun]

There isn't any way to work around this.

Not exactly right. As I mentioned before, you can use syncHandler and it works

[james-pre]

You're correct in that FileSystemSyncAccessHandle can be used for writing, however it can't be used everywhere the async writing can:

This class is only accessible inside dedicated Web Workers (so that its methods do not block execution on the main thread) for files within the origin private file system, which is not visible to end-users.

Specifically:

• The main thread, shared workers, and service workers can't use it
• It can only be used with the OPFS, while the async writable can be used with handles obtained from window.showDirectoryPicker() and DataTransferItem.getAsFileSystemHandle().

Creating a FileSystemSyncAccessHandle takes an exclusive lock on the file associated with the file handle. This prevents the creation of further FileSystemSyncAccessHandles or FileSystemWritableFileStreams for the file until the existing access handle is closed.

It's also worth noting that we can't open a writable stream for the file while a sync handle is held.

The sync handle does provide a more convenient API though. I may look at adding support for using sync handles to enable more use cases (e.g. through a flag on the backend's config). If anyone is interested in seeing proper synchronous operation support in WebAccess when used from a worker, please add a 👍🏻 to this message.

[kachurun]

dedicated Web Workers

Yes! That's why I'm doing this weird stuff with the facade and the actual implementation inside the worker

It's also worth noting that we can't open a writable stream for the file while a sync handle is held.

I got tons of errors caused by that while working on improving Theia. So I just wrapped all my read/write operations with withLock, which is just a navigator.locks.request wrapper.

Anyway, all of this works great, and I even tested how memory-efficient it is by uploading 500–1000 MB files in the OPFS. It works great with streams.