{"id":23799400,"url":"https://github.com/zen-fs/core","last_synced_at":"2026-04-03T00:25:38.661Z","repository":{"id":199601319,"uuid":"703267037","full_name":"zen-fs/core","owner":"zen-fs","description":"A filesystem, anywhere.","archived":false,"fork":false,"pushed_at":"2025-05-12T19:50:35.000Z","size":13112,"stargazers_count":242,"open_issues_count":5,"forks_count":31,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-05-12T20:07:47.862Z","etag":null,"topics":["browserfs","filesystem","zenfs"],"latest_commit_sha":null,"homepage":"https://zenfs.dev/core/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zen-fs.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":"contributing.md","funding":".github/funding.yml","license":"license.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/codeowners","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["james-pre"]}},"created_at":"2023-10-10T23:27:35.000Z","updated_at":"2025-05-12T19:50:38.000Z","dependencies_parsed_at":"2023-10-16T06:34:55.898Z","dependency_job_id":"214beea4-6e67-4313-95f9-ca04bff07c2c","html_url":"https://github.com/zen-fs/core","commit_stats":null,"previous_names":["browser-fs/core","zen-fs/core"],"tags_count":193,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zen-fs%2Fcore","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zen-fs%2Fcore/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zen-fs%2Fcore/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zen-fs%2Fcore/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zen-fs","download_url":"https://codeload.github.com/zen-fs/core/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254384987,"owners_count":22062422,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["browserfs","filesystem","zenfs"],"created_at":"2025-01-01T21:16:12.073Z","updated_at":"2026-04-03T00:25:38.579Z","avatar_url":"https://github.com/zen-fs.png","language":"TypeScript","funding_links":["https://github.com/sponsors/james-pre"],"categories":[],"sub_categories":[],"readme":"# ZenFS\n\nZenFS is a cross-platform library that emulates the [NodeJS filesystem API](http://nodejs.org/api/fs.html). It works using a system of backends, which are used by ZenFS to store and retrieve data. ZenFS can also integrate with other tools.\n\n## Backends\n\nZenFS is modular and extensible. The core includes some built-in backends:\n\n- `InMemory`: Stores files in-memory. This is cleared when the runtime ends (e.g. a user navigating away from a web page or a Node process exiting)\n- `CopyOnWrite`: Use readable and writable file systems with ([copy-on-write](https://en.wikipedia.org/wiki/Copy-on-write)).\n- `Fetch`: Downloads files over HTTP with the `fetch` API\n- `Port`: Interacts with a remote over a `MessagePort`-like interface (e.g. a worker)\n- `Passthrough`: Use an existing `node:fs` interface with ZenFS\n- `SingleBuffer`: A backend contained within a single buffer. Can be used for synchronous multi-threaded operations using `SharedArrayBuffer`\n\nZenFS supports a number of other backends. Many are provided as separate packages under `@zenfs`. More backends can be defined by separate libraries by extending the `FileSystem` class and providing a `Backend` object.\n\nYou can find all of the packages available over on [NPM](https://www.npmjs.com/org/zenfs).\n\nAs an added bonus, all ZenFS backends support synchronous operations. All of the backends included with the core are cross-platform.\n\nFor more information, see the [docs](https://zenfs.dev/core).\n\n## Installing\n\n```sh\nnpm install @zenfs/core\n```\n\nIf you're using ZenFS, especially for big projects, please consider supporting the project. Thousands of hours have been dedicated to its development. Your acknowledgment or financial support would go a long way toward improving ZenFS and its community.\n\n## Usage\n\n```js\nimport { fs } from '@zenfs/core'; // You can also use the default export\n\nfs.writeFileSync('/test.txt', 'You can do this anywhere, including browsers!');\n\nconst contents = fs.readFileSync('/test.txt', 'utf-8');\nconsole.log(contents);\n```\n\n#### Using different and/or multiple backends\n\nA single `InMemory` backend is created by default, mounted on `/`.\n\nYou can configure ZenFS to use a different backend and mount multiple backends. It is strongly recommended to do so using the `configure` function.\n\nYou can use multiple backends by passing an object to `configure` which maps paths to file systems.\n\nThe following example mounts a zip file to `/zip`, in-memory storage to `/tmp`, and IndexedDB to `/home`. Note that `/` has the default in-memory backend.\n\n```js\nimport { configure, InMemory } from '@zenfs/core';\nimport { IndexedDB } from '@zenfs/dom';\nimport { Zip } from '@zenfs/archives';\n\nconst res = await fetch('mydata.zip');\n\nawait configure({\n\tmounts: {\n\t\t'/mnt/zip': { backend: Zip, data: await res.arrayBuffer() },\n\t\t'/tmp': InMemory,\n\t\t'/home': IndexedDB,\n\t}\n};\n```\n\nNote that while you aren't required to use absolute paths for the keys of `mounts`, it is a good practice to do so.\n\n\u003e [!TIP]\n\u003e When configuring a mount point, you can pass in\n\u003e\n\u003e 1. A `Backend` object, if the backend has no required options\n\u003e 2. An object that has the options accepted by the backend and a `backend` property which is a `Backend` object\n\u003e 3. A `FileSystem` instance\n\nHere is an example that mounts the `WebStorage` backend from `@zenfs/dom` on `/`:\n\n```js\nimport { configureSingle, fs } from '@zenfs/core';\nimport { WebStorage } from '@zenfs/dom';\n\nawait configureSingle({ backend: WebStorage });\n\nif (!fs.existsSync('/test.txt')) {\n\tfs.writeFileSync('/test.txt', 'This will persist across reloads!');\n}\n\nconst contents = fs.readFileSync('/test.txt', 'utf-8');\nconsole.log(contents);\n```\n\n#### FS Promises\n\nThe FS promises API is exposed as `promises`.\n\n```js\nimport { configureSingle } from '@zenfs/core';\nimport { exists, writeFile } from '@zenfs/core/promises';\nimport { IndexedDB } from '@zenfs/dom';\n\nawait configureSingle({ backend: IndexedDB });\n\nconst exists = await exists('/myfile.txt');\nif (!exists) {\n\tawait writeFile('/myfile.txt', 'Lots of persistent data');\n}\n```\n\n\u003e [!NOTE]\n\u003e You can import the promises API using:\n\u003e\n\u003e 1. Exports from `@zenfs/core/promises`\n\u003e 2. The `promises` export from `@zenfs/core`\n\u003e 3. `fs.promises` on the exported `fs` from `@zenfs/core`.\n\n#### Mounting and unmounting, creating backends\n\nIf you would like to create backends without configure (e.g. to do something dynamic at runtime), you may do so by importing the backend and calling `resolveMountConfig` with it.\n\nYou can then mount and unmount the backend instance by using `mount` and `umount`.\n\n```js\nimport { configure, resolveMountConfig, InMemory } from '@zenfs/core';\nimport { IndexedDB } from '@zenfs/dom';\nimport { Zip } from '@zenfs/archives';\n\nawait configure({\n\tmounts: {\n\t\t'/tmp': InMemory,\n\t\t'/home': IndexedDB,\n\t},\n});\n\nfs.mkdirSync('/mnt');\n\nconst res = await fetch('mydata.zip');\nconst zipfs = await resolveMountConfig({ backend: Zip, data: await res.arrayBuffer() });\nfs.mount('/mnt/zip', zipfs);\n\n// do stuff with the mounted zip\n\nfs.umount('/mnt/zip'); // finished using the zip\n```\n\n\u003e [!CAUTION]\n\u003e Instances of backends follow the _internal_ API. You should never use a backend's methods unless you are extending a backend.\n\n### Devices and device files\n\nZenFS includes experimental support for device files. These are designed to follow Linux's device file behavior, for consistency and ease of use. You can automatically add some normal devices with the `addDevices` configuration option:\n\n```ts\nawait configure({\n\tmounts: {\n\t\t/* ... */\n\t},\n\taddDevices: true,\n});\n\nfs.writeFileSync('/dev/null', 'Some data to be discarded');\n\nconst randomData = new Uint8Array(100);\n\nconst random = fs.openSync('/dev/random', 'r');\nfs.readSync(random, randomData);\nfs.closeSync(random);\n```\n\nYou can create your own devices by implementing a `DeviceDriver`. For example, the null device looks similar to this:\n\n```ts\nconst customNullDevice = {\n\tname: 'custom_null',\n\t// only 1 can exist per DeviceFS\n\tsingleton: true,\n\t// optional if false\n\tisBuffered: false,\n\tread() {\n\t\treturn 0;\n\t},\n\twrite() {\n\t\treturn 0;\n\t},\n};\n```\n\nNote the actual implementation's write is slightly more complicated since it adds to the file position. You can find more information on the docs.\n\nFinally, if you'd like to use your custom device with the file system:\n\n```ts\nimport { addDevice, fs } from '@zenfs/core';\n\naddDevice(customNullDevice);\n\nfs.writeFileSync('/dev/custom', 'This gets discarded.');\n```\n\n## Using with bundlers\n\nZenFS exports a drop-in for Node's `fs` module (up to the version of `@types/node` in package.json), so you can use it for your bundler of preference using the default export.\n\n## Sponsors\n\nA huge thank you to [![Deco.cx logo](https://avatars.githubusercontent.com/deco-cx?size=20) Deco.cx](https://github.com/deco-cx) for sponsoring ZenFS and helping to make this possible.\n\n## Building\n\n- Make sure you have Node and NPM installed. You must have Node v18 or newer.\n- Install dependencies with `npm install`\n- Build using `npm run build`\n- You can find the built code in `dist`.\n\n### Testing\n\nRun unit tests with:\n\n- `npm test` to run all tests using the default configuration\n- `npx zenfs-test -abc` to run the common tests and run the full FS suite against all included backends\n    - You can also run this command to test your own backends, the `--auto` (`-a`) flag will automatically detect any setup scripts matching `tests/setup/*` or `tests/setup-*.ts`. If you do, you'll need to include the `c8` dependency for coverage.\n\n### BrowserFS Fork\n\nZenFS is a fork of [BrowserFS](https://github.com/jvilk/BrowserFS). If you are using ZenFS in a research paper, you may want to [cite BrowserFS](https://github.com/jvilk/BrowserFS#citing).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzen-fs%2Fcore","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzen-fs%2Fcore","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzen-fs%2Fcore/lists"}