Migrating to RainbowKit and Wagmi v2

The wagmi and viem peer dependencies have reached 2.x.x with breaking changes.

Follow the steps below to migrate.

1. Upgrade RainbowKit, wagmi, and viem to their latest versions

npm i @rainbow-me/rainbowkit wagmi [email protected]

2. Install @tanstack/react-query peer dependency

With Wagmi v2, TanStack Query is now a required peer dependency.

Install it with the following command:

npm i @tanstack/react-query

3. Upgrade your RainbowKit and Wagmi configurations

  import '@rainbow-me/rainbowkit/styles.css'

+ import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
- import { createPublicClient, http } from 'viem'
- import { WagmiConfig } from 'wagmi'
+ import { WagmiProvider, http } from 'wagmi'
- import { configureChains, createConfig } from 'wagmi'
  import { mainnet } from 'wagmi/chains'
  import { RainbowKitProvider } from '@rainbow-me/rainbowkit'
- import { getDefaultWallets, connectorsForWallets } from '@rainbow-me/rainbowkit'
+ import { getDefaultConfig } from '@rainbow-me/rainbowkit'

  /* getDefaultWallets is now optional */
- const { wallets } = getDefaultWallets({
-   appName: 'RainbowKit demo',
-   projectId: 'YOUR_PROJECT_ID',
-   chains,
- })

  /* connectorsForWallets is now optional */
- const connectors = connectorsForWallets([...wallets])

- const { chains, publicClient } = configureChains( 
-   [mainnet, sepolia], 
-   [publicProvider(), publicProvider()],
- )

- const config = createConfig({
-   autoConnect: true,
-   publicClient,
- })

  /* New API that includes Wagmi's createConfig and replaces getDefaultWallets and connectorsForWallets */
+ const config = getDefaultConfig({
+   appName: 'RainbowKit demo',
+   projectId: 'YOUR_PROJECT_ID',
+   chains: [mainnet],
+   transports: {
+     [mainnet.id]: http(),
+   },
+ })

+ const queryClient = new QueryClient()

  const App = () => {
    return (
-     <WagmiConfig config={config}>
+     <WagmiProvider config={config}>
+       <QueryClientProvider client={queryClient}>
-         <RainbowKitProvider chains={chains}>
+         <RainbowKitProvider>
            {/* Your App */}
          </RainbowKitProvider>
+       </QueryClientProvider>
-     </WagmiConfig>
+     </WagmiProvider>
    )
  }

4. Check for breaking changes in wagmi and viem

If you use wagmi hooks and viem actions in your dApp, you will need to follow the migration guides for v2:

RainbowKit Changes

1. Improved behavior for EIP-6963 wallets

Wallets that support the new EIP-6963 connection standard (including Rainbow, MetaMask, and more) will now automatically appear in an Installed section during the Connect Wallet experience. This ensures that users can always find their favorite wallets and connect to dApps without conflicts or fallback buttons.

Developers continue to have full control over the Custom Wallet List to emphasize preferred wallets for end users. It is encouraged that you continue to include the injectedWallet and walletConnectWallet in your list to supports all platforms.

2. Wagmi configuration with getDefaultConfig

This new API simplifies the configuration experience and replaces the need to use Wagmi's createConfig directly. Chain configuration is simplified, including inferred public providers for transports.

The default wallet list will be automatically included, deprecating the need to use getDefaultWallets and connectorsForWallets.

You can create a Custom Wallet List by passing imported or Custom Wallet connectors to wallets. Instantiating wallet connectors and passing projectId and chains is no longer required.

const config = getDefaultConfig({
  appName: 'RainbowKit demo',
  projectId: 'YOUR_PROJECT_ID',
  chains: [mainnet],
  wallets: [rainbowWallet], /* optional custom wallet list */
  /* Wagmi createConfig options including `transports` are also accepted */
})

3. RainbowKitProvider

You no longer need to pass chains to <RainbowKitProvider>.

- <RainbowKitProvider chains={chains}>
+ <RainbowKitProvider>

4. Custom Chains

The Chain type has changed in accordance with Wagmi v2, and continues to support RainbowKit's iconUrl and iconBackground metadata.

+ import { Chain } from '@rainbow-me/rainbowkit'

  const avalanche = {
    id: 43_114,
    name: 'Avalanche',
    iconUrl: 'https://s2.coinmarketcap.com/static/img/coins/64x64/5805.png',
    iconBackground: '#fff',
    nativeCurrency: { name: 'Avalanche', symbol: 'AVAX', decimals: 18 },
    rpcUrls: {
      default: { http: ['https://api.avax.network/ext/bc/C/rpc'] },
    },
    blockExplorers: {
      default: { name: 'SnowTrace', url: 'https://snowtrace.io' },
    },
    contracts: {
      multicall3: {
        address: '0xca11bde05977b3631167028862be2a173976ca11',
        blockCreated: 11_907_934,
      },
    },
  } as const satisfies Chain

Example with getDefaultConfig:

const config = getDefaultConfig({
+ chains: [
+   avalanche, /* custom chain */
+   {
+     ...mainnet,
+     iconBackground: '#000',
+     iconUrl: 'https://example.com/icons/ethereum.png',
+   }, /* metadata overides */
+ ],
});

Example with createConfig:

+ import { Chain } from '@rainbow-me/rainbowkit'
+ const chains: readonly [Chain, ...Chain[]] = [
+   {
+     ...mainnet,
+     iconBackground: '#000',
+     iconUrl: 'https://example.com/icons/ethereum.png',
+   },
+ ];
  const config = createConfig({
    chains,
    transports: {
      [mainnet.id]: http(),
    },
  })

5. Custom Wallets

RainbowKit wallet connectors have undergone substantial changes to support Wagmi v2. Reference the updated docs and an example connector to upgrade any Custom Wallet Connectors in your dApp.

Wallet connectors also now support the EIP-6963 standard with the rdns prop. Ensure that this is populated to prevent duplicate references to EIP-6963 supporting wallets in your wallet list.

Please report any issues or feedback for RainbowKit v2 on GitHub here.