# Sui Fullstack Integration

> Use when bridging Move contracts to TypeScript — generating TS types from Move ABI, creating contract API wrappers, subscribing to on-chain events, or building E2E integration tests. Triggers on "generate types from Move", "event listener", "contract ABI", "Move to TypeScript", "subscribe to events", "ABI wrapper", or any Move↔frontend bridging task. This is the CONTRACT-TO-CODE BRIDGE, not project setup (sui-full-stack) or UI/wallet (sui-frontend).

- Skill: `tomevault-io/sui-fullstack-integration` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/sui-fullstack-integration`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/sui-fullstack-integration/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/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.

**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

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

Output: `frontend/src/types/contracts.ts`

### 2. Create API Wrapper

```typescript
import { MarketplaceAPI } from './api/marketplace';

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

### 3. Subscribe to Events

```typescript
useNFTPurchasedEvents((event) => {
  console.log(`NFT ${event.nft_id} sold for ${event.price}`);
});
```

### 4. Start Dev Environment

```bash
./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:

```typescript
import { SuiGrpcClient } from '@mysten/sui/grpc';
import { kiosk } from '@mysten/kiosk';

const client = new SuiGrpcClient({ network: 'mainnet', baseUrl: 'https://fullnode.mainnet.sui.io:443' })
  .$extend(kiosk());
```

## References

- **[Code Examples](references/examples.md)** - 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:
```typescript
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!**

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/first-mover-tw) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->