@ethersphere/bee-js
v8.3.1
Published
Javascript client for Bee
Downloads
2,308
Readme
Bee-JS
JavaScript SDK for connecting to a Bee node in the Swarm decentralised storage.
Supports Node.js 18+, Vite and Webpack.
Write your code in CJS, MJS or TypeScript.
Intended to be used with Bee version 2.2.0.
Quick start
Start a Swarm project using TypeScript:
npm init swarm-app@latest my-dapp node-ts
or using Vite and TypeScript:
npm init swarm-app@latest my-dapp vite-tsx
Supported types are node
, node-esm
, node-ts
and vite-tsx
. Replace my-dapp
with your project name.
Install
npm install @ethersphere/bee-js
or
yarn add @ethersphere/bee-js
Import
CJS
const { Bee } = require('@ethersphere/bee-js')
MJS and TypeScript
import { Bee } from '@ethersphere/bee-js'
Script tag
Loading this module through a script tag will make the BeeJs
object available in the global namespace.
<script src="https://unpkg.com/@ethersphere/bee-js/dist/index.browser.min.js"></script>
Usage
Upload via Swarm Gateway
import { Bee, NULL_STAMP, SWARM_GATEWAY_URL } from '@ethersphere/bee-js'
main()
async function main() {
const bee = new Bee(SWARM_GATEWAY_URL)
const { reference } = await bee.uploadData(NULL_STAMP, 'Hello, World!')
console.log(reference)
}
Create or select an existing postage batch
Swarm incentivizes nodes in the network to store content, therefor all uploads require a paid postage batch.
import { Bee } from '@ethersphere/bee-js'
async function getOrCreatePostageBatch() {
const bee = new Bee('http://localhost:1633')
let batchId
const batches = await bee.getAllPostageBatch()
const usable = batches.find(x => x.usable)
if (usable) {
batchId = usable.batchID
} else {
batchId = await bee.createPostageBatch('500000000', 20)
}
}
The following examples all assume an existing batchId.
Upload simple data (Browser + Node.js)
import { Bee } from '@ethersphere/bee-js'
const bee = new Bee('http://localhost:1633')
const uploadResult = await bee.uploadData(batchId, 'Bee is awesome!')
const data = await bee.downloadData(uploadResult.reference)
console.log(data.text()) // prints 'Bee is awesome!'
Upload data from a file input (React)
import { Bee } from '@ethersphere/bee-js'
const bee = new Bee('http://localhost:1633')
const result = await bee.uploadFile(batchId, file)
Upload multiple files or a directory (React)
import { Bee } from '@ethersphere/bee-js'
const bee = new Bee('http://localhost:1633')
const result = await bee.uploadFiles(batchId, fileList)
Upload arbitrary large file (Node.js)
import { Bee } from '@ethersphere/bee-js'
import { createReadStream } from 'fs'
const bee = new Bee('http://localhost:1633')
const readable = createReadStream('./path/to/large.bin')
const uploadResult = await bee.uploadFile(batchId, readable)
Upload arbitrary large directories (Node.js)
import { Bee } from '@ethersphere/bee-js'
import { createReadStream } from 'fs'
const bee = new Bee('http://localhost:1633')
const uploadResult = await bee.uploadFilesFromDirectory(batchId, './path/to/gallery/')
Customize http/https agent and headers
const bee = new Bee('http://localhost:1633', {
httpAgent: new http.Agent({ keepAlive: true }),
httpsAgent: new https.Agent({ keepAlive: true }),
headers: {
Authorization: 'Basic ' + Buffer.from('username:password').toString('base64'),
},
})
Check out our examples repo for some more ideas on how to use bee-js
Documentation
You can find the full documentation here. The API reference documentation can be found here.
Contribute
Stay up to date by joining the official Discord and by keeping an eye on the releases tab.
There are some ways you can make this module better:
- Consult our open issues and take on one of them
- Help our tests reach 100% coverage!
- Join us in our Discord chat in the #develop-on-swarm channel if you have questions or want to give feedback
Setup
Install project dependencies with
npm i
Test
The tests run in both context: node and dom with Jest.
To run the integration tests, you need to spin up local Bee cluster using our
fdp-play
project. In order to do that you have to have locally Docker
running on your machine, but afterwards you can just simply run npm run bee
, which spins up the cluster and display
Queen's logs. If you want to exit hit CTRL+C
.
If you want to skip creation of postage stamps every run of integration tests you can create stamps for both nodes and
set them under env. variables BEE_POSTAGE
and BEE_PEER_POSTAGE
.
By default, for integration tests two bee nodes are expected to run on localhost on addresses http://localhost:1633
and http://localhost:11633
. These are the default values for the fdp-play
script. If you want to use custom setup,
you can change the behavior of tests to different addresses using environment variables BEE_API_URL
and
BEE_PEER_API_URL
.
There are also browser tests by Puppeteer, which also provide integrity testing.
npm run test:browser
The test HTML file which Puppeteer uses is the test/testpage/testpage.html. To open and
manually test BeeJS with developer console, it is necessary to build the library first with npm run compile:browser
(running the browser tests npm run test:browser
also builds the library).
Compile code
In order to compile NodeJS code run
npm run compile:node
or for Browsers
npm run compile:browser