{"id":20392370,"url":"https://github.com/wiseplat/npm1-swarm-js","last_synced_at":"2026-04-19T00:04:37.596Z","repository":{"id":122792567,"uuid":"125345241","full_name":"WISEPLAT/npm1-swarm-js","owner":"WISEPLAT","description":"Swarm tools for JavaScript.","archived":false,"fork":false,"pushed_at":"2018-03-15T09:45:00.000Z","size":51,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-01-15T10:26:24.274Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/WISEPLAT.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-03-15T09:44:03.000Z","updated_at":"2018-03-15T09:45:01.000Z","dependencies_parsed_at":null,"dependency_job_id":"8b3e4c5f-d77f-4677-8d59-79e6589ad146","html_url":"https://github.com/WISEPLAT/npm1-swarm-js","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WISEPLAT%2Fnpm1-swarm-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WISEPLAT%2Fnpm1-swarm-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WISEPLAT%2Fnpm1-swarm-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WISEPLAT%2Fnpm1-swarm-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/WISEPLAT","download_url":"https://codeload.github.com/WISEPLAT/npm1-swarm-js/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241941710,"owners_count":20046172,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-15T03:43:33.557Z","updated_at":"2026-04-19T00:04:37.561Z","avatar_url":"https://github.com/WISEPLAT.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"## Swarm.js\n\nThis library allows you to interact with the Swarm network from JavaScript. It:\n\n- Communicates with the network through the HTTP API;\n\n- Can be used either with a local node or a gateway;\n\n- Solves manifests recursively;\n\n- Enables you to upload/download raw data and directores;\n\n- Enables you to upload/download from disk or from pure JS;\n\n- Works on the browser and on Node.js;\n\n- Can automatically download the Swarm binaries safely and administer the local node for you.\n\n[Live demo!](http://swarm-gateways.net/bzz:/aa9dd4d23e105d0a2e62da38544112468372cd5ad038fbdc9874b1f51b8e76f2/)\n\n## Installing\n\n    npm install npm1-swarm-js\n\n## Basic usage\n\nThe simplest use case for Swarm is uploading/downloading raw data and directories. First, load the lib:\n\n```javascript\n// Loads the Swarm API pointing to the official gateway\nconst swarm = require(\"npm1-swarm-js\").at(\"http://swarm-gateways.net\");\n```\n\n#### Upload raw data\n\nTo upload raw data, just call `swarm.upload(buffer)`. It returns a promise with the uploaded hash.\n\n```javascript\nconst file = \"test file\";\nswarm.upload(new Buffer(file)).then(hash =\u003e {\n  console.log(\"Uploaded file. Address:\", hash);\n})\n```\n\n#### Download raw data\n\nTo download raw data, just call `swarm.download(hash)`. It returns a promise with the data buffer.\n\n```javascript\nconst fileHash = \"a5c10851ef054c268a2438f10a21f6efe3dc3dcdcc2ea0e6a1a7a38bf8c91e23\";\nswarm.download(fileHash).then(buffer =\u003e {\n  console.log(\"Downloaded file:\", buffer.toString());\n});\n```\n\n#### Upload a directory\n\nTo upload a directory, just call `swarm.upload(directory)`, where directory is an object mapping paths to entries, those containing a mime-type and the data (a buffer).\n\n```javascript\nconst dir = {\n  \"/foo.txt\": {type: \"text/plain\", data: new Buffer(\"sample file\")},\n  \"/bar.txt\": {type: \"text/plain\", data: new Buffer(\"another file\")}\n};\nswarm.upload(dir).then(hash =\u003e {\n  console.log(\"Uploaded directory. Address:\", hash);\n});\n```\n\n#### Download a directory\n\nTo dowwnload a directory, just call `swarm.download(hash)`. Swarm.js will return a directory instead of a buffer by detecting the existence of a manifest on that hash.\n\n```javascript\nconst dirHash = \"7e980476df218c05ecfcb0a2ca73597193a34c5a9d6da84d54e295ecd8e0c641\";\nswarm.download(dirHash).then(dir =\u003e {\n  console.log(\"Downloaded directory:\");\n  for (let path in dir) {\n    console.log(\"-\", path, \":\", dir[path].data.toString());\n  }\n});\n```\n\n#### Download a file/directory to disk (on Node.js)\n\n```javascript\nswarm.download(\"DAPP_HASH\", \"/target/dir\")\n  .then(path =\u003e console.log(`Downloaded DApp to ${path}.`))\n  .catch(console.log);\n```\n\n#### Upload raw data, a file or a directory from disk (on Node.js)\n\n```javascript\nswarm.upload({\n  path: \"/path/to/thing\",      // path to data / file / directory\n  kind: \"directory\",           // could also be \"file\" or \"data\"\n  defaultFile: \"/index.html\"}) // optional, and only for kind === \"directory\"\n  .then(console.log)\n  .catch(console.log);\n```\n\n#### Upload raw data, a file or a directory from disk (on Browser)\n\n```javascript\nswarm.upload({pick: \"file\"}) // could also be \"directory\" or \"data\"\n```\n\n#### Uploading a PDF\n\n- [Uploading a PDF  in various ways (gist).](https://gist.github.com/wiseplat/npm-ae0439de5ca752604675ffa4535e47b4)\n\n## Uploading an Wiseplat DApp\n\nWhen it comes to decentralized applications (DApps), the Wiseplat network is responsible for the back-end logic, while Swarm is responsible for hosting and serving the front-end code. Hosting a DApp on Swarm is as simple as creating a directory with some HTMLs and a default route (the \"index.html\"). This, too, can be done with Swarm.js either [from disk](https://github.com/wiseplat/npm1-swarm-js/blob/master/examples/dapp_upload_from_disk.js), or with [pure JavaScript](https://github.com/wiseplat/npm1-swarm-js/blob/master/examples/dapp_upload.js). Here is a sneak peek:\n\n```javascript\nconst swarm = require(\"npm1-swarm-js\").at(\"http://swarm-gateways.net\");\n\nconst indexHtml =\n`\u003chtml\u003e\n  \u003cbody\u003e\n    \u003ch3\u003e\u003cimg src=\"wiseplat_icon.png\"/\u003e Swarm.js example DApp\u003c/h3\u003e\n    \u003cp\u003e\u003ca href=\"foo/test_text_1.txt\"\u003eTest #1\u003c/a\u003e\u003c/p\u003e\n    \u003cp\u003e\u003ca href=\"foo/test_text_2.txt\"\u003eTest #2\u003c/a\u003e\u003c/p\u003e\n  \u003c/body\u003e\n\u003c/html\u003e`;\n\n(...)\n\nconst exampleDApp = {\n  \"\"                     : {type: \"text/html\", data: indexHtml},\n  \"/index.html\"          : {type: \"text/html\", data: indexHtml},\n  \"/wiseplat_icon.png\"   : {type: \"image/png\", data: wiseplatIconPng},\n  \"/foo/test_text_1.txt\" : {type: \"text/plain\", data: testText1},\n  \"/foo/test_text_2.txt\" : {type: \"text/plain\", data: testText2}\n}\n\nswarm.upload(exampleDApp)\n  .then(console.log)\n  .catch(console.log);\n```\n\nWhen you run that script, it outputs a hash. You can then use that hash to access the uploaded DApp, by either using a Swarm-enabled browser such as Mist, or through a gateway. That demo DApp is live and can be accessed:\n\n- If your browser recognizes Swarm, [click here](bzz://379d2791624c3e3719bb28f7bfa362cc9c726ec06482b5800c8e3cefaf2b7bcf/).\n\n- If you are in a conventional browser, [click here](http://swarm-gateways.net/bzz:/379d2791624c3e3719bb28f7bfa362cc9c726ec06482b5800c8e3cefaf2b7bcf/).\n\n## Running a local node\n\nRather than using a gateway, you might wish to run your own local node. For that, you can either [download/install/run it yourself](http://swarm-guide.readthedocs.io/en/latest/), and then use `require(\"npm1-swarm-js\").at(\"http://localhost:8500\")`, or let Swarm.js take care of it. For that, you just need to write a small config JSON with some info: \n\n```javascript\nconst Swarm = require(\"npm1-swarm-js\");\n\n// To run Swarm locally, you need a running Gwsh\n// node and an Wiseplat account/password\nconst config = {\n  // Either an address visible by `gwsh account list`, or the path to a private\n  // key (a file with 64 hex characteres); obviously, use an account without wsh!\n  account: \"d849168d52ea5c40de1b0b973cfd96873c961963\",\n\n  // Password to unlock the address above; omit if you used a path to a key\n  password: \"sap\",\n\n  // Path where swarm-js will save its files\n  dataDir: process.env.HOME + \"/Library/Wiseplat/swarm-js\",\n\n  // Path where gwsh.ipc is (that file is created when you start gwsh)\n  wshApi: process.env.HOME + \"/Library/Wiseplat/gwsh.ipc\",\n\n  // Path where the swarm binary is (if there is nothing on this path, swarm-js\n  // will safely download and place it there). Add `.exe` to the end if you're\n  // on windows (otherwise it won't recognize as an executable file - eventually\n  // this will be improved)\n  binPath: process.env.HOME + \"/Library/Wiseplat/swarm-js/bin/swarm\"\n};\n\n// Magically starts a local Swarm node\n// Downloads binaries if necessary\nSwarm.local(config, swarm =\u003e new Promise((resolve, reject) =\u003e {\n  // you can use the `swarm` object inside here\n\n  // Uploads data using the local node\n  swarm.upload(new Buffer(\"test\")).then(hash =\u003e {\n    console.log(\"Uploaded data. Address:\", hash);\n\n    // Closes the Swarm process.\n    resolve();\n  });\n\n})).then(() =\u003e console.log(\"Done!\"));\n```\n\nIf you have any trouble with this, please open an issue to let me know. That function does everything required to start a local Swarm node, including downloading binaries (if not available yet) and manging the process. It then gives you a `swarm` object pointing to the local node. If the Swarm process was started by `Swarm.js`, it will be closed when you call `resolve()`. While it is up, you're able to access it on your browser at `http://localhost:8500`.\n\n## API\n\nTODO: document the API.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwiseplat%2Fnpm1-swarm-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwiseplat%2Fnpm1-swarm-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwiseplat%2Fnpm1-swarm-js/lists"}