sia-storage-js

TypeScript SDK for building decentralized storage apps on the Sia network. Works in Node.js, Bun, and the browser.

For React Native, see react-native-sia.

Install

npm install @siafoundation/sia-storage

Quick start

import { initSia, Builder, generateRecoveryPhrase } from '@siafoundation/sia-storage'

await initSia()

const appMeta = {
  appId: '0'.repeat(64),                // 32-byte app identifier (hex)
  name: 'My App',
  description: 'An app on the Sia network',
  serviceUrl: 'https://myapp.com',
}

const builder = new Builder('https://sia.storage', appMeta)
await builder.requestConnection()
// Show builder.responseUrl() to the user — they visit it to authorize.
await builder.waitForApproval()

const phrase = generateRecoveryPhrase()
const sdk = await builder.register(phrase)

// Persist the app key so the user doesn't re-auth next time.
const appKeyHex = sdk.appKey().export().toHex()

Reconnecting a returning user:

import { Builder, AppKey } from '@siafoundation/sia-storage'

const sdk = await new Builder('https://sia.storage', appMeta)
  .connected(new AppKey(Uint8Array.fromHex(appKeyHex)))

Uploading

import { PinnedObject } from '@siafoundation/sia-storage'

const object = await sdk.upload(new PinnedObject(), file.stream(), { maxInflight: 10 })
await sdk.pinObject(object)

Downloading:

const stream = sdk.download(object)
for await (const chunk of stream) { /* ... */ }

For many small files, share slabs via uploadPacked:

const packed = sdk.uploadPacked({ maxInflight: 10 })
await packed.add(fileA.stream())
await packed.add(fileB.stream())
for (const obj of await packed.finalize()) await sdk.pinObject(obj)

Framework notes

The browser build is WebAssembly — most bundlers handle it directly, a few need a small hint.

Vite — production builds work as-is. For vite dev, exclude the package from the dep pre-bundler so its import.meta.url-relative WASM path resolves correctly:

// vite.config.js
export default defineConfig({
  optimizeDeps: { exclude: ['@siafoundation/sia-storage'] },
})

Without this, the dev server fetches the .wasm from /node_modules/.vite/deps/ where it doesn't exist, the SPA fallback returns index.html, and WebAssembly.instantiate fails with a magic word … found 3c 21 64 6f error.

Next.js (App Router) — load from a Client Component, dynamically imported so the WebAssembly module isn't pulled into the server prerender:

'use client'
import dynamic from 'next/dynamic'
const Storage = dynamic(() => import('./storage'), { ssr: false })
export default function Page() { return <Storage /> }

Webpack:

// webpack.config.js
module.exports = { experiments: { asyncWebAssembly: true, topLevelAwait: true } }

Rollup / esbuild — copy the WebAssembly asset into your output directory:

cp node_modules/@siafoundation/sia-storage/wasm/sia_storage_wasm_bg.wasm dist/

Node vs browser

Near-identical surfaces. Real differences:

• App identifier: appMeta.appId: string (hex) on browser, appMeta.id: Buffer(32) on Node.
• Numeric sizes are number on browser, bigint on Node. Byte arrays are Uint8Array on browser, Buffer on Node (Buffer is a Uint8Array subclass; both accept either as input).

API

Top-level

| | | |---|---| | initSia() | Initialize. Call once before using the SDK. | | generateRecoveryPhrase() | 12-word BIP-39 phrase. | | validateRecoveryPhrase(phrase) | Throws on invalid. | | setLogger(callback, level) | Receive SDK logs. | | encodedSize(size, dataShards, parityShards) | Encoded size after erasure coding. |

Sdk

Returned from Builder.register() or Builder.connected().

| | | |---|---| | appKey() | The AppKey for this session. | | upload(object, stream, options?) | Upload from a ReadableStream. Progress via options.onShardUploaded. | | download(object, options?) | Returns a ReadableStream. Progress via options.onShardDownloaded. | | uploadPacked(options?) | PackedUpload for batching small files into shared slabs. | | object(key) / deleteObject(key) / pinObject(object) | Object CRUD. | | updateObjectMetadata(object) | Push local metadata changes to the indexer. | | shareObject(object, validUntil) / sharedObject(url) | Create / consume share URLs. | | objectEvents(cursor?, limit) | Paginated change feed. | | hosts() / slab(id) / account() / pruneSlabs() | Indexer reads. |

Builder

new Builder(indexerUrl, appMeta)

| | | |---|---| | requestConnection() | Start the approval flow. | | responseUrl() | URL to show the user. | | waitForApproval() | Resolves once the user approves. | | register(phrase) | Finish onboarding with a new recovery phrase → Sdk. | | connected(appKey) | Reconnect with a saved AppKey → Sdk \| null. |

AppKey

new AppKey(seed) — 32-byte Uint8Array.

publicKey() · sign(message) · verifySignature(message, signature) · export()

PinnedObject

new PinnedObject() for new uploads, or sdk.object(key).

id() · size() · encodedSize() · slabs() · metadata() · updateMetadata(bytes) · createdAt() · updatedAt() · seal(appKey) · PinnedObject.open(appKey, sealed)

PackedUpload

From sdk.uploadPacked().

add(stream) · finalize() · cancel() · remaining() · length() · slabs()

License

MIT