# @solarpunkltd/file-manager-lib

> A file manager for storing and handling data on Swarm.

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

## Install

```sh
npm install @solarpunkltd/file-manager-lib
pnpm add @solarpunkltd/file-manager-lib
yarn add @solarpunkltd/file-manager-lib
bun add @solarpunkltd/file-manager-lib
```

## Health

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

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

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.1.0 |
| Published | 2026-09-07 |
| First published | 2025-01-31 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=24.0.0 |
| Dependencies | 3 |
| Unpacked size | 333.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | SolarPunkLtd |
| Maintainers | solarpunkltd |
| Keywords | swarm, bee, mantaray, file-manager, bee-js, decentralised-storage, web3, web3-storage, access-control, ethswarm, ethereum-swarm, p2p |

## Links

- npm: https://www.npmjs.com/package/@solarpunkltd/file-manager-lib
- Homepage: https://github.com/Solar-Punk-Ltd/file-manager-lib
- npm.io page: https://npm.io/package/@solarpunkltd/file-manager-lib

## Dependencies (3)

- [std-env](https://npm.io/package/std-env.md) ^3.10.0
- [cafe-utility](https://npm.io/package/cafe-utility.md) ^33.7.0
- [@ethersphere/bee-js](https://npm.io/package/@ethersphere/bee-js.md) ^13.0.0

## Alternatives

- [localforage](https://npm.io/package/localforage.md) — 6.2M weekly downloads
- [localforage-observable](https://npm.io/package/localforage-observable.md) — 30.8K weekly downloads
- [@y/y](https://npm.io/package/@y/y.md) — 30.1K weekly downloads
- [@metaobjectsdev/render](https://npm.io/package/@metaobjectsdev/render.md) — 3.5K weekly downloads
- [@ledgerhq/coin-algorand](https://npm.io/package/@ledgerhq/coin-algorand.md) — 1.1K weekly downloads

## Recent versions

- 1.1.0 (latest) — 2026-09-07
- 1.0.9 — 2026-06-01
- 1.0.8 — 2026-03-20
- 1.0.7 — 2026-03-05
- 1.0.6 — 2026-03-04
- 1.0.5 — 2026-02-11
- 1.0.4 — 2026-01-09
- 1.0.3 — 2025-12-09
- 1.0.2 — 2025-12-06
- 1.0.1 — 2025-12-02
- 1.0.0 — 2025-11-11
- 0.2.11 — 2025-11-06
- 0.2.10 — 2025-11-05
- 0.2.9 — 2025-11-03
- 0.2.7 — 2025-10-22
- … 26 more at https://npm.io/package/@solarpunkltd/file-manager-lib/versions

## README

# File Manager Library

**@solarpunkltd/file-manager-lib** is a TypeScript/JavaScript library for storing and handling files on
[Swarm](https://ethersphere.github.io/swarm-home/). It builds on [Bee](https://github.com/ethersphere/bee-js) to
provide:

- **Drives** — logical containers backed by postage stamps.
- **Files** — uploaded as manifests, stored in feeds, versioned automatically.
- **Access Control (ACT)** — enforceable read/unwrapping via publisher + history address.
- **Versioning** — restore any historical version to head.
- **Soft delete / recover / forget** — manage lifecycle without losing underlying Swarm data.
- **Sharing** — manage grantees and share notifications.
- **Browser + Node.js support** — unified API.

> Full method-level documentation: see [REFERENCE.md](REFERENCE.md). Test coverage and usage patterns: see
> [TESTS.md](tests/TESTS.md).

---

## Installation

```bash
pnpm install @solarpunkltd/file-manager-lib
```

Peer dependency: `@ethersphere/bee-js`

---

## Running a Bee Node

The library requires a running [Bee](https://github.com/ethersphere/bee) node with postage stamps available.

### Local Development (Dev Mode)

> **⚠️ Deprecated:** Bee dev mode (`bee dev`) is no longer supported as of Bee `v2.8.2` and
> `@ethersphere/bee-js` `v13.0.0`. Use a full Bee node (see Mainnet / Production below) for
> local development going forward.

```bash
bee dev --cors-allowed-origins="*"
```

- Runs with in-memory chequebook.
- Useful for testing and development.

### Mainnet / Production

```bash
bee start --config bee.yaml
```

- Requires full Bee setup (swap, chequebook, persisted DB).
- Ensure you have purchased real postage stamps with BZZ on mainnet.

---

## Postage Stamps

You need an active postage stamp to upload data.

### Install CLI

```bash
pnpm install -g @ethersphere/swarm-cli
```

### List existing stamps

```bash
swarm-cli stamp list
```

### Buy a new stamp

```bash
swarm-cli stamp buy --amount 100000000000 --depth 20 --label admin
```

- `--label admin` will make this stamp the **admin drive** automatically.

---

## Quick Start Example

```ts
import { Bee } from '@ethersphere/bee-js';
import { FileManagerBase } from '@solarpunkltd/file-manager-lib';

const bee = new Bee('http://localhost:1633', { signer });
const fm = new FileManagerBase(bee);
const adminBatchId = new BatchId('your-admin-batchId');
// purchase an 'admin' stamp, and a 'My Drive' stamp in the background,
// or use beeApi to purchase the stamp inline before initialization
// initialize drives & topics
await fm.initialize(adminBatchId);

// create an admin drive
await fm.createDrive(adminBatchId, 'admin', true);
// create a drive (non-admin)
await fm.createDrive('<BATCH_ID>', 'My Drive', false);

// upload directory
const uploaded = await fm.upload(fm.driveList[0], { info: { name: 'docs' }, path: './docs' });

// list + download
const fi = fm.fileInfoList.find((f) => f.name === 'docs')!;
const list = await fm.listFiles(fi, {
  actHistoryAddress: fi.file.historyRef,
  actPublisher: fi.actPublisher,
});
const data = await fm.download(fi, ['README.md'], {
  actHistoryAddress: fi.file.historyRef,
  actPublisher: fi.actPublisher,
});
```

### Browser differences

- Use `{ files: FileList }` instead of `{ path }`.
- `download()` returns `ReadableStream[]` instead of `Bytes[]`.

---

## Scripts

From `package.json`:

- `pnpm run build` → compile Node + browser + types.
- `pnpm run test` → run Jest unit + integration tests (see [TESTS.md](tests/TESTS.md)).
- `pnpm run test:ut` → run unit tests only (this is what CI runs).
- `pnpm run test:it` → run integration tests against a real Bee node.
  > **⚠️ Not run in CI:** `test:it` still relies on `BeeDev`, which was removed in
  > `@ethersphere/bee-js` v13, and on Bee's now-deprecated `dev` mode. It's excluded from CI
  > until it's migrated off both; run it locally against your own Bee node in the meantime.
- `pnpm run lint` / `pnpm run lint:fix` → linting.
- `pnpm init:husky` → husky init
- `pnpm run depcheck` → check dependencies

---

## Troubleshooting

- **Admin stamp not found** → buy a new stamp and label it `admin`.
- **File not found** → ensure correct directory path or FileList provided.
- **Postage expired** → buy a new one and re-initialize.
- **CORS mismatch** → align `--cors-allowed-origins` in Bee with your frontend origin.
- **ACT unwrap errors** → ensure both `actPublisher` and `actHistoryAddress` are passed.

---

## License

[Apache-2.0](./LICENSE)

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