crossbind
GitHub

Files

C++ wants paths. What a path means depends on where the module runs: the real disk in Node.js, an origin-private store or memory in the browser, and the isolate's memory on the edge.

The two browser roots

/opfs/<app>/
The Origin Private File System: files survive a reload. It needs fs.opfs on (the default in mt builds), the module in a worker, and a browser that supports it.
/memfs/<app>/
Memory: files last for the tab's session. Always there.

<app> is general.name from crossbind.config.js. Browsers give OPFS its synchronous file access only in workers, so:

OPFS requires useWorker: true
Mounting /opfs/... on the page thread throws. Where the browser has no OPFS, or blocks it, the path falls back to /memfs/ and the reason is logged: writes keep working but no longer persist.
src/main.js
const m = await initNative({
useWorker: true, // the browser default; OPFS needs it
fs: { opfs: true }, // the default in mt builds
});
 
// Anything under /opfs/<app>/ is still there after a reload.
m.FS.writeFile('/opfs/myapp/data.bin', new Uint8Array([1, 2, 3]));

Module helpers

m.FS
The virtual filesystem: mkdirTree, writeFile, readFile and the rest.
m.getDefaultPath()
Returns /opfs or /memfs, for the current configuration.
m.getFinalPath(path)
Checks a path, falling back when OPFS is unavailable.
m.getRandomPath(startPath?)
Creates <start>/<app>/automounted/<random> and returns it.
m.autoMountFiles(files, parentPath?)
Streams File[] into the filesystem and returns their paths.
m.getFileBytes(path)
A file's contents as a Uint8Array.
m.getFileList(startPath?)
A recursive listing as [{ path, size }].
JavaScript
m.FS.mkdirTree('/memfs/myapp/cache');
m.FS.writeFile('/memfs/myapp/cache/data.bin', new Uint8Array([1, 2, 3]));
const bytes = m.FS.readFile('/memfs/myapp/cache/data.bin');
m.FS exists only after init
Use it after initNative() resolves, or in onRuntimeInitialized.

Files the user picked

A File from an <input type=file> has no path your C++ can open. autoMountFiles streams it in and returns paths that work, with no size limit beyond storage.

src/main.js
const input = document.querySelector('input[type=file]');
 
input.addEventListener('change', async () => {
const paths = await m.autoMountFiles(Array.from(input.files));
// e.g. ['/opfs/myapp/automounted/123456/photo.jpg']
for (const path of paths) {
m.processImage(path);
}
});

Pass a second argument to mount into a known folder instead of a random one: await m.autoMountFiles(files, '/opfs/myapp/uploads').

Getting results back to JavaScript

C++ writes to a path; JavaScript reads the bytes back:

src/main.js
m.processImage('/opfs/myapp/uploads/photo.jpg');
 
const bytes = m.getFileBytes('/opfs/myapp/uploads/photo.processed.jpg');
const url = URL.createObjectURL(new Blob([bytes], { type: 'image/jpeg' }));
imgEl.src = url;

Per-runtime cheat sheet

Browser, useWorker: false
/opfs throws; /memfs lasts for the tab's session.
Browser, in a worker (the default)
/opfs persists in mt builds, or falls back to /memfs; /memfs lasts for the tab's session.
Node.js
m.FS reads and writes the real disk; /memfs is a folder in memory.
Cloudflare Workers and other edge runtimes
m.FS lives in memory and is gone with the isolate; there is no /opfs.
React Native
C++ opens real files in the app's sandbox; there is no m.FS.

Pitfalls

  • No worker, no OPFS. Mounting /opfs on the page thread throws: keep the worker on (the browser default), or write under /memfs/.
  • OPFS off. An /opfs/... path throws too while OPFS is off: the default in st builds, or with fs: { opfs: false }.
  • A path outside the app folder. Writes to /memfs/foo work but sit outside /memfs/<app>/, which is cleaned up on terminate.
  • Expecting OPFS to cross origins. It does not: files written by one origin are invisible to another.
Type to search every guide page and section.
↑↓ navigate↵ openesc close