CommandOSS TypeScript SDKs

A comprehensive collection of TypeScript SDKs for building and deploying decentralized websites on the Sui blockchain ecosystem, powered by Walrus decentralized storage.

🚀 Features

• 🌐 Decentralized Website Deployment: Deploy static websites directly to Walrus storage with Sui blockchain integration
• 📁 Advanced File Management: Browser-based file system using ZenFS with full TypeScript support
• ⚛️ React Integration: Ready-to-use React hooks and components for seamless integration
• 🔧 Type-Safe: Comprehensive TypeScript definitions throughout all packages
• 🧪 Testing Ready: Built-in test suites and development tools
• 📱 Cross-Platform: Works in both Node.js and browser environments

📚 Documentation

For comprehensive documentation, tutorials, and API reference, visit: https://ts-sdks.cmdoss.xyz

📦 Packages

Package	Version	Description
@cmdoss/walrus-site-builder	0.1.0	Core SDK for deploying decentralized websites on Walrus + Sui
@cmdoss/walrus-site-builder-react	0.1.0	React hooks and components for site-builder integration
@cmdoss/file-manager	0.1.0	Browser-based file system management with ZenFS

🏗️ Apps

Development Apps

App	Description
docs	Comprehensive documentation site built with Astro + Starlight
playground	Interactive demo application showcasing all SDK features

Docker Services

App	Docker Hub	Description
walrus	cmdoss/walrus	Latest Sui and Walrus binaries with pre-configured Publisher service (supports Publisher, Aggregator, and Daemon modes)
walrus-upload-relay	-	High-performance upload relay for Walrus TypeScript SDK with environment-based configuration
walrus-sites-portal	-	Self-hosted portal server for serving Walrus Sites as a gateway to decentralized websites
auth-proxy	-	OpenResty-based JWT validation reverse proxy for securing backend services

🐳 Docker Images & Services

Walrus

Docker Hub: cmdoss/walrus

Official Docker image containing the latest Sui and Walrus binaries with multi-architecture support (amd64/arm64).

Features:

• Pre-installed sui (v1.63.2) and walrus (v1.40.3) binaries
• Multiple operation modes: Publisher, Aggregator, Daemon (combined), or CLI tool
• Environment variable-based configuration using Gomplate
• Network support: testnet (default), mainnet

Quick Start:

# CLI Mode
docker run cmdoss/walrus:latest walrus --version
# Publisher Mode
docker run -p 31415:31415 \
-e MODE=publisher \
-e NETWORK=testnet \
-e SUI_KEYSTORE=your_private_key_here \
cmdoss/walrus:latest
# Aggregator Mode
docker run -p 31415:31415 \
-e MODE=aggregator \
-e NETWORK=testnet \
cmdoss/walrus:latest

Full Documentation →

Walrus Upload Relay

High-performance upload relay service for the Walrus TypeScript SDK, handling encoding and distribution of data shards across Walrus's decentralized storage network.

Features:

• Lightweight alternative to the full Publisher
• Environment-based configuration generation via Gomplate
• Configurable server binding via HOST and PORT
• Optimized for application-specific data uploads

Quick Start:

docker compose up

Full Documentation →

Walrus Sites Portal

Self-hosted portal server for serving Walrus Sites - decentralized websites stored on Sui blockchain and Walrus storage.

Features:

• Resolves Walrus Site domains (base36 object IDs)
• Fetches site content from Walrus aggregators
• Standard HTTP interface for decentralized websites
• SuiNS name resolution support
• Configurable allowlist/blocklist

Quick Start:

cd apps/walrus-sites-portal
docker compose up
# Portal available at http://localhost:3003

Full Documentation →

Auth Proxy

OpenResty-based JWT validation reverse proxy that adds a security layer to private backend services.

Features:

• High-performance JWT validation at the edge using Lua
• Protects backends from unauthorized requests
• Injects X-User-ID header with user identity
• Zero backend overhead for token validation

Quick Start:

docker run -p 8080:8080 \
-e JWT_SECRET=your_secret_key \
-e UPSTREAM_URL=http://backend:3000 \
cmdoss/auth-proxy:latest

Full Documentation →

Installation

# Install the core SDK
npm install @cmdoss/walrus-site-builder
# For React applications
npm install @cmdoss/walrus-site-builder-react @cmdoss/file-manager
# Peer dependencies (required)
npm install @mysten/sui @mysten/wallet-standard @mysten/walrus

Basic Usage

