NArchive

NArchive is a fast and open-source TypeScript library for packing directories into a single .nar archive file and extracting them back to disk or ram (Buffer).

It was designed to be simple, extensible, and easy to integrate into any Node.js project. Whether you need a custom archive format, backup solution, or the foundation for your own compression system, NArchive provides a clean API to build on.

[!IMPORTANT] NArchive does not perform compression.

This library is responsible only for packing directories into the .nar format and extracting them back.

If you want to build your own compression library or implement custom compression algorithms, NArchive provides a simple and extensible archive format that you can use as a foundation.

Features

• 📁 Pack entire directories into a single .nar archive
• 📂 Extract .nar archives back to disk
• ⚡ Fast asynchronous API
• 🟦 Written in TypeScript
• 📦 Lightweight with minimal dependencies
• 🔓 Fully open source
• 🛠 Easy to extend for custom archive formats and compression algorithms

Installation

npm install @nroot_project/narchive

Quick Start

import {NarPacker, NarUnpacker} from "@nroot_project/narchive";

export async function run(mode: "pack" | "unpack") {
  if (mode === "pack") {
    await NarPacker.packToFile("./folder", "./archive.nar");
  } else {
    await NarUnpacker.unpackToDisk("./archive.nar", "./output");
  }

  return "Done!";
}

API

Pack a directory

await NarPacker.packToFile("./directory", "./archive.nar");

Unpack an archive

await NarUnpacker.unpackToDisk("./archive.nar", "./directory");

Use Cases

NArchive can be used for:

• Application asset packaging
• Project backups
• Game resource archives
• File distribution
• Building custom archive or compression tools
• Learning how archive formats work

Roadmap

• [ ] Built-in compression support
• [ ] Archive metadata
• [ ] Streaming API
• [ ] Archive inspection
• [ ] Progress callbacks
• [ ] Incremental packing
• [ ] Archive validation

Contributing

Contributions are always welcome!

If you have an idea, find a bug, or want to improve the project, feel free to:

• Open an issue
• Submit a pull request
• Suggest new features
• Improve the documentation

Please make sure to follow the existing code style.

Sponsors

Platinum Sponsor

NRoot_Project

Gold Sponsor

NCrypt

Interested in sponsoring the project? Feel free to contact us.

License

This project is licensed under the MIT License.

Made with ❤️ by the NRoot_Project team.