Skip to main content

​
Setting Up Providers

Providers are essential React context components that manage the state and configuration of your Sui dApp. This guide will show you how to set up all the necessary providers.

​
Required Providers

Your Sui dApp needs three providers wrapped in the correct order:
  1. QueryClientProvider - From @tanstack/react-query (outermost)
  2. SuiClientProvider - Manages network connections
  3. WalletProvider - Manages wallet state (innermost)

​
Basic Setup for Next.js

Since we’re using Next.js 15 with the App Router, we need to create a client component for the providers. Create a new file:
src/components/providers.tsx
"use client";

import {
  createNetworkConfig,
  SuiClientProvider,
  WalletProvider,
} from "@mysten/dapp-kit";
import { getFullnodeUrl } from "@mysten/sui/client";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { ReactNode } from "react";

// Import dApp Kit CSS
import "@mysten/dapp-kit/dist/index.css";

// Configure the networks you want to connect to
const { networkConfig } = createNetworkConfig({
  localnet: { url: getFullnodeUrl("localnet") },
  mainnet: { url: getFullnodeUrl("mainnet") },
  testnet: { url: getFullnodeUrl("testnet") },
  devnet: { url: getFullnodeUrl("devnet") },
});

// Create a QueryClient instance
const queryClient = new QueryClient();

export function Providers({ children }: { children: ReactNode }) {
  return (
    <QueryClientProvider client={queryClient}>
      <SuiClientProvider networks={networkConfig} defaultNetwork="testnet">
        <WalletProvider autoConnect={true}>{children}</WalletProvider>
      </SuiClientProvider>
    </QueryClientProvider>
  );
}

​
Provider Details

​
1. QueryClientProvider

The QueryClientProvider from React Query manages all the caching and data fetching state. 
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";

const queryClient = new QueryClient();

<QueryClientProvider client={queryClient}>
  {/* Your app */}
</QueryClientProvider>;
Configuration options: 
const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      // Time before queries are considered stale (default: 0)
      staleTime: 60 * 1000, // 1 minute
      // Time before inactive queries are garbage collected
      gcTime: 5 * 60 * 1000, // 5 minutes
      // Retry failed queries
      retry: 3,
    },
  },
});

​
2. SuiClientProvider

The SuiClientProvider manages connections to Sui blockchain networks. Props:
  • networks - Network configuration object
  • defaultNetwork - The network to connect to initially (optional)
import { createNetworkConfig, SuiClientProvider } from "@mysten/dapp-kit";
import { getFullnodeUrl } from "@mysten/sui/client";

const { networkConfig } = createNetworkConfig({
  mainnet: { url: getFullnodeUrl("mainnet") },
  testnet: { url: getFullnodeUrl("testnet") },
});

<SuiClientProvider networks={networkConfig} defaultNetwork="testnet">
  {/* Your app */}
</SuiClientProvider>;

​
Network Configuration

Using official Sui RPC endpoints: 
import { getFullnodeUrl } from "@mysten/sui/client";

const { networkConfig } = createNetworkConfig({
  mainnet: { url: getFullnodeUrl("mainnet") },
  testnet: { url: getFullnodeUrl("testnet") },
  devnet: { url: getFullnodeUrl("devnet") },
  localnet: { url: getFullnodeUrl("localnet") },
});
Using custom RPC endpoints: 
const { networkConfig } = createNetworkConfig({
  mainnetCustom: {
    url: "https://your-custom-rpc.com",
  },
  testnetCustom: {
    url: "https://testnet-rpc.example.com",
  },
});

​
Available Networks

NetworkDescriptionURL
mainnetProduction networkhttps://fullnode.mainnet.sui.io:443
testnetTest network for developmenthttps://fullnode.testnet.sui.io:443
devnetDeveloper network (unstable)https://fullnode.devnet.sui.io:443
localnetLocal Sui nodehttp://127.0.0.1:9000
Devnet is reset frequently and should not be used for persistent testing. Use testnet for stable development.

​
3. WalletProvider

The WalletProvider manages wallet connection state and makes wallet functionality available to your app. 
import { WalletProvider } from "@mysten/dapp-kit";

<WalletProvider>{/* Your app */}</WalletProvider>;
Props (all optional): 
<WalletProvider
  // Sort these wallets to the top of the list
  preferredWallets={["Sui Wallet", "Suiet Wallet"]}
  // Filter which wallets to show
  walletFilter={(wallet) => wallet.name !== "Example Wallet"}
  // Enable unsafe burner wallet for testing
  enableUnsafeBurner={true}
  // Automatically reconnect to last used wallet
  autoConnect={true}
  // Customize storage for wallet state
  storage={window.localStorage}
  storageKey="sui-wallet-connection"
>
  {/* Your app */}
</WalletProvider>

​
WalletProvider Configuration Options

Type: string[]List of wallet names that should appear at the top of the wallet selection list.
preferredWallets={['Sui Wallet', 'Suiet Wallet', 'Ethos Wallet']}
Type: (wallet: Wallet) => booleanFunction to filter which wallets are available to users.
walletFilter={(wallet) => {
  // Only show wallets that support certain features
  return wallet.features.includes('sui:signAndExecuteTransaction');
}}
Type: booleanEnable a development-only burner wallet that generates a temporary keypair. Never use in production!
enableUnsafeBurner={process.env.NODE_ENV === 'development'}
Type: booleanAutomatically reconnect to the most recently used wallet when the app loads.
autoConnect={true} // Default: false
Type: Storage | nullStorage mechanism for persisting wallet connection. Set to null to disable persistence.
storage={window.localStorage} // Default
// or
storage={null} // Disable persistence
Type: stringThe key used to store wallet connection data.
storageKey = "my-dapp-wallet"; // Default: "sui-dapp-kit:wallet-connection-info"

​
Complete Example

Now integrate the Providers component into your Next.js layout:
src/app/layout.tsx
import type { Metadata } from "next";
import { Providers } from "@/components/providers";
import "./globals.css";

export const metadata: Metadata = {
  title: {
    default: "Workshop SUI - Frontend",
    template: "%s | Workshop SUI",
  },
  description:
    "Interactive workshop for building decentralized applications on the SUI blockchain. Learn to create modern Web3 frontends with Next.js and SUI dApp Kit.",

  authors: [
    {
      name: "Workshop SUI Team",
    },
  ],
  creator: "Workshop SUI Team",
  publisher: "Workshop SUI",
};

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body className="bg-background text-foreground bg-grid min-h-screen">
        <Providers>
          <main className="mx-2 sm:mx-8 md:mx-16 lg:mx-28 xl:mx-28 my-32">
            {children}
          </main>
        </Providers>
      </body>
    </html>
  );
}
That’s it! Your Next.js app now has all the Sui providers configured and ready to use.

​
Switching Networks

You can allow users to switch networks using the useSuiClientContext hook: 
import { useSuiClientContext } from "@mysten/dapp-kit";

function NetworkSwitcher() {
  const ctx = useSuiClientContext();

  return (
    <select
      value={ctx.network}
      onChange={(e) => ctx.selectNetwork(e.target.value)}
    >
      <option value="mainnet">Mainnet</option>
      <option value="testnet">Testnet</option>
      <option value="devnet">Devnet</option>
    </select>
  );
}

​
Next Steps

With providers configured, you’re ready to add wallet connection functionality to your app.

Connect Wallet

Add wallet connection with UI components