Quick Start

Get Swarm ID integrated into your dApp in just a few steps.

Installation

# Using pnpm (recommended)
pnpm add @snaha/swarm-id

# Using npm
npm install @snaha/swarm-id

# Using yarn
yarn add @snaha/swarm-id

Basic Usage

import { SwarmIdClient } from '@snaha/swarm-id'

// 1. Create the client
const client = new SwarmIdClient({
  iframeOrigin: 'https://swarm-id.snaha.net',
  metadata: {
    name: 'My dApp',
    description: 'A demo Swarm application',
  },
  onConnectionChange: (info) => {
    console.log('Connection changed:', info.identity?.name, 'canUpload=', info.canUpload)
  },
})

// 2. Initialize (creates hidden iframe; populates client.connectionInfo)
await client.initialize()

// 3a. Option A: Use iframe authentication button
// The iframe will show a connect/disconnect button automatically

// 3b. Option B: Manual authentication with connect()
// Opens the authentication page in a new window/tab (useful for custom UI)
await client.connect()

// 4. Read current connection state synchronously
const info = client.connectionInfo

// 5. Upload data (requires authentication AND upload capability — a connected
//    user can still have canUpload=false if they have no postage stamp and no
//    subsidised gateway is configured)
if (info.identity && info.canUpload) {
  const result = await client.uploadData(new TextEncoder().encode('Hello, Swarm!'))
  console.log('Uploaded:', result.reference)
}

// 6. Cleanup when done
client.destroy()

Configuration Options

The SwarmIdClient constructor accepts the following options:

Option	Type	Required	Description
iframeOrigin	string	Yes	Origin of the Swarm ID iframe (e.g., https://swarm-id.snaha.net)
metadata	object	No	App metadata shown during authentication
metadata.name	string	No	Your app’s name
metadata.description	string	No	Brief description of your app
onConnectionChange	function	No	Callback when the dApp-visible connection state changes (identity, stamp, account, auth)

Data Operations

Note: Data operations require the user to be authenticated first. Use client.connect() or the iframe button to authenticate.

Upload Data

// Simple upload
const result = await client.uploadData(data)

// Upload with encryption
const result = await client.uploadData(data, { encrypt: true })

// Upload with progress tracking
const result = await client.uploadData(data, {}, (progress) => {
  console.log(`${progress.percent}% uploaded`)
})

Download Data

// Download by reference
const data = await client.downloadData(reference)

// Download encrypted data (reference will be 128 chars instead of 64)
const data = await client.downloadData(encryptedReference)

File Operations

// Upload a file
const result = await client.uploadFile(file, 'myfile.txt')

// Download a file
const fileData = await client.downloadFile(reference)
console.log(fileData.name, fileData.data)

Local Development

# Clone the repository
git clone https://github.com/snaha/swarm-id

# Install dependencies
pnpm install

# Start both demo and identity UI
pnpm dev

Open http://localhost:3500 — that’s it!

• Demo app runs on port 3500
• Identity UI runs on port 5500
• No HTTPS, certificates, or custom domains required (localhost is a secure context)

For advanced setup (local Bee cluster, SSH tunnels for real-domain testing, known dev keys), see the Local Development guide.

Import & Export

The library also supports account backup and recovery via encrypted .swarmid files and Swarm-based restoration. See the Architecture Overview for details on the file format and flows, and the API Reference for function documentation.

Next Steps

• Architecture Overview - Understand how Swarm ID works
• API Reference - Detailed API documentation