A TypeScript SDK for building and deploying decentralized websites on Walrus + Sui, with integrated file operations using zenfs.
npm install @cmdoss/walrus-site-builderA TypeScript SDK for building and deploying decentralized websites on Walrus + Sui, with integrated file operations using zenfs.
- ๐ Site Management: Create, update, and manage decentralized websites
- ๐ File Operations: Advanced file handling with zenfs integration
- ๐ง Type Safety: Full TypeScript support with comprehensive type definitions
- ๐งช Testing: Complete test suite with Node.js test runner
- ๐ Web Compatible: Works in both Node.js and browser environments
``bash`
npm install @cmdoss/walrus-site-builder
`typescript
import { WalrusSiteBuilderSdk } from '@cmdoss/walrus-site-builder'
import { ZenFsFileManager } from '@cmdoss/file-manager'
import { SuiClient } from '@mysten/sui/client'
import { WalrusClient } from '@mysten/walrus'
const suiClient = new SuiClient({ url: 'https://fullnode.example.com' })
const walrusClient = new WalrusClient({ suiClient })
const fileManager = new ZenFsFileManager()
const sdk = new WalrusSiteBuilderSdk({
suiClient,
walrusClient,
fileManager,
signAndExecuteTransaction: async (tx) => {
// Your wallet signing implementation
}
})
// Deploy a site
await sdk.publishSite({
siteDataPath: '/path/to/site',
numEpochs: 100
})
`
This SDK uses zenfs for file operations, providing:
- Cross-platform compatibility: Works in Node.js and browsers
- Memory-efficient: Handles large files without blocking
- Type-safe: Full TypeScript integration
- Feature-rich: Advanced file operations and metadata
The SDK follows a modular architecture:
`mermaid`
graph TD
A["๐ WalrusSiteBuilderSdk
Entry Point"] --> B["๐ UpdateWalrusSiteFlow
Deployment Orchestrator"]
B --> C["๐ prepareResources
Compute Diff & Hashes"]
C --> D["๐ค writeResources
Upload to Walrus"]
D --> E["โ
certifyResources
Associate Certificates"]
E --> F["โ๏ธ writeSite
Create Site on Sui"]
A --> G["๐ IFileManager
File Operations"]
G --> H["๐ Node.js & Browser
Cross-platform"]
style A fill:#4F46E5,stroke:#312E81,color:#fff,stroke-width:3px
style B fill:#7C3AED,stroke:#5B21B6,color:#fff,stroke-width:3px
style C fill:#EC4899,stroke:#BE185D,color:#fff,stroke-width:2px
style D fill:#F97316,stroke:#C2410C,color:#fff,stroke-width:2px
style E fill:#06B6D4,stroke:#0E7490,color:#fff,stroke-width:2px
style F fill:#10B981,stroke:#065F46,color:#fff,stroke-width:2px
style G fill:#8B5CF6,stroke:#6D28D9,color:#fff,stroke-width:3px
style H fill:#6366F1,stroke:#3730A3,color:#fff,stroke-width:2px
Key Components:
- WalrusSiteBuilderSdk: Main entry point for site deployment
- UpdateWalrusSiteFlow: Orchestrates the deployment lifecycle
- prepareResources(): Computes file diff and generates hasheswriteResources()
- : Uploads blobs to Walrus storagecertifyResources()
- : Associates certificates with on-chain datawriteSite()`: Creates/updates Site object on Sui blockchain
-
- IFileManager: Abstraction for file operations (supports both Node.js and browser)
For more details, see AGENTS.md in the root repository.
See the playground app for comprehensive examples showcasing:
- Site creation and deployment
- File management
- Wallet integration
- Resource management
- Site updates and publishing
Refer to the package source in src/ for detailed API documentation.
1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request
MIT
- Built on Sui blockchain infrastructure
- Uses Walrus for decentralized storage
- File operations powered by zenfs
- Inspired by the original Rust implementation