Quick Start Guide
Relevant source files
The following files were used as context for generating this wiki page:This guide provides a comprehensive overview of the sui-svelte-wallet-kit, a toolkit for integrating Sui blockchain wallets into Svelte 5 applications. The package simplifies wallet connection, account management, transaction signing, and data fetching (like SUI balance and SuiNS names) by providing pre-built Svelte components and reactive utilities built with Svelte 5 runes. It supports popular Sui wallets and includes functionality for zkLogin with Google via Enoki.
This document covers installation, basic setup, core components, configuration options, and common usage patterns. It is intended for developers building dApps on the Sui network using the Svelte framework.
Sources: README.md, package.json
Installation
To get started, add the package to your project using your preferred package manager.
pnpm add sui-svelte-wallet-kit
# or
npm install sui-svelte-wallet-kit
The kit has a peer dependency on Svelte 5.
pnpm add svelte@^5.0.0
Sources: README.md:16-23, package.json:52-54
Core Architecture
The library is centered around the SuiModule component, which acts as a provider and state manager for the entire dApp. It handles wallet discovery, connection state, and data fetching, making wallet information available to all child components through reactive stores and functions.
Component Hierarchy
The following diagram illustrates the typical component structure in a dApp using the kit. The SuiModule wraps the main application content, and components like ConnectButton are used within it to trigger wallet interactions.
This diagram shows that SuiModule is the root provider, managing state and the internal ConnectModal. Other components within the dApp can then use the provided functions and reactive state.
Sources: src/lib/SuiModule/SuiModule.svelte:1120-1138, README.md:27-34
Key Components
| Component | Description | Source File |
|---|---|---|
SuiModule | The main provider component that wraps your application. It manages wallet state, connection logic, and data fetching. It must be present at the root of your dApp. | src/lib/SuiModule/SuiModule.svelte |
ConnectButton | A UI button that shows the connection status. When clicked, it opens the ConnectModal if disconnected or shows options like disconnect/switch if connected. | src/lib/index.d.ts:2 |
ConnectModal | A modal dialog, used internally by SuiModule, that lists available wallets for the user to select. It handles wallet detection and differentiates installed wallets. | src/lib/SuiModule/SuiModule.svelte:1130-1138 |
Basic Setup
To integrate the wallet kit, wrap your main application layout or page with the SuiModule component and place the ConnectButton where you want the connection UI to appear.
<script>
import { SuiModule, ConnectButton } from 'sui-svelte-wallet-kit';
const onConnect = () => {
console.log('Wallet connected');
};
</script>
<SuiModule {onConnect} autoConnect={true}>
<h1>My Sui dApp</h1>
<ConnectButton class="connect-btn" />
</SuiModule>
Sources: README.md:27-34, src/routes/+page.svelte:282-290
Wallet Connection Flow
The connection process is initiated by the user and handled by the SuiModule and its internal ConnectModal. The library also supports automatically reconnecting to a previously selected wallet.
Initial Connection
The following sequence diagram shows the steps involved when a user connects their wallet for the first time.
This flow demonstrates how components interact to establish a wallet connection, update the application state, and persist the connection for future sessions.
Sources: src/lib/SuiModule/SuiModule.svelte:699-720, 722-763
Auto-Connection
If autoConnect is set to true, SuiModule will attempt to reconnect to the last used wallet on page load. It retrieves the wallet's name from localStorage and, if the wallet is installed, initiates the connection process automatically.
This flow is managed internally by an $effect within SuiModule.
Sources: src/lib/SuiModule/SuiModule.svelte:315-328, 1101-1111
Configuration
You can customize the wallet kit's behavior using props on the SuiModule component.
SuiModule Props
| Prop | Type | Default | Description |
|---|---|---|---|
onConnect | () => void | undefined | A callback function that runs after a wallet successfully connects. |
autoConnect | boolean | false | If true, automatically reconnects to the last used wallet on page load. |
autoSuiNS | boolean | true | If true, automatically fetches SuiNS names for the connected account. |
autoSuiBalance | boolean | true | If true, automatically fetches the SUI balance for the connected account. |
walletConfig | WalletConfig | {} | An object to customize wallet display names and ordering in the ConnectModal. See Wallet Configuration. |
zkLoginGoogle | ZkLoginGoogleConfig | null | Configuration object to enable "Sign in with Google" via Enoki. See zkLogin (Enoki). |
Sources: src/lib/SuiModule/SuiModule.svelte:1091-1100, src/lib/SuiModule/types.ts:1330-1340
Wallet Configuration
The walletConfig prop allows you to customize the appearance of the wallet connection modal.
customNames: An object to rename wallets.ordering: An array of wallet names to define a specific display order.
<script lang="ts">
import type { WalletConfig } from 'sui-svelte-wallet-kit';
const walletConfig: WalletConfig = {
customNames: {
'Suiet': 'Suiet Wallet',
},
ordering: [
'Sign in with Google',
'Slush — A Sui wallet',
'Suiet'
]
};
</script>
Sources: README.md:39-61, src/routes/+page.svelte:273-280, src/lib/SuiModule/types.ts:511-515
zkLogin (Enoki) Google
Enable Google sign-in by providing the zkLoginGoogle configuration. This requires an API key from the Enoki Portal and a Google OAuth Client ID.
This diagram shows the structure of the ZkLoginGoogleConfig object.
Example:
<script lang="ts">
import type { ZkLoginGoogleConfig } from 'sui-svelte-wallet-kit';
const zkLoginGoogle: ZkLoginGoogleConfig = {
apiKey: 'ENOKI_API_KEY',
googleClientId: 'GOOGLE_CLIENT_ID.apps.googleusercontent.com',
network: 'testnet'
};
</script>
<SuiModule {zkLoginGoogle}>
<!-- ... -->
</SuiModule>
When configured, a "Sign in with Google" option appears in the ConnectModal. The kit validates the configuration and probes the Enoki API key for validity.
Sources: README.md:143-160, src/lib/SuiModule/types.ts:517-524, src/lib/SuiModule/SuiModule.svelte:1026-1055
API and State Management
The package exports several functions and reactive stores (hooks) for interacting with the wallet and accessing its state.
Reactive State (Hooks)
These functions return reactive Svelte 5 runes that update automatically when the wallet state changes.
| Hook | Return Type | Description |
|---|---|---|
useCurrentAccount() | SuiAccount | undefined | The currently active wallet account. |
useAccounts() | SuiAccount[] | An array of all accounts available from the connected wallet. |
useCurrentWallet() | SuiWallet | undefined | Information about the currently connected wallet. |
suiBalance | ReadableStore<string|null> | The SUI balance of the current account. |
suiNames | ReadableStore<string[]> | The SuiNS names associated with the current account. |
useSuiClient() | SuiClient | An instance of the SuiClient for the current network. |
Sources: src/lib/index.d.ts:9-31, src/lib/SuiModule/index.js:4-29
Reactive Data Flow
The library uses $effect to react to state changes. For example, when the current account changes, effects are triggered to fetch the new account's balance and SuiNS name.
This diagram shows how a change in the active account triggers automatic data fetching for balance and SuiNS.
Sources: src/lib/SuiModule/SuiModule.svelte:1113-1128
Core Functions
| Function | Description |
|---|---|
connect(wallet) | Programmatically connect to a specific wallet instance. |
disconnect() | Disconnects the current wallet and clears session data. |
switchWallet(options?) | Opens the ConnectModal to allow the user to switch to a different wallet. |
switchAccount(selector) | Switches the active account to another one from the list of available accounts. |
signAndExecuteTransaction(tx) | Prompts the user to sign and submit a transaction to the network. |
signMessage(message) | Prompts the user to sign a personal message. |
refreshSuiBalance(address?) | Manually triggers a refresh of the SUI balance for a given address. |
Sources: README.md:168-180, src/lib/SuiModule/index.d.ts:14-25
Transaction & Message Signing
The signAndExecuteTransaction and signMessage functions delegate the signing operation to the connected wallet's adapter.
This diagram illustrates the flow for signing and executing a transaction, where the kit acts as a mediator between the dApp and the wallet adapter.
Sources: src/lib/SuiModule/SuiModule.svelte:874-902, 904-955
Summary
The sui-svelte-wallet-kit provides a robust and developer-friendly solution for integrating Sui wallets into Svelte 5 applications. By leveraging a central SuiModule provider, pre-built UI components, and a reactive state management system based on Svelte 5 runes, it significantly reduces the boilerplate code required for dApp development. Its configurable nature, support for zkLogin, and comprehensive API make it a powerful tool for building on the Sui blockchain.
Sources: README.md:7-14, package.json:3-4