Swarm.js: Decentralized Storage Client

0.1.42 · abandoned · verified Sun Apr 19

Swarm.js is a JavaScript library designed to facilitate interaction with the Swarm network, a decentralized storage platform. The package provides functionalities for uploading and downloading files and directories to and from Swarm, as well as hashing various data types. It specifically targets both Node.js and browser environments for these operations. The current stable version appears to be 0.1.42, indicating it never reached a 1.0 release. The library's development has ceased, with the maintainer explicitly stating it is no longer actively maintained and recommending Erebos (https://erebos.js.org/) as an alternative. Therefore, users should be aware of its abandoned status and consider alternatives for new projects, or for maintaining existing ones.

Common errors

```
TypeError: swarm.at is not a function
```
cause Attempting to import `at` as a named export (`import { at } from 'swarm-js';`) or incorrectly calling `require('swarm-js')` without chaining `.at()` immediately.

fix Ensure you are using the CommonJS `require` syntax and calling the `.at()` method immediately: `const swarm = require('swarm-js').at('http://swarm-gateways.net');`
```
ERR_REQUIRE_ESM
```
cause Attempting to use `require()` in an ES Module context, or using `import` syntax directly with this CommonJS-only library without proper transpilation.

fix Change `import` statements to `const swarm = require('swarm-js').at(...)` or configure your build process to transpile CommonJS modules for ESM consumption in an `ESM` project. If in an ES Module environment, you might need a wrapper or dynamic import if `require` is not available.
```
Error: connect ECONNREFUSED
```
cause The Swarm gateway specified in `.at()` is unreachable, offline, or refusing connections from your environment.

fix Verify the Swarm gateway URL is correct and the gateway is operational and accessible from your network. Try a different public gateway URL if available, or ensure your firewall/network settings allow the connection.

Warnings

breaking This library is explicitly unmaintained and abandoned by its creator. No further updates, bug fixes, or security patches will be released, making it unsuitable for production use.
Fix: Migrate to an actively maintained alternative for Swarm interactions, such as Erebos (https://erebos.js.org/).
gotcha The package is still in a pre-1.0 version (0.1.42), indicating it was never considered stable by its original maintainer. This implies potential API instability, incomplete features, and lack of long-term support.
Fix: Use with extreme caution and be aware of potential issues; strongly consider actively maintained alternative libraries for any new or critical projects.
gotcha The primary usage pattern shown is CommonJS (`require`). Modern Node.js and browser environments typically prefer ES Modules (`import`). Direct ESM compatibility is not guaranteed without bundling or transpilation, and using `import` directly may lead to errors.
Fix: For Node.js, ensure your project is configured for CommonJS or use a bundler (e.g., Webpack, Rollup) for browser environments if you need ESM context. Always use `require()` as shown in the documentation.

Install

npm install swarm-js npm
yarn add swarm-js yarn
pnpm add swarm-js pnpm

Imports

swarm (configured instance)
wrong:
```
import { at } from 'swarm-js';
```
correct:
```
const swarm = require("swarm-js").at("http://swarm-gateways.net");
```
The library primarily uses CommonJS `require()` syntax. The main export is a function that returns the Swarm API instance when called with a gateway URL.
swarm.upload
wrong:
```
import { upload } from 'swarm-js';
```
correct:
```
swarm.upload(data)
```
The `upload` function is a method of the `swarm` instance returned by `require('swarm-js').at()`.
swarm.download
wrong:
```
import { download } from 'swarm-js';
```
correct:
```
swarm.download(hash)
```
Similarly, `download` is a method of the configured `swarm` instance.
swarm.hash
wrong:
```
import { hash } from 'swarm-js';
```
correct:
```
swarm.hash(value)
```
The `hash` utility is also a method of the configured `swarm` instance.

Quickstart

Demonstrates installation, configuration with a gateway, and basic upload/download operations for both single files and directories.

const swarm = require("swarm-js").at("http://swarm-gateways.net");

const fileContent = "Hello Swarm! This is a test file.";

swarm.upload(fileContent)
  .then(hash => {
    console.log("Uploaded file. Address:", hash);
    return swarm.download(hash);
  })
  .then(downloadedArray => {
    console.log("Downloaded file content:", swarm.toString(downloadedArray));
  })
  .catch(error => {
    console.error("An error occurred:", error);
  });

const dir = {
  "/hello.txt": { type: "text/plain", data: "Hello from directory!" },
  "/meta.json": { type: "application/json", data: JSON.stringify({ version: "1.0" }) }
};

swarm.upload(dir)
  .then(dirHash => {
    console.log("Uploaded directory. Address:", dirHash);
    return swarm.download(dirHash);
  })
  .then(downloadedDir => {
    console.log("Downloaded directory:");
    for (let path in downloadedDir) {
      console.log(`- ${path}: ${downloadedDir[path].data.toString()}`);
    }
  })
  .catch(error => {
    console.error("Directory operation failed:", error);
  });

view raw JSON →