import{WalrusSiteBuilderSdk}from'@cmdoss/walrus-site-builder'import{ZenFsFileManager}from'@cmdoss/file-manager'import{WalrusClient}from'@mysten/walrus'import{useSuiClient,useCurrentAccount,useSignAndExecuteTransaction}from'@mysten/dapp-kit'// Initialize file managerconstfileManager=newZenFsFileManager('/workspace')awaitfileManager.initialize()// Add your filesawaitfileManager.writeFile('/index.html',newTextEncoder().encode('<h1>Hello Walrus!</h1>'))// Initialize the SDKconstsdk=newWalrusSiteBuilderSdk(walrusClient,suiClient,walletAddr,signAndExecuteTransaction)// Configure site resourcesconstwsResources={site_name: 'My Site',metadata: {description: 'A decentralized website'},routes: [['/*','/index.html']]as[string,string][]}// Create and execute deploy flowconstdeployFlow=sdk.executeSiteUpdateFlow(fileManager,wsResources)awaitdeployFlow.prepareResources()awaitdeployFlow.writeResources(5,false)// Store for 5 epochsconst{ certifiedBlobs }=awaitdeployFlow.certifyResources()const{ siteId }=awaitdeployFlow.writeSite()

React Integration

import{useZenFsWorkspace}from'@cmdoss/walrus-site-builder-react'functionMyComponent(){const{ assets, loading, fileManager }=useZenFsWorkspace()constaddFile=async()=>{awaitfileManager?.writeFile('/hello.txt','Hello World!')}return(<div><buttononClick={addFile}>AddFile</button>{loading ? 'Loading...' : `${assets.length} files loaded`}</div>)}

🏛️ Architecture

This monorepo is built with:

• 🔧 Turborepo: High-performance build system for monorepos
• 📦 PNPM: Fast, disk space efficient package manager
• 🎯 TypeScript: Type-safe development with strict configuration
• 🧪 Node.js Test Runner: Built-in testing without external dependencies
• 🎨 Biome: Fast formatter and linter for consistent code style

Package Architecture

packages/
├── site-builder/ # Core SDK - Walrus + Sui integration
│ ├── src/
│ │ ├── sdk.ts # Main SDK class
│ │ ├── deploy-flow.ts # Deployment orchestration
│ │ ├── manager.ts # Site management
│ │ ├── resource.ts # Resource handling
│ │ └── types.ts # TypeScript definitions
│ └── package.json
├── site-builder-react/ # React integration layer
│ ├── src/
│ │ └── useZenFsWorkspace.ts # File system hook
│ └── package.json
└── file-manager/ # Browser file system
├── src/
│ └── file-manager.ts # ZenFS implementation
└── package.json

🚦 Development

Prerequisites

• Node.js 18+
• PNPM 8+
• Git

Setup

# Clone the repository
git clone https://github.com/CommandOSSLabs/ts-sdks.git
cd ts-sdks
# Install dependencies
pnpm install
# Build all packages
pnpm build
# Start development mode
pnpm dev

Available Scripts

# Development
pnpm dev # Start all packages in watch mode
pnpm build # Build all packages
pnpm test# Run all tests# Code Quality
pnpm check # Run Biome linter
pnpm check:fix # Fix linting issues automatically
pnpm check:types # Type check all packages# Publishing
pnpm publish-packages # Build, test, and publish to npm

Project Structure

ts-sdks/
├── apps/
│ ├── docs/ # Documentation site (Astro)
│ └── playground/ # Demo application (Next.js)
├── packages/
│ ├── site-builder/ # Core SDK
│ ├── site-builder-react/ # React integration
│ └── file-manager/ # File system management
├── configs/
│ ├── tsconfig.base.json # Base TypeScript config
│ └── tsconfig.library.json # Library-specific config
├── package.json # Root package configuration
├── turbo.json # Turborepo configuration
└── README.md # This file

🌟 Key Features Explained

Decentralized Website Deployment

Deploy static websites directly to Walrus decentralized storage with automatic Sui blockchain integration:

• Asset Management: Automatic file processing, compression, and optimization
• Blob Storage: Efficient storage on Walrus with configurable retention periods
• Site Certification: Blockchain-verified asset integrity and ownership
• Update Management: Seamless site updates with diff-based optimization

Browser-Based File System

Full file system operations in the browser using ZenFS:

• Multiple Backends: IndexedDB, ZIP, and ISO support
• Real-time Updates: File change notifications and reactive updates
• Type Safety: Full TypeScript integration with proper error handling
• Memory Efficient: Handles large files without blocking the UI

React Integration

Production-ready React hooks and components:

• useZenFsWorkspace: Complete file system management in React
• Automatic State Management: Reactive file updates and loading states
• Error Boundaries: Proper error handling and user feedback
• Performance Optimized: Minimal re-renders and efficient updates

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes with proper tests
4. Run the test suite (pnpm test)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

📄 License

MIT License - see the LICENSE file for details.

Copyright (c) 2025 CommandOSS™ Team

🙏 Acknowledgments

• Built on Sui blockchain infrastructure
• Powered by Walrus decentralized storage
• File operations using ZenFS
• Inspired by the Rust Walrus Sites implementation

🔗 Links

• Documentation: https://ts-sdks.cmdoss.xyz
• GitHub: https://github.com/CommandOSSLabs/ts-sdks
• NPM Organization: https://www.npmjs.com/org/cmdoss
• Website: https://cmdoss.xyz

---

Built with ❤️ by the CommandOSS Team