@mysten/dapp-kit-react 2.0.2 → 2.1.0

package/docs/getting-started/create-dapp.md

@@ -0,0 +1,151 @@
+# @mysten/create-dapp
+
+> Create a Sui app with one command using the create-dapp CLI scaffolding tool.
+
+`@mysten/create-dapp` is a CLI tool that scaffolds a complete Sui app project with best practices
+built in.
+
+## Quick start
+
+```npm
+npm create @mysten/dapp
+```
+
+The CLI prompts you to choose a template and project name, then creates a ready-to-run project.
+
+## Templates
+
+### react-client-dapp
+
+A basic React app that demonstrates wallet connection and fetching owned objects:
+
+- Wallet connection with `ConnectButton`
+- Display connected wallet address
+- List objects owned by the connected wallet
+- Clean, modern UI with Tailwind CSS
+
+### react-e2e-counter
+
+A complete end-to-end example with Move smart contract integration:
+
+- Move counter contract in `move/counter/`
+- TypeScript bindings generated with `@mysten/codegen`
+- Create, increment, and reset counters
+- MVR (Move Registry) name resolution for package IDs
+- Full transaction signing and execution
+
+## Tech stack
+
+Both templates include:
+
+- [React](https://react.dev/) - UI framework
+- [TypeScript](https://www.typescriptlang.org/) - Type safety
+- [Vite](https://vitejs.dev/) - Fast build tooling
+- [Tailwind CSS v4](https://tailwindcss.com/) - Utility-first styling
+- [Lucide React](https://lucide.dev/) - Modern icons
+- [`@mysten/dapp-kit-react`](/dapp-kit) - Wallet connection and blockchain interaction
+- [pnpm](https://pnpm.io/) - Package management
+
+The e2e-counter template also includes:
+
+- [`@mysten/codegen`](/codegen) - Generate TypeScript from Move code
+
+## Project structure
+
+### react-client-dapp
+
+```
+src/
+├── components/ui/     # Reusable UI components (Card)
+├── lib/utils.ts       # Utility functions
+├── App.tsx            # Main application
+├── WalletStatus.tsx   # Wallet connection display
+├── OwnedObjects.tsx   # Object list component
+├── dApp-kit.ts        # dApp Kit configuration
+└── index.css          # Tailwind CSS theme
+```
+
+### react-e2e-counter
+
+```
+src/
+├── components/ui/     # UI components (Button, Card)
+├── contracts/         # Generated TypeScript bindings
+├── lib/utils.ts       # Utility functions
+├── App.tsx            # Main application
+├── Counter.tsx        # Counter display and controls
+├── CreateCounter.tsx  # Counter creation
+├── dApp-kit.ts        # dApp Kit configuration
+├── constants.ts       # Package IDs per network
+└── index.css          # Tailwind CSS theme
+move/
+└── counter/           # Move smart contract
+```
+
+## Using the e2e-counter template
+
+### Step 1: Deploy the Move contract
+
+First, install the [Sui CLI](https://docs.sui.io/build/install) and set up testnet:
+
+```bash
+sui client new-env --alias testnet --rpc https://fullnode.testnet.sui.io:443
+sui client switch --env testnet
+```
+
+Get testnet SUI from the [faucet](https://faucet.sui.io), then publish:
+
+```bash
+cd move
+sui client publish --gas-budget 100000000 counter
+```
+
+### Step 2: Configure the package ID
+
+Copy the `packageId` from the publish output to `src/constants.ts`:
+
+```ts
+
+```
+
+### Step 3: Generate TypeScript bindings
+
+```bash
+pnpm codegen
+```
+
+This generates type-safe functions in `src/contracts/` for interacting with your Move modules.
+
+### Step 4: Start development
+
+```bash
+pnpm install
+pnpm dev
+```
+
+## Customizing the UI
+
+The templates use [Tailwind CSS v4](https://tailwindcss.com/docs) with
+[shadcn/ui](https://ui.shadcn.com/)-style components. The UI components in `src/components/ui/` can
+be customized or extended.
+
+To add more components, copy them from the
+[shadcn/ui components](https://ui.shadcn.com/docs/components) documentation and adapt them to your
+project.
+
+Theme variables are defined in `src/index.css` using Tailwind's `@theme` directive.
+
+## CLI options
+
+You can skip prompts with command-line flags:
+
+```bash
+# Create with specific template
+npm create @mysten/dapp -- -t react-e2e-counter
+
+# Create with specific name
+npm create @mysten/dapp -- -n my-app
+
+# Create with both
+npm create @mysten/dapp -- -t react-client-dapp -n my-app
+```

package/docs/getting-started/next-js.md

@@ -0,0 +1,163 @@
+# Next.js
+
+> Set up dApp Kit in a Next.js application.
+
+This guide covers integrating dApp Kit into Next.js applications, including handling server-side
+rendering (SSR).
+
+## Installation
+
+```npm
+npm i @mysten/dapp-kit-react @mysten/sui
+```
+
+## Setup
+
+### Step 1: Create a dApp Kit instance
+
+```ts
+// app/dapp-kit.ts
+
+const GRPC_URLS = {
+	testnet: 'https://fullnode.testnet.sui.io:443',
+} as const;
+
+	networks: ['testnet'],
+	createClient: (network) => new SuiGrpcClient({ network, baseUrl: GRPC_URLS[network] }),
+});
+
+// Register types for hook type inference
+declare module '@mysten/dapp-kit-react' {
+	interface Register {
+		dAppKit: typeof dAppKit;
+	}
+}
+```
+
+### Step 2: Create a client-only wrapper
+
+Wallet detection only works in the browser, so dApp Kit components must be client-side rendered:
+
+```tsx
+// app/DAppKitClientProvider.tsx
+'use client';
+
+	return <DAppKitProvider dAppKit={dAppKit}>{children}</DAppKitProvider>;
+}
+
+```
+
+### Step 3: Use dynamic import in pages
+
+Use Next.js dynamic imports with `ssr: false` to prevent server-side rendering:
+
+```tsx
+// app/page.tsx
+
+const DAppKitClientProvider = dynamic(
+	() => import('./DAppKitClientProvider').then((mod) => mod.DAppKitClientProvider),
+	{ ssr: false },
+);
+
+const ConnectButton = dynamic(
+	() => import('./DAppKitClientProvider').then((mod) => mod.ConnectButton),
+	{ ssr: false, loading: () => <button disabled>Loading...</button> },
+);
+
+	return (
+		<DAppKitClientProvider>
+			<main>
+				<h1>My Sui dApp</h1>
+				<ConnectButton />
+			</main>
+		</DAppKitClientProvider>
+	);
+}
+```
+
+## Alternative: single client component
+
+For simpler apps, create a single client component:
+
+```tsx
+// app/WalletApp.tsx
+'use client';
+
+function WalletStatus() {
+	const account = useCurrentAccount();
+	const dAppKit = useDAppKit();
+
+	if (!account) {
+		return <p>Connect your wallet to get started</p>;
+	}
+
+	async function handleTransfer() {
+		const tx = new Transaction();
+		tx.transferObjects([coinWithBalance({ balance: 1_000_000 })], account.address);
+		const result = await dAppKit.signAndExecuteTransaction({ transaction: tx });
+
+		if (result.FailedTransaction) {
+			throw new Error(`Transaction failed: ${result.FailedTransaction.status.error?.message}`);
+		}
+
+		alert(`Transaction: ${result.Transaction.digest}`);
+	}
+
+	return (
+		<div>
+			<p>Connected: {account.address}</p>
+			<button onClick={handleTransfer}>Send Transaction</button>
+		</div>
+	);
+}
+
+	return (
+		<DAppKitProvider dAppKit={dAppKit}>
+			<ConnectButton />
+			<WalletStatus />
+		</DAppKitProvider>
+	);
+}
+```
+
+```tsx
+// app/page.tsx
+
+const WalletApp = dynamic(() => import('./WalletApp'), {
+	ssr: false,
+	loading: () => <p>Loading wallet...</p>,
+});
+
+	return (
+		<main>
+			<h1>My Sui dApp</h1>
+			<WalletApp />
+		</main>
+	);
+}
+```
+
+## Key considerations
+
+### Why SSR: false?
+
+Wallets are detected through the browser's `window` object and the Wallet Standard API. This
+detection cannot happen on the server, so components that interact with wallets must be client-side
+only.
+
+### Hydration errors
+
+If you see hydration errors, ensure all dApp Kit components are wrapped with `ssr: false` dynamic
+imports or are inside a `'use client'` component that's dynamically imported.
+
+## Example application
+
+See the complete
+[Next.js example](https://github.com/MystenLabs/ts-sdks/tree/main/packages/dapp-kit/examples/next-js/simple)
+on GitHub.
+
+## Next steps
+
+- [React Hooks](/dapp-kit/react/hooks) - All available hooks
+- [React Components](/dapp-kit/react/components) - UI components
+- [Theming](/dapp-kit/theming) - Customize appearance

package/docs/getting-started/react.md

@@ -0,0 +1,172 @@
+# React
+
+> Set up dApp Kit in a React application.
+
+This guide walks you through integrating dApp Kit into a React application.
+
+## Quick start with create-dapp
+
+The fastest way to get started is using our CLI tool:
+
+```npm
+npm create @mysten/dapp
+```
+
+This creates a new project with:
+
+- React + TypeScript + Vite
+- Tailwind CSS v4 for styling
+- dApp Kit pre-configured
+- Example wallet connection UI
+
+Choose from two templates:
+
+- **react-client-dapp**: Basic wallet connection and object display
+- **react-e2e-counter**: Full example with Move smart contract and codegen
+
+See the [create-dapp guide](/dapp-kit/getting-started/create-dapp) for more details.
+
+---
+
+## Manual installation
+
+```npm
+npm i @mysten/dapp-kit-react @mysten/sui
+```
+
+## Setup
+
+### Step 1: Create a dApp Kit instance
+
+Create a file to configure your dApp Kit instance:
+
+```tsx
+// dapp-kit.ts
+
+const GRPC_URLS = {
+	testnet: 'https://fullnode.testnet.sui.io:443',
+};
+
+	networks: ['testnet'],
+	createClient: (network) => new SuiGrpcClient({ network, baseUrl: GRPC_URLS[network] }),
+});
+
+// Register types for hook type inference
+declare module '@mysten/dapp-kit-react' {
+	interface Register {
+		dAppKit: typeof dAppKit;
+	}
+}
+```
+
+### Step 2: Add the provider
+
+Wrap your application with `DAppKitProvider`:
+
+```tsx
+// App.tsx
+
+	return (
+		<DAppKitProvider dAppKit={dAppKit}>
+			<div>
+				<h1>My Sui dApp</h1>
+				<ConnectButton />
+				<WalletStatus />
+			</div>
+		</DAppKitProvider>
+	);
+}
+```
+
+### Step 3: Display connection status
+
+Use hooks to access wallet state:
+
+```tsx
+
+function WalletStatus() {
+	const account = useCurrentAccount();
+	const wallet = useCurrentWallet();
+	const network = useCurrentNetwork();
+
+	if (!account) {
+		return <p>Connect your wallet to get started</p>;
+	}
+
+	return (
+		<div>
+			<p>Wallet: {wallet?.name}</p>
+			<p>Address: {account.address}</p>
+			<p>Network: {network}</p>
+		</div>
+	);
+}
+```
+
+### Step 4: Execute transactions
+
+Use the `useDAppKit` hook to sign and execute transactions:
+
+```tsx
+
+function TransferButton() {
+	const dAppKit = useDAppKit();
+	const account = useCurrentAccount();
+
+	async function handleTransfer() {
+		const tx = new Transaction();
+		tx.transferObjects([coinWithBalance({ balance: 1_000_000 })], 'RECIPIENT_ADDRESS');
+
+		try {
+			const result = await dAppKit.signAndExecuteTransaction({ transaction: tx });
+
+			if (result.FailedTransaction) {
+				throw new Error(`Transaction failed: ${result.FailedTransaction.status.error?.message}`);
+			}
+
+			console.log('Transaction digest:', result.Transaction.digest);
+		} catch (error) {
+			console.error('Transaction failed:', error);
+		}
+	}
+
+	return (
+		<button onClick={handleTransfer} disabled={!account}>
+			Send Transaction
+		</button>
+	);
+}
+```
+
+## Available hooks
+
+| Hook                                                                 | Description                              |
+| -------------------------------------------------------------------- | ---------------------------------------- |
+| [`useDAppKit`](/dapp-kit/react/hooks/use-dapp-kit)                   | Access the dApp Kit instance and actions |
+| [`useWalletConnection`](/dapp-kit/react/hooks/use-wallet-connection) | Full connection state with status flags  |
+| [`useCurrentAccount`](/dapp-kit/react/hooks/use-current-account)     | Currently selected account               |
+| [`useCurrentWallet`](/dapp-kit/react/hooks/use-current-wallet)       | Currently connected wallet               |
+| [`useCurrentNetwork`](/dapp-kit/react/hooks/use-current-network)     | Current network                          |
+| [`useCurrentClient`](/dapp-kit/react/hooks/use-current-client)       | SuiClient for current network            |
+| [`useWallets`](/dapp-kit/react/hooks/use-wallets)                    | List of available wallets                |
+
+## Components
+
+| Component                                                    | Description                       |
+| ------------------------------------------------------------ | --------------------------------- |
+| [`ConnectButton`](/dapp-kit/react/components/connect-button) | Complete wallet connection UI     |
+| [`ConnectModal`](/dapp-kit/react/components/connect-modal)   | Standalone wallet selection modal |
+| [`DAppKitProvider`](/dapp-kit/react/dapp-kit-provider)       | Context provider for hooks        |
+
+## Example application
+
+See the complete
+[React example](https://github.com/MystenLabs/ts-sdks/tree/main/packages/dapp-kit/examples/react/simple)
+on GitHub.
+
+## Next steps
+
+- [`DAppKitProvider`](/dapp-kit/react/dapp-kit-provider) - Provider configuration
+- [Hooks Reference](/dapp-kit/react/hooks) - All available hooks
+- [Components](/dapp-kit/react/components) - UI components
+- [Theming](/dapp-kit/theming) - Customize appearance

package/docs/getting-started/vue.md

@@ -0,0 +1,193 @@
+# Vue
+
+> Set up dApp Kit in a Vue application.
+
+This guide walks you through integrating dApp Kit into a Vue application using Web Components and
+direct store access.
+
+## Installation
+
+```npm
+npm i @mysten/dapp-kit-core @mysten/sui @nanostores/vue
+```
+
+## Setup
+
+### Step 1: Create a dApp Kit instance
+
+```ts
+// src/dapp-kit.ts
+
+const GRPC_URLS = {
+	testnet: 'https://fullnode.testnet.sui.io:443',
+};
+
+	networks: ['testnet'],
+	createClient: (network) => new SuiGrpcClient({ network, baseUrl: GRPC_URLS[network] }),
+});
+```
+
+### Step 2: Register web components
+
+Import the web components in your app entry point:
+
+```ts
+// src/main.ts
+
+createApp(App).mount('#app');
+```
+
+### Step 3: Use the connect button
+
+```vue
+<script setup lang="ts">
+
+</script>
+
+<template>
+	<div>
+		<h1>My Sui dApp</h1>
+		<mysten-dapp-kit-connect-button :instance="dAppKit" />
+	</div>
+</template>
+```
+
+### Step 4: Access connection state
+
+Use `@nanostores/vue` for reactive state:
+
+```vue
+<script setup lang="ts">
+
+const connection = useStore(dAppKit.stores.$connection);
+const network = useStore(dAppKit.stores.$currentNetwork);
+</script>
+
+<template>
+	<div>
+		<mysten-dapp-kit-connect-button :instance="dAppKit" />
+
+		<div v-if="connection.account">
+			<p>Wallet: {{ connection.wallet?.name }}</p>
+			<p>Address: {{ connection.account.address }}</p>
+			<p>Network: {{ network }}</p>
+		</div>
+		<p v-else>Connect your wallet to get started</p>
+	</div>
+</template>
+```
+
+### Step 5: Execute transactions
+
+```vue
+<script setup lang="ts">
+
+const connection = useStore(dAppKit.stores.$connection);
+
+async function handleTransfer() {
+	const tx = new Transaction();
+	tx.transferObjects([coinWithBalance({ balance: 1_000_000 })], connection.value.account!.address);
+
+	try {
+		const result = await dAppKit.signAndExecuteTransaction({ transaction: tx });
+
+		if (result.FailedTransaction) {
+			throw new Error(`Transaction failed: ${result.FailedTransaction.status.error?.message}`);
+		}
+
+		alert(`Transaction: ${result.Transaction.digest}`);
+	} catch (error) {
+		console.error('Transaction failed:', error);
+	}
+}
+</script>
+
+<template>
+	<div>
+		<mysten-dapp-kit-connect-button :instance="dAppKit" />
+
+		<button v-if="connection.account" @click="handleTransfer">Send Transaction</button>
+	</div>
+</template>
+```
+
+## Complete example
+
+```vue
+<script setup lang="ts">
+
+const connection = useStore(dAppKit.stores.$connection);
+const network = useStore(dAppKit.stores.$currentNetwork);
+
+async function handleTransfer() {
+	if (!connection.value.account) return;
+
+	const tx = new Transaction();
+	tx.transferObjects([coinWithBalance({ balance: 1_000_000 })], connection.value.account.address);
+
+	try {
+		const result = await dAppKit.signAndExecuteTransaction({ transaction: tx });
+
+		if (result.FailedTransaction) {
+			throw new Error(`Transaction failed: ${result.FailedTransaction.status.error?.message}`);
+		}
+
+		alert(`Transaction successful: ${result.Transaction.digest}`);
+	} catch (error) {
+		console.error('Transaction failed:', error);
+	}
+}
+</script>
+
+<template>
+	<div class="app">
+		<h1>My Sui dApp</h1>
+		<mysten-dapp-kit-connect-button :instance="dAppKit" />
+
+		<div v-if="connection.account" class="wallet-info">
+			<p>Wallet: {{ connection.wallet?.name }}</p>
+			<p>Address: {{ connection.account.address }}</p>
+			<p>Network: {{ network }}</p>
+			<button @click="handleTransfer">Send Test Transaction</button>
+		</div>
+		<p v-else>Connect your wallet to get started</p>
+	</div>
+</template>
+```
+
+## Web components
+
+Vue works with dApp Kit's Web Components through property binding:
+
+| Component      | Usage                                                                  |
+| -------------- | ---------------------------------------------------------------------- |
+| Connect Button | `<mysten-dapp-kit-connect-button :instance="dAppKit" />`               |
+| Connect Modal  | `<mysten-dapp-kit-connect-modal :instance="dAppKit" :open="isOpen" />` |
+
+See [Web Components](/dapp-kit/web-components/connect-button) for full documentation.
+
+## Available stores
+
+Access these stores through `dAppKit.stores`:
+
+| Store             | Description                                       |
+| ----------------- | ------------------------------------------------- |
+| `$connection`     | Connection state with wallet, account, and status |
+| `$currentNetwork` | Current network string                            |
+| `$currentClient`  | SuiClient for current network                     |
+| `$wallets`        | List of available wallets                         |
+
+See [State Management](/dapp-kit/state) for full documentation.
+
+## Example application
+
+See the complete
+[Vue example](https://github.com/MystenLabs/ts-sdks/tree/main/packages/dapp-kit/examples/vue/simple)
+on GitHub.
+
+## Next steps
+
+- [Web Components](/dapp-kit/web-components/connect-button) - Component documentation
+- [State Management](/dapp-kit/state) - Store details
+- [Actions](/dapp-kit/actions/connect-wallet) - All available actions
+- [Theming](/dapp-kit/theming) - Customize appearance