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.opfson (the default inmtbuilds), 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.Module helpers
m.FS- The virtual filesystem:
mkdirTree,writeFile,readFileand the rest. m.getDefaultPath()- Returns
/opfsor/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 }].
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.
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:
Per-runtime cheat sheet
- Browser,
useWorker: false /opfsthrows;/memfslasts for the tab's session.- Browser, in a worker (the default)
/opfspersists inmtbuilds, or falls back to/memfs;/memfslasts for the tab's session.- Node.js
m.FSreads and writes the real disk;/memfsis a folder in memory.- Cloudflare Workers and other edge runtimes
m.FSlives 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
/opfson 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 instbuilds, or withfs: { opfs: false }. - A path outside the app folder. Writes to
/memfs/foowork 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.