Relifso • Node.js Filesystem Toolkit Library

sponsor — discord — npm — github

@reliverse/relifso is a modern filesystem toolkit for builders. drop-in replacement for node:fs and fs-extra — powered by native promises, built with es modules, and packed with dx-focused utilities.

Features

• 🪄 Everything you love from fs-extra — now simpler, cleaner, and more beginner-friendly
• ⚙️ Drop-in replacement for node:fs — with native Promise, async/await, and sync variants
• 🤝 Forget about try-catch for common errors like “file not found” — relifso does it under the hood
• 🧯 Gracefully handles errors like EMFILE (reading or writing a lot of files at once) and other edge cases
• 📚 Consistent error-first behavior — even for legacy APIs like fs.exists()
• 📦 First-class ESM and full TypeScript support — no config hacks required
• 🧼 Zero bloat — small size (4 kB), zero deps, modern code, no monkey-patching
• 🎯 Supports all Node.js v16+ features — optimized for Node.js v22+
• 🧪 Soon: Ready for upcoming Node.js v22+ experimental features
• ✌️ Soon: Bun v1.2+ ready — ships with Bun-aware enhancements out of the box
• 🔥 Soon: Bun-specific features are exposed via fs.* when running on Bun

Heads Up

• Most of the things mentioned in this doc aren’t implemented yet — they’re part of the vision for ~v1.3.0.
• Got thoughts? Ideas? Send your feedback in Discord or use GitHub Issues.
• Your feedback means the world and helps shape where this project goes next. Thank you!

Install

# bun • pnpm • yarn • npm
bun add @reliverse/relifso

Migrate:

bun rm fs-extra
bun rm @types/fs-extra
# soon:
# bun add -D @reliverse/dler
# bun dler relifso node-fs to relifso
# bun dler relifso fs-extra to relifso

Coming soon:

bun add -D @reliverse/dler
bun dler relifso init ...

Usage

Check ./e-relifso.ts and ./e-pathkit.ts for a full examples. You can clone this repo and run via bun dev.

Relifso works just like fs-extra — every method is promise-first, ergonomic, and future-ready.

import { copy, pathExists, remove } from "@reliverse/relifso";

await copy("src/index.ts", "dist/index.ts");

if (await pathExists("dist/index.ts")) {
  await remove("dist/index.ts");
}

• ✨ Everything’s bundled — modern, async, and type-safe.
• 🧼 No more boilerplate like promisify(fs.removeSync) or using mkdirp, ncp, or rimraf.
• 🌱 No more weird try/catch for common errors like “file not found.”
• ✌️ Just clean, predictable APIs built for 2025 and beyond.

Example

import {
  ensureDir,
  outputJson,
  readJson,
  remove,
} from "@reliverse/relifso";

const path = "./.reliverse/config.json";

await ensureDir(".reliverse");
await outputJson(path, { hello: "world" });

const config = await readJson(path);
console.log(config); // { hello: 'world' }

await remove(".reliverse");

Sync vs Async vs Legacy

You choose your flavor:

// Async/Await
await copy("a.txt", "b.txt");

// Sync
copySync("a.txt", "b.txt");

// Callback (legacy-style)
copy("a.txt", "b.txt", err => {
  if (err) console.error(err);
});

All async methods return a Promise if no callback is passed.

Fully Typed, Fully Modern

• Written in modern ESM
• Minimal dependencies
• Full TypeScript declarations
• Compatible with Node.js 16+, best with 22+
• Async methods are built from the sync versions — no wrappers, no bloat

What’s Inside?

• All async methods follow the Promise pattern by default.
• All sync methods are safe and throw errors when needed.

Async (recommended)

Common Async Methods

• access
• appendFile
• copy
• copyFile
• cp
• createReadStream
• createWriteStream
• ensureFile
• exists
• mkdir
• mkdirs
• move
• open
• outputFile
• outputJson
• read
• readdir
• readFile
• readJson
• readLines
• readText
• rename
• rm
• rmdir
• stat
• symlink
• truncate
• unlink
• watch
• watchFile
• write
• writeFile
• writeJson

Less Commonly Used Async Methods

• chmod
• chown
• close
• dive
• emptyDir
• ensureLink
• ensureSymlink
• fchmod
• fchown
• forEachChild
• fstat
• ftruncate
• futimes
• gracefulify
• isDirectory
• isSymlink
• lchmod
• lchown
• link
• lstat
• lutimes
• mapChildren
• mapStructure
• mapStructureOrdered
• mkdtemp
• openAsBlob
• opendir
• readv
• realpath
• remove
• resolve
• statfs
• unwatchFile
• utimes
• vacuum
• writev

Sync

Common Sync Methods

• accessSync
• appendFileSync
• copyFileSync
• copySync
• cpSync
• existsSync
• mkdirSync
• mkdirsSync
• moveSync
• openSync
• outputFileSync
• outputJsonSync
• readdirSync
• readFileSync
• readJsonSync
• readTextSync
• renameSync
• rmSync
• rmdirSync
• statSync
• symlinkSync
• truncateSync
• unlinkSync
• writeFileSync
• writeJsonSync
• writeSync

Less Commonly Used Sync Methods

• chmodSync
• chownSync
• closeSync
• diveSync
• emptyDirSync
• ensureFileSync
• ensureLinkSync
• ensureSymlinkSync
• fchmodSync
• fchownSync
• fdatasync
• fdatasyncSync
• forEachChildSync
• fstatSync
• fsync
• fsyncSync
• ftruncateSync
• futimesSync
• isDirectorySync
• lchmodSync
• lchownSync
• linkSync
• lstatSync
• lutimesSync
• mkdirsSync
• mkdtempSync
• opendirSync
• readLinesSync
• readlinkSync
• readSync
• readvSync
• realpathSync
• removeSync
• statfsSync
• utimesSync
• writevSync

Contributing

...

TODO

• Create usage example in ./e-relifso.ts and ./e-pathkit.ts
• Ensure ./e-relifso.ts and ./e-pathkit.ts works 100% correctly
• Consider using @reliverse/repath instead of just node:path.
• Pass all fs-extra tests with Bun (+ fix & improve them).
• Convert all jsdoc comments to TypeScript types.
• Fully improve all fs-extra codebase files.

Shoutouts

Relifso wouldn’t be so cool without these gems:

• node:fs+node:path — origins
• fs-extra — classic, reliable
• fsxt — full fs-extra overhaul

Show Some Love

If @reliverse/relifso reduced the number of lines in your codebase:

• ⭐ Star it on GitHub
• 💖 Sponsor @blefnk
• 🧙 Recommend it to your dev friends

License

MIT © 2025 Nazar Kornienko (blefnk)