sui-fullstack-integration

SUI Fullstack Integration

Scope: This skill covers Move ↔ TypeScript bridging: type generation, event handling, ABI wrappers. For dApp UI setup and wallet integration, use the sui-frontend skill. For PTB construction and SDK client patterns, use the sui-ts-sdk skill.

Targets: @mysten/sui 2.17.0 (^2.16), @mysten/kiosk 1.2.6 (^1.2). Tested: 2026-05-21.

Compatibility notes: @mysten/[email protected] accepts only SuiJsonRpcClient | SuiGraphQLClient, so the kiosk example in this skill instantiates a JSON-RPC client even though other examples use gRPC. Re-check on the next kiosk minor bump — once kiosk types SuiGrpcClient, the example can be migrated.

Seamlessly integrate Move smart contracts with frontend applications.

Overview

This skill bridges Move contracts and frontend code through:

• Automatic TypeScript type generation from Move ABI
• Contract API wrappers for frontend
• Event handling patterns
• Development environment setup (local node + frontend)
• End-to-end integration testing
• Error handling and user feedback

Quick Start

1. Generate Types from Move ABI

# Build Move package and generate TypeScript types
npx ts-node scripts/generate-types.ts

Output: frontend/src/types/contracts.ts

2. Create API Wrapper

// @check:skip
import { MarketplaceAPI } from './api/marketplace';

const api = new MarketplaceAPI(suiClient, packageId);
const txb = api.createListing({ nft_id: '0x...', price: 1000000000n });

3. Subscribe to Events

// @check:skip
useNFTPurchasedEvents((event) => {
  console.log(`NFT ${event.nft_id} sold for ${event.price}`);
});

4. Start Dev Environment

./scripts/dev.sh  # Starts local node + deploys + frontend

Integration Patterns

Pattern	Description
Type Generation	Auto-generate TS types from Move ABI
API Wrapper	Type-safe transaction builders
React Hooks	useMarketplaceAPI() for component integration
Event Subscriptions	Real-time updates via gRPC streaming (replaces WebSocket subscribeEvent)
Error Handling	Map Move abort codes to user messages

Move Type to TypeScript Mapping

Move Type	TypeScript Type
u8	number
u64	number | bigint
u128	bigint
bool	boolean
address	string
vector<u8>	Uint8Array
String	string
ID, UID	string

Project Structure

project/
├── contracts/
│   └── sources/*.move
├── frontend/
│   ├── src/
│   │   ├── api/           # API wrappers
│   │   ├── hooks/         # React hooks
│   │   ├── types/         # Generated types
│   │   └── lib/           # Error handling
│   └── .env.local
└── scripts/
    ├── generate-types.ts
    └── dev.sh

SDK v2 Notes

• SDK v2 uses client.core.* namespace for core RPC methods
• ESM-only: SDK v2 requires ESM ("type": "module" in package.json or .mts files)
• Use coinWithBalance for non-SUI coin transfers (not just SUI)
• Extend client capabilities with $extend() for ecosystem integration:

import { SuiJsonRpcClient, getJsonRpcFullnodeUrl } from '@mysten/sui/jsonRpc';
import { kiosk } from '@mysten/kiosk';

const client = new SuiJsonRpcClient({ url: getJsonRpcFullnodeUrl('mainnet'), network: 'mainnet' })
  .$extend(kiosk());

References

• Code Examples - Complete implementation code for all patterns

Usage

This skill is invoked by sui-full-stack after Phase 2 (contracts) and Phase 3 (frontend).

Query latest integration patterns:

// @check:skip
const patterns = await sui_docs_query({
  type: "github",
  target: "dapp-kit",
  query: "transaction building patterns"
});

Common Mistakes

❌ Manual type definitions instead of generating from Move ABI

• Problem: Types drift from contract, runtime errors in production
• Fix: Always run generate-types.ts after Move contract changes

❌ Not handling u64/u128 correctly in TypeScript

• Problem: Number overflow, precision loss for large values
• Fix: Use bigint for u64/u128, number | bigint for safety

❌ Forgetting to update package ID after redeployment

• Problem: Frontend calls old contract, all transactions fail
• Fix: Store package ID in .env, auto-update in deployment script

❌ Not mapping Move abort codes to user messages

• Problem: Generic "Transaction failed" error, users confused
• Fix: Create error code mapping in lib/errors.ts

❌ Polling for updates instead of subscribing to events

• Problem: Delayed updates, high RPC costs
• Fix: Use gRPC streaming for real-time updates (WebSocket subscribeEvent is deprecated)

❌ Not testing integration locally

• Problem: Integration bugs discovered after deployment
• Fix: Use dev.sh to run local node + contracts + frontend together

❌ Hardcoding transaction arguments

• Problem: Cannot reuse API wrappers, brittle code
• Fix: Use typed interfaces for transaction parameters

---

Bridge Move contracts and modern frontend - type-safe, real-time, production-ready integration!