Skip to main content
Mirage behaves the same in Python and TypeScript. This page lists where a TypeScript host differs: Node’s fs patching and FUSE, the browser’s sandbox, and how a call is cancelled. Cloudflare Workers have their own limits, and limits every host shares are on Limits and the shell page.

Node

Node versions

@struktoai/mirage-node needs Node ^22.20 || ^24.12 || >=25. The core and browser packages, run under Node, need 20.18.1+ on 20, or 22+.

patchNodeFs misses ESM imports

patchNodeFs(ws) routes fs calls on mounted paths into the workspace by swapping the functions on CommonJS fs and fs.promises. An ESM named import, import { readFile } from 'node:fs/promises', is bound when the module loads, so it bypasses the patch and reaches the real filesystem. Synchronous calls (readFileSync) refuse a mounted path either way, since the workspace answers asynchronously. Instead:
  • Call ws.shell(...) or ws.vfs directly, from ESM or CommonJS.
  • Mount the workspace as a FUSE folder, so every fs call goes through the kernel.
  • Keep the code that reads the files in CommonJS, require('fs').

A FUSE folder is served on the process’s event loop

A synchronous call on the folder from the process that mounted it, such as readFileSync or execFileSync('cat', ...), blocks the loop that must answer it, and the mount hangs. Use async fs calls and async child processes, or own the mount from a child process. See FUSE.

Browser

A browser workspace runs inside the page, with no kernel, no subprocesses and no Node fs. Every command runs in-process, and python3 runs on Pyodide.
  • No FUSE. A page cannot mount a folder: the browser Workspace takes plain mounts. Use ws.shell(...) and ws.vfs.
  • OPFS quota and eviction. OPFSVFS stores files under the browser’s per-origin quota. Set its capacity so a write fails with Disk quota exceeded before the browser’s own quota does; navigator.storage.estimate() shows the room left. The browser may clear an origin under storage pressure unless the page calls navigator.storage.persist().
  • CORS. A VFS that calls a third-party API from the page fails unless that API allows the page’s origin. Slack and Discord take a proxyUrl to a backend that adds the token; S3, R2 and GCS take presigned URLs; Notion, Box, Dropbox and Google sign in from the page with OAuth.
  • Pyodide caches files for a run. A file Pyodide read stays cached for that run, so an outside edit shows on the next run. Without a worker and either SharedArrayBuffer or Mirage’s service worker, python3 exits 127; see worker and browser setup.
Building an unsupported VFS throws an error.

Cancellation

ws.shell(command, { signal }) cancels a call. A JavaScript promise cannot be cancelled, so:
  • TypeScript fires the signal, gives the line 250 ms to settle, then rejects with an AbortError whose cause is the signal’s reason.
  • A step that ignores the signal, such as a custom handler or a backend call with no signal, can run on after that. Its output is dropped and it cannot change $?, but a write it completes still lands. Built-in commands check the signal between operands, so they start no new read or write.
  • Long commands yield to the event loop as they go, so timers and I/O keep running, but a single synchronous step, such as a large regex match, holds the thread until it returns. To stop arbitrary code hard, run the workspace in a worker or a separate process.
  • A command timeout is a normal result (exit 124), not a cancellation.
  • The signal does not reach background jobs. Stop them with kill.