Skip to content
Swarm ID

Quick Start

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

Installation

Terminal window
# 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',
  },
  onAuthChange: (authenticated) => {
    console.log('Auth status:', authenticated)
  },
})


// 2. Initialize (creates hidden iframe)
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()
// Open authentication page in new window/browser tab (useful for custom UI)
const authUrl = client.connect()
console.log('Authentication opened at:', authUrl)


// 4. Check if user is authenticated
const status = await client.checkAuthStatus()


// 5. Upload data (after authentication)
if (status.authenticated) {
  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:

OptionTypeRequiredDescription
iframeOriginstringYesOrigin of the Swarm ID iframe (e.g., https://swarm-id.snaha.net)
metadataobjectNoApp metadata shown during authentication
metadata.namestringNoYour app’s name
metadata.descriptionstringNoBrief description of your app
onAuthChangefunctionNoCallback when authentication status changes

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

Terminal window
# 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:3000 — that’s it!

  • Demo app runs on port 3000
  • Identity UI runs on port 5174
  • 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