# @humanfs/node

> The Node.js bindings of the humanfs library.

Latest version **0.17.0** (published 2026-09-10) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @humanfs/node
pnpm add @humanfs/node
yarn add @humanfs/node
bun add @humanfs/node
```

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.17.0 |
| Published | 2026-09-10 |
| First published | 2024-01-30 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=24.0.0 |
| Dependencies | 3 |
| Unpacked size | 36.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 554 |
| Author | Nicholas C. Zakas |
| Maintainers | nzakas |
| Keywords | filesystem, fs, hfs, files |

## Links

- npm: https://www.npmjs.com/package/@humanfs/node
- Repository: https://github.com/humanwhocodes/humanfs
- Homepage: https://github.com/humanwhocodes/humanfs#readme
- Issues: https://github.com/humanwhocodes/humanfs/issues
- npm.io page: https://npm.io/package/@humanfs/node

## Dependencies (3)

- [@humanfs/core](https://npm.io/package/@humanfs/core.md) ^0.20.0
- [@humanfs/types](https://npm.io/package/@humanfs/types.md) ^0.16.0
- [@humanwhocodes/retry](https://npm.io/package/@humanwhocodes/retry.md) ^0.4.0

## Alternatives

- [unionfs](https://npm.io/package/unionfs.md) — 2.2M weekly downloads
- [path-starts-with](https://npm.io/package/path-starts-with.md) — 35.9K weekly downloads
- [redzip](https://npm.io/package/redzip.md) — 1.2K weekly downloads
- [vscode-anymatch](https://npm.io/package/vscode-anymatch.md) — 848 weekly downloads
- [@ledgerhq/coin-filecoin](https://npm.io/package/@ledgerhq/coin-filecoin.md) — 793 weekly downloads

## Recent versions

- 0.17.0 (latest) — 2026-09-10
- 0.16.8 — 2026-04-17
- 0.16.7 — 2025-09-03
- 0.16.6 — 2024-10-28
- 0.16.5 — 2024-09-09
- 0.16.4 — 2024-07-24
- 0.16.3 — 2024-06-13
- 0.16.2 — 2024-06-12
- 0.16.0 — 2024-03-20
- 0.15.0 — 2024-03-13
- 0.14.1 — 2024-02-29
- 0.14.0 — 2024-02-27
- 0.13.0 — 2024-02-24
- 0.12.0 — 2024-02-19
- 0.11.0 — 2024-02-14
- … 5 more at https://npm.io/package/@humanfs/node/versions

## README

# `@humanfs/node`

by [Nicholas C. Zakas](https://humanwhocodes.com)

If you find this useful, please consider supporting my work with a [donation](https://humanwhocodes.com/donate) or [nominate me](https://stars.github.com/nominate/) for a GitHub Star.

## Description

The `hfs` bindings for use in Node.js and Node.js-compatible runtimes.

> [!WARNING]
> This project is **experimental** and may change significantly before v1.0.0. Use at your own caution and definitely not in production!

## Installation

Install using your favorite package manager:

```shell
npm install @humanfs/node

# or

pnpm install @humanfs/node

# or

yarn add @humanfs/node

# or

bun install @humanfs/node
```

## Usage

The easiest way to use hfs in your project is to import the `hfs` object:

```js
import { hfs } from "@humanfs/node";
```

Then, you can use the API methods:

```js
// 1. Files

// read from a text file
const text = await hfs.text("file.txt");

// read from a JSON file
const json = await hfs.json("file.json");

// read raw bytes from a text file
const arrayBuffer = await hfs.arrayBuffer("file.txt");

// write text to a file
await hfs.write("file.txt", "Hello world!");

// write bytes to a file
await hfs.write("file.txt", new TextEncoder().encode("Hello world!"));

// append text to a file
await hfs.append("file.txt", "Hello world!");

// append bytes to a file
await hfs.append("file.txt", new TextEncoder().encode("Hello world!"));

// does the file exist?
const found = await hfs.isFile("file.txt");

// how big is the file?
const size = await hfs.size("file.txt");

// when was the file modified?
const mtime = await hfs.lastModified("file.txt");

// copy a file from one location to another
await hfs.copy("file.txt", "file-copy.txt");

// move a file from one location to another
await hfs.move("file.txt", "renamed.txt");

// delete a file
await hfs.delete("file.txt");

// 2. Directories

// create a directory
await hfs.createDirectory("dir");

// create a directory recursively
await hfs.createDirectory("dir/subdir");

// does the directory exist?
const dirFound = await hfs.isDirectory("dir");

// copy the entire directory
hfs.copyAll("from-dir", "to-dir");

// move the entire directory
hfs.moveAll("from-dir", "to-dir");

// delete a directory
await hfs.delete("dir");

// delete a non-empty directory
await hfs.deleteAll("dir");
```

If you'd like to create your own instance, import the `NodeHfs` constructor:

```js
import { NodeHfs } from "@humanfs/node";
import fsp from "fs/promises";

const hfs = new NodeHfs();

// optionally specify the fs/promises object to use
const hfs = new NodeHfs({ fsp });
```

If you'd like to use just the impl, import the `NodeHfsImpl` constructor:

```js
import { NodeHfsImpl } from "@humanfs/node";
import fsp from "fs/promises";

const hfs = new NodeHfsImpl();

// optionally specify the fs/promises object to use
const hfs = new NodeHfsImpl({ fsp });
```

## Errors Handled

* `ENOENT` - in most cases, these errors are handled silently.
* `ENFILE` and `EMFILE` - calls that result in these errors are retried for up to 60 seconds before giving up for good.

## License

Apache 2.0

---
_Source: https://npm.io/package/@humanfs/node · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._